These are needed for using BDisk.

These are required Python modules:

While not strictly necessary, these will greatly enhance your BDisk usage. I’ve included some reasons why you might want to install them.

This contains BDisk’s license, the GPLv3.

This is simply a link to COPYING.

This directory contains the documentation source you’re reading right now! It’s written in asciidoc (well, to be more precise it’s written in/has some asciidoctor-isms). I’d recommend reading the rendered version, as the source (while perfectly human-readable) is written in a very modular fashion so it may be inconvenient to read each source file and following include directives.

This is a placeholder for common convention; it simply tells you to read the manual (and where to find it/build it).

This file is used for bootloader graphics. If you change the name of the project, this can be named something different — see the section on uxname.

This directory contains sample code or extra tools that don’t have anything to do with BDisk normal operation but are useful in building a BDisk distribution.

This is the "source-provided"/upstream example build.ini. It will be sourced for any missing configuration options or the like.

This directory contains external source code for use with extra features in BDisk that would otherwise be inconvenient to fetch and build dynamically.

This is the recommended default build.ini file for packagers of distro repositories to use when packaging BDisk for inclusion in a package manager.

This file contains a "core" overlay. Generally these files shouldn’t be modified unless you know what you’re doing, but there are some interesting things you can do in here. Generally speaking, though, you’ll want to place your modifications in the overlay/ directory.

For files that should be included in both chroots, simply recreate the path with the desired file. For instance, if you want a file /etc/foo/bar.conf to exist in both i686 and x86_64 versions, it would exist as the path pre-build.d/etc/foo/bar.conf.

It follows the following structure:

This directory contains dynamic templates used for dynamic configuration building and other such things. They are written in Jinja2. If you haven’t used Jinja2 before, the templating documentation will prove to be very useful.

This allows you to customize low-level behaviour of BDisk without modifying the source.

This contains modifications that should be applied to the i686 version only. If you wanted a file to exist only in the i686 version at /etc/a/b.conf, it would be placed in overlay/i686/etc/a/b.conf.

This contains modifications that should be applied to the x86_64 version only. If you wanted a file to exist only in the x86_64 version at /etc/z/y.conf, it would be placed in overlay/x86_64/etc/z/y.conf.

This value is a "basic" name of your project. It’s not really shown anywhere end-user visible, but we need a consistent name that follows some highly constrained rules:

This value is used for filenames and the like. I highly recommend it be the same as name (in lowercase) but it doesn’t need to be. It also has some rules:

This string is used for "pretty-printing" of the project name; it should be a more human-readable string.

The version string. If this isn’t specified, we’ll try to guess based on the current git commit and tags in build:basedir. If build:basedir is not a git repository (i.e. you installed BDisk from a package manager), you MUST specify a version number.

The name of the developer or publisher of the ISO, be it an individual or organization. For example, if you are using BDisk to build an install CD for your distro, this would be the name of your distro. The same rules as pname apply.

An email address to use for git syncing messages, and/or GPG key generation.

What this distribution/project is used for.

What is this project’s URI (website, etc.)? Alternatively, your personal site, your company’s site, etc.

The escaped, salted, hashed string to use for the root user.

Please see the section on passwords for information on this value. In the example above, the string 6t92Uvm1ETLocDb1D$$BvI0Sa6CSXxzIKBinIaJHb1gLJWheoXp7WzdideAJN46aChFu3hKg07QaIJNk4dfIJ2ry3tEfo3FRvstKWasg/ is created from the password test. I cannot stress this enough, do not use a plaintext password here nor just use a regular /etc/shadow file/crypt(3) hash here. Read the section. I promise it’s short.

Default: no

This setting specifies if we should create a regular (non-root) user in the live environment. See the section [user] for more options.

What username should the user have? Standard *nix username rules apply:

What comment/description/real name should be used for the user? For more information on this, see the passwd(5) man page's section on GECOS.

What groups this user should be added to, comma-separated. They will be created if they don’t exist yet. Standard *nix group names rules apply:

The escaped, salted, hashed string to use for the non-root user.

Please see the section on passwords for information on this value. In the example above, the string 6t92Uvm1ETLocDb1D$$BvI0Sa6CSXxzIKBinIaJHb1gLJWheoXp7WzdideAJN46aChFu3hKg07QaIJNk4dfIJ2ry3tEfo3FRvstKWasg/ is created from the password test. I cannot stress this enough, do not use a plaintext password here nor just use a regular /etc/shadow file/crypt(3) hash here. Read the section. I promise it’s short.

A mirror that hosts the bootstrap tarball. It is highly recommended you use an Arch Linux bootstrap tarball as the build process is highly specialized to this (but patches/feature requests are welcome for other built distros). You can find a list of mirrors at the bottom of Arch’s download page.

What protocol should we use for the mirror?

What is the path to the tarball directory on the mirror?

What is the filename for the tarball found in the path specified in mirrorpath ? If left blank, we will use the hash checksum file to try to guess the most recent file.

[optional]
default: (no hash checking done)
requires: chksumtype

The path to a checksum file of the bootstrap tarball.

The algorithm that mirrorchksum's hashes are in.

[optional]
default: (no GPG checking done)
requires: gpg/gnupg
requires: gpgkey

If the bootstrap tarball file has a GPG signature, we can use it for extra checking. If it’s blank, GPG checking will be disabled.

If you specify just .sig (or use the default and don’t specify a mirrorfile), BDisk will try to guess based on the file from the hash checksum file. Note that unless you’re using the .sig "autodetection", this must evaluate to a full URL. (e.g. ${mirrorproto}://${mirror}${mirrorpath}somefile.sig)

requires: gpg/gnupg

What is a key ID that should be used to verify/validate the mirrorgpgsig?

default: blank (GNUPG-bundled keyservers)
requires: gpg/gnupg

What is a valid keyserver we should use to fetch gpgkey?

Should we sign our release files? See the [gpg] section.

Where should the release files be saved? Note that many other files are created here as well.

Where the bootstrap tarball(s) extract to, where the chroots are built and prepped for filesystems on the live media.

Where your extra/ and overlay/ directories are located. If you checked out from git, this would be your git worktree directory.

This is the output directory of ISO files when they’re created (as well as GPG signatures if you enabled them).

This is where we save and compile source code if we need to dynamically build components (such as iPXE for mini ISOs).

This is the directory we use for staging.

This directory is used to stage boot files.

The path to use as a mountpoint.

default: yes

Whether or not to build a "multiarch" image- that is, building support for both x86_64 and i686 in the same ISO.

default: no

Enable iPXE ("mini ISO") functionality.

default: no

This option should only be enabled if you are on a fairly powerful, multicore system with plenty of RAM. It will speed the build process along, but will have some seriously adverse effects if your system can’t handle it. Most modern systems should be fine with enabling it.

A valid key ID that BDisk should use to sign release files.

The directory should be used for the above GPG key if specified. Make sure it contains a keybox (.kbx) your private key. (e.g. /home/username/.gnupg)

default: no

If enabled, BDisk will generate/prepare HTTP files. This is mostly only useful if you plan on using iPXE. See the [http] section.

default: no

If enabled, BDisk will generate/prepare TFTP files. This is mostly only useful if you plan on using more traditional (non-iPXE) setups and regualar PXE bootstrapping into iPXE.

requires: git
default: no

Enable automatic Git pushing for any changes done to the project itself. If you don’t have upstream write/push access, you’ll want to disable this.

requires: rsync
default: no

Enable rsync pushing for the ISO (and other files, if you choose- useful for iPXE over HTTP(S)).

This directory is where to build an HTTP webroot.

What user the HTTP files should be owned as. This is most likely going to be either 'http', 'nginx', or 'apache'.

What group the HTTP files should be owned as. This is most likely going to be either 'http', 'nginx', or 'apache'.

The directory where we want to build a TFTP root.

What user the TFTP files should be owned as. This is most likely going to be either 'tftp', 'root', or 'nobody'.

What group the TFTP files should be owned as. This is most likely going to be either 'tftp', 'root', or 'nobody'.

default: no
requires: git

Build a "mini-ISO"; that is, an ISO file that can be used to bootstrap an iPXE environment (so you don’t need to set up a traditional PXE environment on your LAN). We’ll still build a full standalone ISO no matter what.

What URI iPXE’s EMBED script should use. This would be where you host an iPXE chainloading script on a webserver, for instance. See iPXE’s example of dynamic scripts for an example of the script that would be placed at this URI.

Directory to hold SSL results, if we are generating keys, certificates, etc.

Path to the (root) CA certificate file iPXE should use. See iPXE’s crypto page for more information.

Path to the (root) CA key file iPXE should use.

Path to the client certificate iPXE should use.

Path to the client key iPXE should use.

The rsync destination host.

This is the remote user we should use when performing the rsync push.

This is the remote destination path we should use for pushing via rsync.

Should we rsync over the ISO files too, or just the boot files?

This list contains packages to only be installed for the i686 image.

This list contains packages you only want installed in the x86_64 image.

This file contains packages for both architectures (i686 and x86_64).

Many desktop environments even offer an automatic login feature directly through the desktop manager (LXDM, in LXDE’s case).

Again, using LXDE as an example, create a file at <basedir>/overlay/etc/lxdm/lxdm.conf:

LXDE will then automatically log in with the user bdisk (note the second line, right under [base]) whenever started.

This function manages mounting the mountpoints for the chroot(s) in preparation for the images of the live media. It also runs the inner chroot preparation script. Returns chrootdir (same as the paramater provided).

Unmount the mounts set up in chroot().

This function performs some cleanup and optimizations to the chroot(s).

This function controls generating (or "importing" an existing) GnuPG key for use with other operations. Returns gpg, a PyGPGME object.

This function kills off any stale GnuPG agents running. Not doing so can cause some strange behaviour both during the build process and on the host.

This function signs a given file with the keys BDisk was either configured to use or automatically generated.

This function verifies a detatched signature against a file containing data. Returns True if the file verifies, or False if not.

Delete automatically-generated keys (if we generated them) as well as the automatically imported verification key ([code_gpgkey_code]).

This function will verify a certificate’s validity/pairing with a key, optionally against a given CA certificate. Returns True on successful verification, or False and an exit (for sanity purposes).

This function imports a CA key ([code_ssl_cakey_code]) into a PyOpenSSL object (or generates one if necessary). Returns a PyOpenSSL key object.

This function imports a CA certificate ([code_ssl_ca_code]) into a PyOpenSSL object (or generates one if necessary). Returns a PyOpenSSL certificate object.

This function imports a client key ([code_ssl_key_code]) into a PyOpenSSL object (or generates one if necessary). Returns a PyOpenSSL key object.

This function generates a CSR (certificate signing request).

This function signs a CSR using a specified CA.

Ties all the above together into one convenient function. Returns a PyOpenSSL certificate object of the signed client certificate.

This function prepares a local HTTP directory, or webroot. See [code_http_code_2].

This function prepares a local TFTP directory (for traditional PXE). See [code_tftp_code_2].

This function commits (and pushes) any changes you might have made to your project ([code_basedir_code]) automatically.

This function syncs your builds, HTTP directory (if enabled), TFTP directory (if enabled), etc. to a remote host. See [code_rsync_code_2].

This function builds the squashed filesystem images and, if requested, signs them.

This function builds UEFI support for the ISO files. Returns the path of an embedded EFI bootable binary/ESP image.

Builds the full ISO image(s). Returns a dictionary of information about the built ISO file (see iso).

Parses the output of e.g. genISO() and displays in a summary useful to the end-user.

Currently a no-op; this function is reserved for future usage to cleanup the build process automatically.

Returns the distribution of the build host.

Returns the "bitness" of the build host (e.g. 32bit or 64bit)

Returns the hostname of the build host.

Returns a list of:

This function parses the configuration file(s) and returns a list of:

It performs some additional things, such as:

This function builds the iPXE core files.

This function builds the mini ISO (if enabled). Returns a dictionary of information about the built ISO file (see iso).

This function configures a TFTP boot/root directory for traditional PXE setups.

This function creates extra directories if needed.

This function downloads the tarball ([code_mirrorfile_code]) from the [code_mirror_code], and performs verifications (SHA1 and GPG signature if enabled). Returns the full/absolute path to the downloaded tarball.

This function extracts the tarball downloaded via downloadTarball().

This incorporates donwloading and extracting into one function, as well as applying the pre-build.d/ directory (and the pre-build.d templates).

Returns a modified/updated [build]. This function:

This function applies the overlay/ directory (and the overlay templates).

Simply put a blank CD/DVD-R (or RW, RW+, etc.) in your optical media drive. Find where you downloaded the above file (it should be named bdisk-mini.iso). Right-click and select Burn disc image.

You’ll most likely want to download a program called USBWriter. Unzip it (or just open it via double-clicking) and copy the USBWriter.exe program somewhere you’ll remember- your desktop, for instance.

Next, make sure your USB thumbdrive is inserted in your computer and formatted/"initialized" already.

Now right-click on the USBWriter icon and select Run as administrator. You may get a warning pop up asking for permissions for USBWriter. It’s safe to click Yes.

Select the proper USB flash drive from the Target device dropdown menu. If your USB drive isn’t showing up, try clicking the Refresh button and looking again. (If it still doesn’t show up, you may need to reboot your computer.)

Click the Browse…​ button and find where you saved bdisk-mini.iso. Once you’ve found it, double-click it. Then click Write. It might take a little bit of time depending on how fast your USB interface is, so give it some time. When it finishes, click Close. You now have a bootable USB thumbdrive.

Booting differs depending on each and every hardware, but typically you should get a message when you first start up for "Setup" and/or "Boot options" or the like. The terminology differs here. It will probably be an F# button (usually F2, F4, F10, or F12) or the Delete key. While rebooting, try to hold or press repeatedly this key and you should come across an option somewhere with a list of devices to boot from or an order you can set. Make sure the USB (or CD/DVD, whichever media type you’re using) is set as first, and save.

Unfortunately, the OS X/macOS Disk Utility doesn’t work with hybrid ISOs (what bdisk-mini.iso is). At all. You’re out of luck, I’m afraid, unless you happen have a spare USB thumbdrive handy.

We’ll need to get a little messy with this one.

Open Applications ⇒ Utilities ⇒ Terminal. A black box should pop up.

Insert your USB thumbdrive now (if you haven’t already) and run the following command:

You should see an entry, probably near the bottom, that looks something like this:

Now that you’ve found which disk your USB device is (the /dev/disk# part), we can continue. Make sure that it is the disk ID right above the line that contains your flash drive size! For our example, I will use /dev/disk42 as an example as it’s highly unlikely you’ll have that many disk IDs, but be sure to replace this in the following commands with the proper disk ID you found above.

Then we need to unmount the disk, in case it’s already mounted.

Assuming you saved BDisk Mini to your Desktop, you can do:

This will run for a couple seconds. When it finishes, you should see something similar to (but not necessarily the same numbers as) this:

At this point you may get a popup warning you "The disk you inserted was not readable by this computer." If you do, just click the Ignore button.

One last step. Still in Terminal:

You can then close Terminal.

The instructions here don’t differ too much than from Windows, though it’s always the same key. From it being in a shutdown state, power on your Macbook Pro (or whatever it is you have) and hold the Option key (or the Alt key on non-Apple keyboards). The Option/Alt key should bring up a boot menu that will let you select a USB device to boot from.

Strangely enough, you should still be able to boot a BDisk Mini CD/DVD, you just can’t burn one. I’m tempted to make a cheap dig at Apple, but I’ll refrain.

Easy. Most (if not all) of these should support burning bdisk-mini.iso to disc (I’m partial to cdrecord). If you prefer a GUI, try some of these instead (I like k3b).

Very similar to OS X/macOS in approach. First open a terminal emulator- the ways of navigating to it depends on your window manager/desktop environment, but it’s usually under a System or Utilities menu.

Now we need to find which disk our USB thumbdrive is. Insert your USB thumbdrive now, if you haven’t already, and run in the terminal:

You should see a device matching your USB thumbdrive’s size. In our example, I use /dev/sdz as it’s unlikely you have that many disks attached to a system, but be sure to replace this in the following commands with the proper disk ID you find.

Make sure it isn’t mounted:

You should get a message that says umount: /dev/sdz: not mounted. If it was mounted before, it’s unmounted now.

Next, simply dd over the ISO file.

This will run for a couple seconds. When it finishes, you should see something similar to (but not necessarily the same numbers as) this:

If you get a popup from your desktop environment (assuming you’re using one) about not being able to mount a disk, or that it’s unformatted, etc. and it prompts you to format, ignore/cancel/close it- do not format it! This would erase the BDisk Mini image on it.

Exactly the same as those for Windows. (Unless you’re running GNU/Linux on Mac hardware, in which case follow the booting instructions for Mac instead.)

Part of the whois package, available in the AUR as debian-whois-mkpasswd.

The following Perl one-liner will generate a salted hash string (using the salt aBcDeFgHiJ):

Legacy GRUB ("GRUB v1") includes grub-crypt, which will let you generate a salted hash:

Create a script and mark it as executable with the following content:

Assuming you want to run the sync script every 6 hours and it is located at /root/bin/arch.repo.clone.sh, this is the cron entry you would use (crontab -e):

The first sync can take quite a while, but subsequent runs shouldn’t take more than five minutes or so.

You’ll need a way to serve this local mirror in a way pacman can understand. Luckily, it’s fairly easy. I recommend using nginx as it’s available by default in many operating systems. You can of course use others such as lighttpd, apache/httpd, etc. For the example configuration here, we’re going to use an nginx configuration file.

The configuration may vary according to your distribution’s provided nginx default configuration, but you’ll want this configuration to be served as the default (or set an appropriate server_name directive which you would then use in <basedir>/extra/pre-build.d/etc/pacman.d/mirrorlist).

You’ll then want to configure BDisk’s chroots to use your local mirror first. However, when doing so you run into an issue — in the built image, install operations will take longer than they need to because the local mirror likely won’t be available! This is a small issue as it’s unexpected that you’ll need to install software within the live environment, but I’ve run into cases where it was a necessity once or twice.

There is an easy workaround if you’re using libvirt — you can simply tell your build VM to resolve to the IP address of the box that is running the mirror for the same FQDN that the "preferred" "real" mirror on the Internet is and set that mirror at the top of <basedir>/extra/pre-build.d/etc/pacman.d/mirrorlist. However, that’s not always feasible- most notably if you’re building on a physical box and it’s the same host as the repository clone. In that case you can set the specific local resolution — e.g. http://127.0.0.1/ — at the top of <basedir>/extra/pre-build.d/etc/pacman.d/mirrorlist and then set a mirrorlist WITHOUT that entry in <basedir>/overlay/etc/pacman.d/mirrorlist. For more information on using these type of overrides, see Advanced Customization.

If you’re using the libvirt workaround, remember to configure nginx (or whatever you’re using) with a virtual host and location block that matches the "real", upstream mirror. In our example below, we use http://mirror.us.leaseweb.net/archlinux as the mirror.