i cannot believe i just wiped out an entire night's worth of work.

docs/manual/user/ADVANCED.adoc

@@ -0,0 +1,14 @@
+== Advanced Customization
+If the <<the_code_build_ini_code_file,`build.ini`>> file doesn't provide enough customization to your liking, I don't blame you! It was designed only to provide the most basic control and is primarily only used to control the build process itself.
+
+Luckily, there are a lot of changes you can make. For all of these, you'll want to make a copy of the <<code_basedir_code,`basedir`>> directory somewhere and change the basedir configuration option in the <<the_code_build_ini_code_file,`build.ini`>> file to point to that directory.
+
+This section isn't going to cover every single use case, as that's mostly an exercise for you -- I can't predict how you want to use BDisk! But we'll cover some common cases you can use and in the process you'll know how to implement your own customizations.
+
+include::advanced/SSH.adoc[]
+include::advanced/VPN.adoc[]
+include::advanced/SOFTWARE.adoc[]
+include::advanced/BUILDING.adoc[]
+include::advanced/AUTOLOGIN.adoc[]
+include::advanced/DESKTOP.adoc[]
+

docs/manual/user/BUILDING.adoc

@@ -0,0 +1,13 @@
+== Building a BDisk ISO
+So you finally have <<the_code_build_ini_code_file,configured>> BDisk (and perhaps added further <<advanced_customization,customizations>>. Now you're ready to build!
+
+Building is, thankfully, the easiest part!
+
+NOTE: Due to requiring various mounting and chrooting, BDisk must be run as the *root* user (or via _sudo_).
+
+To initiate a build, simply run `<basedir>/bdisk/bdisk.py`. That's it! Everything should continue automatically.
+
+If you're using a packaged version you installed from your distro's package manager, you instead should run wherever it installs to. Most likely this is going to be `/usr/sbin/bdisk`. (On systemd build hosts that have done the https://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge/[/usr merge^], you can use `/usr/sbin/bdisk` or `/sbin/bdisk`.)
+
+If you encounter any issues during the process, make sure you read the documentation -- if your issue still isn't addressed, please be sure to file a <<bug_reports_feature_requests,bug report>>!
+

docs/manual/user/BUILDINI.adoc

@@ -0,0 +1,598 @@
+== The `build.ini` File
+This file is where you can specify some of the very basics of BDisk building. It allows you to specify/define certain variables and settings used by the build process. It uses https://docs.python.org/3/library/configparser.html[ConfigParser^] for the parsing engine, and you can do some https://wiki.python.org/moin/ConfigParserExamples[more advanced^] things with it than I demonstrate in the default.
+
+It's single-level, but divided into "sections". This is unfortunately a limitation of ConfigParser, but it should be easy enough to follow.
+
+Blank lines are ignored, as well as any lines beginning with `#` and `;`. There are some restrictions and recommendations for some values, so be sure to note them when they occur. Variables referencing other values in the `build.ini` are allowed in the format of `${value}` if it's in the same section; otherwise, `${section:value}` can be used.
+
+If you want to use your own `build.ini` file (and you should!), the following paths are searched in order. The first one found will be used.
+
+* `/etc/bdisk/build.ini`
+* `/usr/share/bdisk/build.ini`
+* `/usr/share/bdisk/extra/build.ini`
+* `/usr/share/docs/bdisk/build.ini`
+* `/usr/local/etc/bdisk/build.ini`
+* `/usr/local/share/docs/bdisk/build.ini`
+* `/opt/dev/bdisk/build.ini`
+* `/opt/dev/bdisk/extra/build.ini`
+* `/opt/dev/bdisk/extra/dist.build.ini`
+
+We'll go into more detail for each section below.
+
+=== Example
+ [bdisk]
+ name = BDISK
+ uxname = bdisk
+ pname = BDisk
+ ver =
+ dev = A Developer
+ email = dev@domain.tld
+ desc = A rescue/restore live environment.
+ uri = https://domain.tld
+ root_password =
+ user = yes
+ [user]
+ username = ${bdisk:uxname}
+ name = Default user
+ password = $$6$$t92Uvm1ETLocDb1D$$BvI0Sa6CSXxzIKBinIaJHb1gLJWheoXp7WzdideAJN46aChFu3hKg07QaIJNk4dfIJ2ry3tEfo3FRvstKWasg/
+ [build]
+ mirror = mirror.us.leaseweb.net
+ mirrorproto = https
+ mirrorpath = /archlinux/iso/latest/
+ mirrorfile =
+ mirrorchksum = ${mirrorpath}sha1sums.txt
+ mirrorgpgsig =
+ gpgkey = 7F2D434B9741E8AC
+ gpgkeyserver =
+ gpg = no
+ dlpath = /var/tmp/${bdisk:uxname}
+ chrootdir = /var/tmp/chroots
+ basedir = /opt/dev/bdisk
+ isodir = ${dlpath}/iso
+ srcdir = ${dlpath}/src
+ prepdir = ${dlpath}/temp
+ archboot = ${prepdir}/${bdisk:name}
+ mountpt = /mnt/${bdisk:uxname}
+ multiarch = yes
+ ipxe = no
+ i_am_a_racecar = no
+ [gpg]
+ mygpgkey =
+ mygpghome =
+ [sync]
+ http = no
+ tftp = no
+ git = no
+ rsync = no
+ [http]
+ path = ${build:dlpath}/http
+ user = http
+ group = http
+ [tftp]
+ path = ${build:dlpath}/tftpboot
+ user = root
+ group = root
+ [ipxe]
+ iso = no
+ uri = https://domain.tld
+ ssldir = ${build:dlpath}/ssl
+ ssl_ca = ${ssldir}/ca.crt
+ ssl_cakey = ${ssldir}/ca.key
+ ssl_crt = ${ssldir}/main.crt
+ ssl_key = ${ssldir}/main.key
+ [rsync]
+ host =
+ user =
+ path =
+ iso = no
+
+=== `[bdisk]`
+This section controls some basic branding and information having to do with the end product.
+
+==== `name`
+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:
+
+. Alphanumeric only
+. 8 characters total (or less)
+. No whitespace
+. ASCII only
+. Will be converted to uppercase if it isn't already
+
+==== `uxname`
+This value is used for filenames and the like. I highly recommend it be the same as `<<code_name_code,name>>` (in lowercase) but it doesn't need to be. It also has some rules:
+
+. Alphanumeric only
+. No whitespace
+. ASCII only
+. Will be converted to lowercase if it isn't already
+
+==== `pname`
+This string is used for "pretty-printing" of the project name; it should be a more human-readable string.
+
+. *Can* contain whitespace
+. *Can* be mixed-case, uppercase, or lowercase
+. ASCII only
+
+==== `ver`
+The version string. If this isn't specified, we'll try to guess based on the current git commit and tags in `<<code_basedir_code,build:basedir>>`.
+
+. No whitespace
+
+==== `dev`
+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 `<<code_pname_code,pname>>` apply.
+
+. *Can* contain whitespace
+. *Can* be mixed-case, uppercase, or lowercase
+. ASCII only
+
+==== `email`
+An email address to use for git syncing messages, and/or GPG key generation.
+
+==== `desc`
+What this distribution/project is used for.
+
+. *Can* contain whitespace
+. *Can* be mixed-case, uppercase, or lowercase
+. ASCII only
+
+==== `uri`
+What is this project's URI (website, etc.)? Alternatively, your personal site, your company's site, etc.
+
+. Should be a valid URI understood by curl
+
+
+==== `root_password`
+The escaped, salted, hashed string to use for the root user.
+
+Please see <<passwords,the section on passwords>> for information on this value. In the <<example,example above>>, the string `$$6$$t92Uvm1ETLocDb1D$$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.
+
+==== `user`
+*Default: no*
+
+This setting specifies if we should create a regular (non-root) user in the live environment. See the section <<code_user_code_2,`[user]`>> for more options.
+
+NOTE: If enabled, this user has full sudo access.
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================
+
+=== `[user]`
+This section of `build.ini` controls aspects about `bdisk:user`. It is only used if <<code_user_code,`bdisk:user`>> is enabled.
+
+==== `username`
+What username should the user have? Standard *nix username rules apply:
+
+. ASCII only
+. 32 characters or less
+. Alphanumeric only
+. Lowercase only
+. No whitespace
+. Cannot start with a number
+
+==== `name`
+What comment/description/real name should be used for the user? For more information on this, see the https://linux.die.net/man/5/passwd[passwd(5) man page^]'s section on *GECOS*.
+
+. ASCII only
+
+==== `password`
+The escaped, salted, hashed string to use for the non-root user.
+
+Please see <<passwords,the section on passwords>> for information on this value. In the <<example,example above>>, the string `$$6$$t92Uvm1ETLocDb1D$$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.
+
+=== `[build]`
+This section controls some aspects about the host and things like filesystem paths, etc.
+
+==== `mirror`
+A mirror that hosts the bootstrap tarball. It is *highly* recommended you use an Arch Linux https://wiki.archlinux.org/index.php/Install_from_existing_Linux#Method_A:_Using_the_bootstrap_image_.28recommended.29[bootstrap tarball^] as the build process is highly specialized to this (but <<bug_reports_feature_requests,patches/feature requests>> are welcome for other built distros). You can find a list of mirrors at the bottom of Arch's https://www.archlinux.org/download/[download page^].
+
+. No whitespace
+. Must be accessible remotely/via a WAN-recognized address
+. Must be a domain/FQDN only; no paths (those come later!)
+
+==== `mirrorproto`
+What protocol should we use for the <<code_mirror_code,`mirror`>>?
+
+|======================
+^s|Must be (case-insensitive) one of: ^.^m|http ^.^m|https ^.^m|ftp
+|======================
+
+==== `mirrorpath`
+What is the path to the tarball directory on the <<code_mirror_code,`mirror`>>?
+
+. Must be a complete path (e.g. `/dir1/subdir1/subdir2`)
+. No whitespace
+
+==== `mirrorfile`
+What is the filename for the tarball found in the path specified in <<code_mirrorpath_code,`mirrorpath`>> ? If left blank, we will use the sha1 <<code_mirrorchksum_code,checksum>> file to try to guess the most recent file.
+
+==== `mirrorchksum`
+The path to a sha1 checksum file of the bootstrap tarball.
+
+. No whitespace
+. Must be the full path
+. Don't include the mirror domain or protocol
+
+==== `mirrorgpgsig`
+*[optional]* +
+*default: (no GPG checking done)* +
+*requires: <<optional,_gpg/gnupg_>>* +
+*requires: <<code_gpgkey_code,`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 <<code_mirrorfile_code,`mirrorfile`>>), BDisk will try to guess based on the file from the sha1 <<code_mirrorchksum_code,checksum>> file. Note that this must evaluate to a full URL. (e.g. `${mirrorproto}://${mirror}${mirrorpath}somefile.sig`)
+
+==== `gpgkey`
+*requires: <<optional,_gpg/gnupg_>>*
+
+What is a key ID that should be used to verify/validate the <<code_mirrorgpgsig_code,`mirrorgpgsig`>>?
+
+. Only used if <<code_mirrorgpgsig_code,`mirrorgpgsig`>> is set
+. Can be in "short" form (e.g. _7F2D434B9741E8AC_) or "full" form (_4AA4767BBC9C4B1D18AE28B77F2D434B9741E8AC_), with or without the _0x_ prefix.
+
+==== `gpgkeyserver`
+*default: blank (GNUPG-bundled keyservers)* +
+*requires: <<optional,_gpg/gnupg_>>*
+
+What is a valid keyserver we should use to fetch <<code_gpgkey_code,`gpgkey`>>?
+
+. Only used if <<code_mirrorgpgsig_code,`mirrorgpgsig`>> is set
+. The default (blank) is probably fine. If you don't specify a personal GPG config, then you'll most likely want to leave this blank.
+. If set, make sure it is a valid keyserver URI (e.g. `hkp://keys.gnupg.net`)
+
+==== `gpg`
+Should we sign our release files? See the <<code_gpg_code_2,`[gpg]`>> section.
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================
+
+==== `dlpath`
+Where should the release files be saved? Note that many other files are created here as well.
+
+WARNING: If you manage your project in git, this should not be checked in as it has many large files that are automatically generated!
+
+. No whitespace
+. Will be created if it doesn't exist
+
+==== `chrootdir`
+Where the bootstrap tarball(s) extract to, where the chroots are built and prepped for filesystems on the live media.
+
+WARNING: If you manage your project in git, this should not be checked in as it has many large files that are automatically generated!
+
+. No whitespace
+. Will be created if it doesn't exist
+
+==== `basedir`
+Where your <<extra,`extra/`>> and <<overlay,`overlay/`>> directories are located. If you checked out from git, this would be your git worktree directory.
+
+. No whitespace
+. Must exist and contain the above directories populated with necessary files
+
+==== `isodir`
+This is the output directory of ISO files when they're created (as well as GPG signatures if you <<code_gpg_code,enabled them>>).
+
+WARNING: If you manage your project in git, this should not be checked in as it has many large files that are automatically generated!
+
+. No whitespace
+. Will be created if it doesn't exist
+
+==== `srcdir`
+This is where we save and compile source code if we need to dynamically build components (such as iPXE for mini ISOs).
+
+. No whitespace
+. Will be created if it doesn't exist (and is needed)
+
+==== `prepdir`
+This is the directory we use for staging.
+
+. No whitespace
+. Will be created if it doesn't exist
+
+==== `archboot`
+This directory is used to stage boot files.
+
+WARNING: This directory should not be the exact same path as other directives! If so, you will cause your ISO to be much larger than necessary. A subdirectory of another directive's path, however, is okay.
+
+. No whitespace
+. Will be created if it doesn't exist
+
+==== `mountpt`
+The path to use as a mountpoint.
+
+. No whitespace
+. Will be created if it doesn't exist
+
+==== `multiarch`
+*default: yes*
+
+Whether or not to build a "multiarch" image- that is, building support for both x86_64 and i686 in the same ISO.
+
+[options="header"]
+|======================
+s|In order to... 3+^|Accepts (case-insensitive) one of:
+s|build a multiarch ISO ^m|yes ^m|true ^m|1
+s|build a separate ISO for each architecture ^m|no ^m|false ^m|0
+s|only build an i686-architecture ISO ^m|i686 ^m|32 ^m|no64
+s|only build an x86_64-architecture ISO ^m|x86_64 ^m|64 ^m|no32
+|======================
+
+==== `ipxe`
+*default: no*
+
+Enable iPXE ("mini ISO") functionality.
+
+NOTE: This has no bearing on the <<code_sync_code,`[sync]`>> section, so you can create an iPXE HTTP preparation for instance without needing to sync it anywhere (in case you're building on the webserver itself).
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================
+
+==== `i_am_a_racecar`
+*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.
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================
+
+=== `[gpg]`
+This section controls settings for signing our release files. This is only used if <<code_gpg_code,`build:gpg`>> is enabled.
+
+==== `mygpgkey`
+A valid key ID that BDisk should use to _sign_ release files.
+
+. You will be prompted for a passphrase if your key has one/you don't have an open and authorized gpg-agent session. Make sure you have a working pinentry configuration set up!
+. If you leave this blank we will use the key we generate automatically earlier in the build process.
+. We will generate one if this is blank and you have selected sign as yes.
+
+==== `mygpghome`
+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`)
+
+=== `[sync]`
+This section controls what we should do with the resulting build and how to handle uploads, if we choose to use those features.
+
+==== `http`
+*default: no*
+
+If enabled, BDisk will generate/prepare HTTP files. This is mostly only useful if you plan on using iPXE. See the <<code_http_code_2,`[http]`>> section.
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================
+
+==== `tftp`
+*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.
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================
+
+==== `git`
+*requires: <<optional,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.
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================
+
+==== `rsync`
+*requires: <<optional,rsync>>* +
+*default: no*
+
+Enable rsync pushing for the ISO (and other files, if you choose- useful for iPXE over HTTP(S)).
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================
+
+=== `[http]`
+This section controls details about HTTP file preparation/generation. Only used if <<code_http_code,`sync:http`>> is enabled.
+
+==== `path`
+This directory is where to build an HTTP webroot.
+
+WARNING: MAKE SURE you do not store files here that you want to keep! They will be deleted!
+
+. No whitespace
+. If blank, HTTP preparation/generation will not be done
+. If specified, it will be created if it doesn't exist
+. Will be deleted first
+
+==== `user`
+What user the HTTP files should be owned as. This is most likely going to be either 'http', 'nginx', or 'apache'.
+
+. No whitespace
+. User must exist on build system
+
+|======================
+^s|Can be one of: ^.^m|username ^.^m|http://www.linfo.org/uid.html[UID]
+|======================
+
+==== `group`
+What group the HTTP files should be owned as. This is most likely going to be either 'http', 'nginx', or 'apache'.
+
+. No whitespace
+. Group must exist on build system
+
+|======================
+^s|Can be one of: ^.^m|group name ^.^m|https://linux.die.net/man/5/group[UID]
+|======================
+
+=== `[tftp]`
+This section controls details about TFTP file preparation/generation. Only used if <<code_tftp_code,`sync:tftp`>> is enabled.
+
+==== `path`
+The directory where we want to build a TFTP root.
+
+WARNING: MAKE SURE you do not store files here that you want to keep! They will be deleted!
+
+. No whitespace
+. Will be created if it doesn't exist
+. Will be deleted first
+
+==== `user`
+What user the TFTP files should be owned as. This is most likely going to be either 'tftp', 'root', or 'nobody'.
+
+. No whitespace
+. User must exist on build system
+
+|======================
+^s|Can be one of: ^.^m|username ^.^m|http://www.linfo.org/uid.html[UID]
+|======================
+
+==== `group`
+What group the TFTP files should be owned as. This is most likely going to be either 'tftp', 'root', or 'nobody'.
+
+. No whitespace
+. Group must exist on build system
+
+|======================
+^s|Can be one of: ^.^m|group name ^.^m|https://linux.die.net/man/5/group[UID]
+|======================
+
+=== `[ipxe]`
+This section controls aspects of iPXE building. Only used if <<code_ipxe_code,`build:ipxe`>> is enabled.
+
+==== `iso`
+*default: no* +
+*requires: <<optional,_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.
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================
+
+==== `uri`
+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 http://ipxe.org/scripting#dynamic_scripts[dynamic scripts^] for an example of the script that would be placed at this URI.
+
+NOTE: If you require HTTP BASIC Authentication or HTTP Digest Authentication (untested), you can format it via `https://user:password@bdisk.square-r00t.net/boot.php`.
+
+NOTE: This currently does not work for HTTPS with self-signed certificates.
+
+. *Required* if <<code_iso_code,`iso`>> is enabled
+
+==== `ssldir`
+Directory to hold SSL results, if we are generating keys, certificates, etc.
+
+. No whitespace
+. Will be created if it does not exist
+
+==== `ssl_ca`
+Path to the (root) CA certificate file iPXE should use. See http://ipxe.org/crypto[iPXE's crypto page^] for more information.
+
+NOTE: You can use your own CA to sign existing certs. This is handy if you run a third-party/"Trusted" root-CA-signed certificate for the HTTPS target.
+
+. No whitespace
+. Must be in PEM/X509 format
+. *Required* if <<code_iso_code,`iso`>> is enabled
+. If it exists, a matching key (ssl_cakey) *must* be specified
+.. However, if left blank/doesn't exist, one will be automatically generated
+
+==== `ssl_cakey`
+Path to the (root) CA key file iPXE should use.
+
+. No whitespace
+. Must be in PEM/X509 format
+. *Required* if <<code_iso_code,`iso`>> is enabled
+. If left blank or it doesn't exist (and <<code_ssl_ca_code,`ssl_ca`>> is also blank), one will be automatically generated
+. *Must* match/pair to <<code_ssl_ca_code,`ssl_ca`>> if specified/exists
+. MUST NOT be passphrase-protected/DES-encrypted
+
+==== `ssl_crt`
+Path to the _client_ certificate iPXE should use.
+
+. No whitespace
+. Must be in PEM/X509 format
+. *Required* if <<code_iso_code,`iso`>> is enabled
+. If specified/existent, a matching CA cert (<<code_ssl_ca_code,`ssl_ca`>>) and key (<<code_ssl_cakey_code,`ssl_cakey`>>) *must* be specified
+.. However, if left blank/doesn't exist, one will be automatically generated
+. *Must* be signed by <<code_ssl_ca_code,`ssl_ca`>>/<<code_ssl_cakey_code,`ssl_cakey`>> if specified and already exists
+
+==== `ssl_key`
+Path to the _client_ key iPXE should use.
+
+. No whitespace
+. Must be in PEM/X509 format
+. *Required* if <<code_iso_code,`iso`>> is enabled
+. If left blank/nonexistent (and <<code_ssl_ca_code,`ssl_ca`>> is also blank), one will be automatically generated
+
+=== `[rsync]`
+This section controls aspects of rsync pushing. Only used if <<code_rsync_code,`sync:rsync`>> is enabled.
+
+==== `host`
+The rsync destination host.
+
+. Must resolve from the build server
+. Can be host, FQDN, or IP address
+
+==== `user`
+This is the remote user we should use when performing the rsync push.
+
+. User must exist on remote system
+. SSH pubkey authorization must be configured
+. The destination's hostkey must be added to your local build user's known hosts
+
+==== `path`
+This is the remote destination path we should use for pushing via rsync.
+
+
+NOTE: You'll probably want to set <<code_user_code_3,`http:user`>> and <<code_group_code,`http:group`>> to what it'll need to be on the destination.
+
+. No whitespace
+. The path *must* exist on the remote host
+. The path MUST be writable by <<code_user_code_5,`user`>>
+
+==== `iso`
+Should we rsync over the ISO files too, or just the boot files?
+
+[options="header"]
+|======================
+2+^|Accepts (case-insensitive) one of:
+^m|yes ^m|no
+^m|true ^m|false
+^m|1 ^m|0
+|======================

docs/manual/user/GETTING_STARTED.adoc

@@ -0,0 +1,91 @@
+== Getting Started
+
+=== Downloading
+If it isn't in your distro's repositories (It *is* in Arch's AUR! Both https://aur.archlinux.org/packages/bdisk/[tagged release^] and https://aur.archlinux.org/packages/bdisk-git/[git master^].), you can still easily get rolling. Simply visit the project's https://git.square-r00t.net/BDisk/[source code web interface^] and download a tarball under the *Download* column:
+
+image::fig1.1.png[cgit,align="center"]
+
+If you know the tag of the commit you want, you can use curl:
+
+ curl -sL https://git.square-r00t.net/BDisk/snapshot/BDisk-4.0.0.tar.xz | tar -xf -
+
+or wget:
+
+ wget -O - https://git.square-r00t.net/BDisk/snapshot/BDisk-3.11.tar.xz | tar -xf -
+
+You can use `https://git.square-r00t.net/BDisk/snapshot/BDisk-master.tar.xz` for the URL if you want the latest working version. If you want a snapshot of a specific commit, you can use e.g. `https://git.square-r00t.net/BDisk/snapshot/BDisk-5ac510762ce00eef213957825de0e6d07186e7f8.tar.xz` and so on.
+
+Alternatively, you can use https://git-scm.com/[git^]. Git most definitely _should_ be in your distro's repositories.
+
+TIP: If you're new to git and want to learn more, I highly recommend the book https://git-scm.com/book/en/v2[Pro Git^]. It is available for free download (or online reading).
+
+You can clone via https:
+
+ git clone https://git.square-r00t.net/BDisk
+
+or native git protocol:
+
+ git clone git://git.square-r00t.net/bdisk.git BDisk
+
+The git protocol is much faster, but at a cost of lessened security.
+
+NOTE: I also have a mirror at https://github.com/johnnybubonic/BDisk[GitHub^], but I don't like GitHub very much and since it's a mirror repository, it's possible it will be out of date. For this reason, it's recommended that you use the resources above.
+
+=== Prerequisites
+This is a list of software you'll need available to build with BDisk.
+
+TIP: Your distro's package manager should have most if not all of these available, so it's unlikely you'll need to install from source.
+
+NOTE: Some versions may be higher than actually needed (especially _gcc_).
+
+CAUTION: You will need at least about *15GB* of free disk space, depending on what options you enable. Each architecture chroot (i.e. x86_64, i686) is about 3.5GB after a build using the default package set (more on that later), each architecture release tarball (what we use to build the chroots) is approximately 115MB each, and each squashed image per architecture is 1.1GB (if you use the default package set). If you don't understand what this means quite yet, don't worry- we'll go into more detail later on.  Just know that you'll need a fair bit of free disk space.
+
+==== Build Environment
+* GNU/Linux (relatively recent release of preferred distro)
+** Building on FreeBSD and other +*BSDs+ *may* be possible via the use of https://www.freebsd.org/doc/handbook/jails.html[jails^]. This is entirely untested and no support nor testing will be offered by the author (me). If you would like to offer documentation for this, please <<contact_the_author,contact me>>.
+** Building on Windows *may* be possible via the use of the https://docs.microsoft.com/en-us/windows/wsl/install-win10[WSL (Windows Subsystem for Linux)^]. This is entirely untested and no support nor testing will be offered by the author (me). If you would like to offer documentation for this, please <<contact_the_author,contact me>>.
+** Building on macOS is simply not supported, period, due to chroots being necessary to the build functionality of BDisk (and macOS not being able to implement GNU/Linux chroots). You'll need to run a build VM.
+* https://www.python.org/[Python^] (>=3.6)
+
+==== Necessary
+These are needed for using BDisk.
+
+* https://github.com/dosfstools/dosfstools[dosfstools^]
+* http://libburnia-project.org[libisoburn^]
+* http://squashfs.sourceforge.net[squashfs-tools^] (>=4.2)
+
+These are required Python modules:
+// TODO: double-check/update these.
+
+* https://pypi.python.org/pypi/humanize[Humanize^]
+* http://jinja.pocoo.org/[Jinja2^]
+* https://pypi.python.org/pypi/psutil[PSUtil^]
+* https://pypi.python.org/pypi/validators[Validators^]
+
+==== Optional
+While not strictly necessary, these will greatly enhance your BDisk usage. I've included some reasons why you might want to install them.
+
+NOTE: If you do not wish to install any of these or cannot install them, be sure to disable the relevant options in the `build.ini` file (we'll talk about that later). The default `extra/dist.build.ini` should be sane enough to not require any of these.
+
+* http://gcc.gnu.org[gcc (multilib)^] (>=6.x)
+** Needed for building iPXE.
+* http://gcc.gnu.org[gcc-libs (multilib)^] (>=6.x)
+** (Same as _gcc_.)
+* https://git-scm.com/[git^]
+** For autodetection of version, automatically making commits for your project, checking out source code, etc.
+* https://www.gnupg.org/[gpg/gnupg^] (>=2.1.11)
+** For automatically signing releases, verifying downloaded files from the Internet as part of the build process, etc. It's okay if you don't have a key set up!
+* https://rsync.samba.org/[rsync^]
+** For syncing built ISOs to a fileserver, syncing to a remote iPXE server, syncing to a traditional PXE/TFTP server, etc.
+
+These are optional Python modules:
+
+* https://pypi.python.org/pypi/GitPython[GitPython^]
+** (Same reasons as _git_)
+* https://pypi.python.org/pypi/pygpgme[PyGPGME^]
+** (Same reasons as _gpg/gnupg_)
+* https://pypi.python.org/pypi/patch[Patch^]
+** For branding iPXE environments per your `build.ini`.
+* https://pypi.python.org/pypi/pyOpenSSL[PyOpenSSL^]
+** To set up a PKI when building iPXE; used to create trusted/verified images.
+

docs/manual/user/IMPORTANT_CONCEPTS.adoc

@@ -0,0 +1,51 @@
+== Important Concepts
+If this is your first foray into building live distros, there are some terms and concepts we need to understand first. This will simplify the process later on.
+
+=== Terms
+An *operating system*, or OS, is what your programs (email client, web browser, etc.) run on.
+
+There are two basic types of booting systems that communicate between the *hardware* (the physical computer itself and its components) and the operating system: https://en.wikipedia.org/wiki/BIOS[*BIOS*^] (Basic Input/Output System) which has been around for quite some time and the newer https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface[*UEFI*^] (Unified Extensible Firmware Interface). Don't worry, you don't need to memorize what they're acronyms for and there won't be an exam -- just remember that BIOS is an older technology and UEFI is the newer one (and that they operate differently).
+
+*GNU/Linux*, sometimes just referred to as _Linux_ (And there is a difference between the terminologies, but it's nuanced. You are welcome to https://www.gnu.org/gnu/linux-and-gnu.en.html[read up on it^] though!), is an example of an operating system. Other examples include _Windows_, _macOS_ (previously _OS X_), _iOS_, _Android_, and a whole slew of others. There are many types of GNU/Linux offerings, called _distributions_, _flavors_, or _distros_.
+
+A *live distro*, *live CD*, *live DVD*, *live USB*, and the like are a way of booting an operating system without installing it on the hard drive- this means the computer doesn't even need a hard drive installed, or it doesn't matter if the installed operating system is broken. Typically they are Linux-based, but there are several Windows-based live releases out there (usually they're focused on rescuing broken Windows systems, so they're not very flexible).
+
+*Hybrid ISOs* are ISO files that can be burned to optical media (CDs, DVDs, etc.) and also be _dd_'d directly to a USB thumbdrive (for computers that support booting from USB). That means one file, multiple media types.
+
+*Architectures* are different hardware platforms. This mostly refers to the CPU. Common implementations are *64-bit* (also known as *x86_64* or *AMD64* for ones that support running both 64-bit and 32-bit software, or *IA64* or *Itanium* for processors that only support 64-bit) and *32-bit* (or *i686* and the older *i386* and *i486* implementations). Most consumer PCs on the market today are x86_64.
+
+*Chroots*, *chrooting*, and the like are variants on the word *chroot*. A *chroot* is a way of running a GNU/Linux install "inside" another GNU/Linux distro. It's sort of like a virtual machine, or VM, except that it's a lot more lightweight and it doesn't do any actual virtualization- and uses the host's kernel, memory mapping, etc. It's very useful for development of operating systems.
+
+*PXE*, or Pre-boot eXecution Environment, is a way of booting operating systems over a local network.
+
+*iPXE* is a http://ipxe.org/[project^] that builds a very small Linux kernel, UNDI (traditional PXE) images, and the like that allow you to essentially use PXE over the Internet. It's very flexible and customizable, and supports a custom scripting engine and such.
+
+=== Why live media is necessary/Why you might want BDisk
+"But Brent," I hear you ask in a voice which most likely is nothing close to what you actually sound like and entirely in my head, "Why would I need a live CD/USB/etc.? And why BDisk?"
+
+Elementary, my dear imaginary reader! I touch on some reasons why one might want live media in the beginning of the <<USER.adoc#user_manual,User Manual>>, but here's why you might want BDisk specifically as opposed to another live distro (or <<FAQ.adoc#i_don_t_like_bdisk_are_there_any_other_alternatives,live distro creator>>).
+
+* Fully customizable
+* Works with a multitude of GNU/Linux distros -- both for the host build system and as the guest. (Still under development!)
+* It performs optimizations and compression to help you get the smallest ISO possible.
+* In addition to building hybrid ISOs, it supports building iPXE hybrid ISOs (meaning you only need a very small file; the rest of the operating system boots over the Internet).
+* It supports both BIOS and UEFI systems- both the full image and the iPXE images.
+* It supports multiple architectures (x86_64, i686, possibly IA64 -- untested) on the same ISO.
+* It supports automatically syncing to a web mirror, PXE boot server, etc. via rsync upon successful build.
+* It supports SecureBoot (untested!).
+* It is 100% compatible with both the https://wiki.archlinux.org/index.php/installation_guide[Arch installation guide^] and the https://wiki.gentoo.org/wiki/Handbook:AMD64#Installing_Gentoo[Gentoo installation guide^].
+* It allows for non-interactive/automated building (i.e. nightly images).
+* It supports arbitrary file inclusion in a defined path on the ISO itself, not via some arbitrary directory as a separate partition on the media.
+* It can automatically build an accompanying "mini" ISO using iPXE -- which is also a hybrid, UEFI-supported ISO.
+* Automatic versioning based on git tags (optional).
+
+=== Who might want to use BDisk?
+* System builders/hardware testers
+* System Administrators/Engineers/Architects
+* Information Security professionals
+* Computer repair shops
+* Technology Consultants
+* Hobbyists
+* Home GNU/Linux users
+* Technology enthusiasts
+

docs/manual/user/PROJECT_LAYOUT.adoc

@@ -0,0 +1,81 @@
+== Project Structure
+The following is a tree of files and directories in a BDisk root directory. Note that yours may not look quite like this, as BDisk supports some directory relocation to aid in packaging for distros. These will be examined in-depth in the coming sections.
+
+ <BDisk root directory>
+ ├── bdisk
+ │   ├── bchroot.py
+ │   ├── bdisk.py
+ │   ├── bGPG.py
+ │   ├── bSSL.py
+ │   ├── bsync.py
+ │   ├── build.py
+ │   ├── host.py
+ │   ├── ipxe.py
+ │   └── prep.py
+ ├── docs
+ │   ├── COPYING
+ │   ├── LICENSE -> COPYING
+ │   ├── manual
+ │   │   └── (...)
+ │   ├── README
+ ├── examples
+ │   └── HTTP
+ │       └── (...)
+ ├── extra
+ │   ├── bdisk.png
+ │   ├── bin
+ │   │   └── (...)
+ │   ├── dist.build.ini
+ │   ├── external
+ │   │   └── (...)
+ │   ├── mirrorlist
+ │   ├── pre-build.d
+ │   │   ├── (...)
+ │   │   ├── i686
+ │   │   │   └── (...)
+ │   │   └── x86_64
+ │   │       └── (...)
+ │   └── templates
+ │       ├── BIOS
+ │       │   ├── isolinux.cfg.arch.j2
+ │       │   └── isolinux.cfg.multi.j2
+ │       ├── EFI
+ │       │   ├── base.conf.j2
+ │       │   ├── loader.conf.j2
+ │       │   ├── ram.conf.j2
+ │       │   ├── uefi1.conf.j2
+ │       │   └── uefi2.conf.j2
+ │       ├── GPG.j2
+ │       ├── iPXE
+ │       │   ├── BIOS
+ │       │   │   └── isolinux.cfg.j2
+ │       │   ├── EFI
+ │       │   │   ├── base.conf.j2
+ │       │   │   └── loader.conf.j2
+ │       │   ├── EMBED.j2
+ │       │   ├── patches
+ │       │   │   ├── 01.git-version.patch.j2
+ │       │   │   └── 02.banner.patch.j2
+ │       │   └── ssl
+ │       │       └── openssl.cnf
+ │       ├── overlay
+ │       │   ├── (...)
+ │       │   ├── i686
+ │       │   ├── x86_64
+ │       ├── pre-build.d
+ │       │   ├── (...)
+ │       │   ├── i686
+ │       │   ├── x86_64
+ │       ├── VARS.txt.j2
+ │       └── VERSION_INFO.txt.j2
+ └── overlay
+     ├── (...)
+     ├── i686
+     └── x86_64
+
+include::fslayout/BDISK.adoc[]
+include::fslayout/DOCS.adoc[]
+include::fslayout/EXAMPLES.adoc[]
+include::fslayout/EXTRA.adoc[]
+include::fslayout/OVERLAY.adoc[]
+

docs/manual/user/advanced/AUTOLOGIN.adoc

@@ -0,0 +1,10 @@
+=== Automatic Login (TTY)
+If you don't want to have to log into the TTY on boot, BDisk can automatically log in for you with a given username.
+
+If, for example, you want a terminal to auto-login on TTY1 with the root user, you would create the following file at `<basedir>/overlay/etc/systemd/system/getty@tty1.service.d/autologin.conf`: 
+
+ [Service]
+ Type=idle
+ ExecStart=
+ ExecStart=-/usr/bin/agetty --autologin root --noclear %I 38400 linux
+

docs/manual/user/advanced/BUILDING.adoc

@@ -0,0 +1,3 @@
+=== Changing the Build Process
+If you want to make modifications that can't be managed by arbitrary file inclusion or changing the software package lists, you may want to introduce additional changes to the image configuration that's run during the chroot. This is fairly easy to do. Simply modify `<basedir>/extra/pre-build.d/root/pre-build.sh` with the changes you desire. Note that this has a `.sh` file extension, but it can be any type of script you want -- Bash, Perl, Python, etc. -- it just needs the shebang line at the beginning of the script.
+

docs/manual/user/advanced/DESKTOP.adoc

@@ -0,0 +1,30 @@
+=== Starting a Desktop Environment
+You can install any desktop environment or window manager you would like via <<changing_the_installed_software,package lists>>! From there, it's simply a matter of setting the correct Systemd unit to start automatically. The https://wiki.archlinux.org/index.php/[Arch wiki^] has a lot of useful information here. As an example, I'll include http://lxde.org/[LXDE^] instructions here.
+
+Simply create a symlink for the target. In the `<basedir>/overlay/etc/systemd/system/` directory:
+
+ ln -s /usr/lib/systemd/system/lxdm.service display-manager.service
+
+==== Autologin (LXDE)
+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`:
+
+ [base]
+ autologin=bdisk
+ greeter=/usr/lib/lxdm/lxdm-greeter-gtk
+ [server]
+ arg=/usr/bin/X -background vt1
+ [display]
+ gtk_theme=Adwaita
+ bottom_pane=1
+ lang=1
+ keyboard=0
+ theme=Industrial
+ [input]
+ [userlist]
+ disable=0
+ white=
+ black=
+
+LXDE will then automatically log in with the user `bdisk` (note the second line, right under `[base]`) whenever started.

docs/manual/user/advanced/SOFTWARE.adoc

@@ -0,0 +1,20 @@
+=== Changing the Installed Software
+BDisk comes with a large https://bdisk.square-r00t.net/packages/[list of software^] installed in the build instance by default, ranging from data recovery (such as _foremost_, _scalpel_, _ddrescue_, etc.), security and data wiping (_nwipe_, _scrub_, etc.), penetration testing (_wifite_, _aircrack-ng_, etc.) and a slew of others. Seriously, if you're looking for a tool, changes are it's on it.
+
+However, this leads to a fairly long build time- even with a local repository mirror (many of the packages are from the AUR). You may want to replace the list with a smaller subset.
+
+The `iso.pkgs.\*` files are not files you should modify- they contain software necessary to the building of BDisk and are the basic necessary files to build a bootable image. However, the `packages.*` files are where you would add or remove software to be installed.
+
+NOTE: The package lists can contain both https://www.archlinux.org/packages/[Arch repository packages^] *and* https://aur.archlinux.org/[AUR^] packages.
+
+NOTE: Blank lines are ignored, and you can comment out lines by prefixing the line with the `#` character.
+
+==== `<basedir>/extra/pre-build.d/i686/root/packages.arch`
+This list contains packages to *only* be installed for the i686 image.
+
+==== `<basedir>/extra/pre-build.d/x86_64/root/packages.arch`
+This list contains packages you *only* want installed in the x86_64 image.
+
+==== `<basedir>/extra/pre-build.d/root/packages.both`
+This file contains packages for both architectures (i686 and x86_64).
+

docs/manual/user/advanced/SSH.adoc

@@ -0,0 +1,74 @@
+=== SSH Pubkey Authentication
+To start with, you'll want to secure SSH a little more than normal.
+
+I highly recommend https://stribika.github.io/2015/01/04/secure-secure-shell.html[this article^], which we'll be following in this process.
+
+First, create a file: `<basedir>/overlay/etc/ssh/sshd_config` using the following. Comments and blank lines have been stripped out for brevity.
+
+ PermitRootLogin prohibit-password
+ HostKey /etc/ssh/ssh_host_ed25519_key
+ HostKey /etc/ssh/ssh_host_rsa_key
+ AuthorizedKeysFile	.ssh/authorized_keys
+ PasswordAuthentication no
+ PermitEmptyPasswords no
+ ChallengeResponseAuthentication no
+ UsePAM yes
+ PrintMotd no # pam does that
+ Subsystem	sftp	/usr/lib/ssh/sftp-server
+ KexAlgorithms curve25519-sha256@libssh.org,diffie-hellman-group-exchange-sha256
+ Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes128-gcm@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr
+ MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com,hmac-ripemd160-etm@openssh.com,umac-128-etm@openssh.com,hmac-sha2-512,hmac-sha2-256,hmac-ripemd160,umac-128@openssh.com
+
+We'll also want to implement a more secure `ssh_config` file to avoid possible leaks. The following is `<basedir>/overlay/etc/ssh/ssh_config`:
+
+ Host *
+     KexAlgorithms curve25519-sha256@libssh.org,diffie-hellman-group-exchange-sha256
+     PasswordAuthentication no
+     ChallengeResponseAuthentication no
+     PubkeyAuthentication yes
+     HostKeyAlgorithms ssh-ed25519-cert-v01@openssh.com,ssh-rsa-cert-v01@openssh.com,ssh-ed25519,ssh-rsa
+     Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes128-gcm@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr
+     MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com,hmac-ripemd160-etm@openssh.com,umac-128-etm@openssh.com,hmac-sha2-512,hmac-sha2-256,hmac-ripemd160,umac-128@openssh.com
+
+We'll want to create our own moduli. This can take a long time, but only needs to be done once -- it doesn't need to be done for every build. The following commands should be run in `<basedir>/overlay/etc/ssh/`:
+
+ ssh-keygen -G moduli.all -b 4096
+ ssh-keygen -T moduli.safe -f moduli.all
+ mv moduli.safe moduli
+ rm moduli.all
+
+Then we generate hostkeys. This isn't strictly necessary as the live media will create them automatically when starting SSH if they're missing, but this does provide some verification that the host you're SSHing to is, in fact, running the BDisk instance that you yourself built. The following commands should be run in `<basedir>/overlay/etc/ssh/`:
+
+ ssh-keygen -t ed25519 -f ssh_host_ed25519_key -N "" < /dev/null
+ ssh-keygen -t rsa -b 4096 -f ssh_host_rsa_key -N "" < /dev/null
+
+Make sure you have keys on your host workstation generated so you can SSH into BDisk. If you don't have any ED25519 or RSA SSH keys, this will create them for you. The following should be run as the host (build machine, or what have you) user you want to be able to SSH into BDisk as:
+
+ ssh-keygen -t ed25519 -o -a 100
+ ssh-keygen -t rsa -b 4096 -o -a 100
+
+The defaults are fine. Adding a password to your private key is not necessary, but recommended (though note that doing so will inhibit automated SSHing). You should now have in `~/.ssh/` the following files (assuming you kept the defaults above):
+
+ id_ed25519
+ id_ed25519.pub
+ id_rsa
+ id_rsa.pub
+
+WARNING: The files ending in *.pub* are _public_ -- they can be published anywhere. However, the ones that are not appended with *.pub* are your _private keys_ and should not be shared with anyone, whether they're password-protected or not!
+
+Now you'll want to get the public key of your SSH keys so you can add them to your BDisk build. The following commands should be run in `<basedir>/overlay/`:
+
+ mkdir -p root/.ssh
+ chmod 700 root/.ssh
+ touch root/.ssh/authorized_keys
+ chmod 600 root/.ssh/authorized_keys
+ cat ~/.ssh/id_{ed25519,rsa}.pub > root/.ssh/authorized_keys
+
+If you decided to <<code_user_code,enable a regular non-root user>> in your build, you'll want to perform the same steps above for the regular user as well (or forego the above and just enable SSH for the user you create). Remember to replace `root/` with `home/<<_code_username_code,<username>>>/`!
+
+Lastly, we need to enable SSH to start on boot. Run the following command in `<basedir>/overlay/etc/systemd/system/multi-user.target.wants/`:
+
+ ln -s /usr/lib/systemd/system/sshd.service sshd.service
+
+You should now have SSH automatically start once the instance boots.
+

docs/manual/user/advanced/VPN.adoc

@@ -0,0 +1,13 @@
+=== VPN Configuration
+For this example we'll set up an https://openvpn.net/[OpenVPN^] client to start automatically on boot.
+
+Setting up an OpenVPN server is outside the scope of this section, but there are a https://openvpn.net/index.php/open-source/documentation/howto.html[multitude^] of https://openvpn.net/index.php/open-source/documentation/examples.html[useful^] https://wiki.archlinux.org/index.php/OpenVPN[documentation^] https://wiki.gentoo.org/wiki/Openvpn[sources^] out there that will help you with that.
+
+However, once you have your client .ovpn file (in our example, we'll call it `client.ovpn`) you can add it to the build relatively easily.
+
+Copy `client.ovpn` as `<basedir>/overlay/etc/openvpn/client/client.conf` -- note the changed file extension. Then, in the `<basedir>/overlay/etc/systemd/system/multi-user.target.wants/` directory, issue these commands:
+
+ ln -s /usr/lib/systemd/system/openvpn-client\@.service openvpn-client\@client.service
+
+OpenVPN will then start on boot in the built BDisk instance.
+

docs/manual/user/fslayout/BDISK.adoc

@@ -0,0 +1,13 @@
+=== bdisk/
+This directory contains the "heart" of BDisk. It essentially is a Python module package. It contains several python "subpackages" split into different files that provide different functions for BDisk. Chances are you won't ever need to touch anything in here.
+
+* <<code_bchroot_py_code>>
+* <<code_bdisk_py_code>>
+* <<code_bgpg_py_code>>
+* <<code_bssl_py_code>>
+* <<code_bsync_py_code>>
+* <<code_build_py_code>>
+* <<code_host_py_code>>
+* <<code_ipxe_py_code>>
+* <<code_prep_py_code>>
+

docs/manual/user/fslayout/DOCS.adoc

@@ -0,0 +1,15 @@
+=== docs/
+This directory contains various documentation and other helpful text.
+
+==== COPYING
+This contains BDisk's license, the GPLv3.
+
+==== LICENSE
+This is simply a link to `COPYING`.
+
+==== manual/
+This directory contains the documentation source you're reading right now! It's written in http://asciidoc.org/[asciidoc^] (well, to be more precise it's written in/has some http://asciidoctor.org/[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.
+
+==== README
+This is a placeholder for common convention; it simply tells you to read the manual (and where to find it/build it).
+

docs/manual/user/fslayout/EXAMPLES.adoc

@@ -0,0 +1,3 @@
+=== examples/
+This directory contains example filesystem layouts for e.g. your webserver (for iPXE), or your PXE server via TFTP.
+

docs/manual/user/fslayout/EXTRA.adoc

@@ -0,0 +1,21 @@
+=== extra/
+This directory contains multiple "support files" for BDisk building.
+
+==== bdisk.png
+This file is used for bootloader graphics. If you change the name of the project, this can be named something different -- see <<code_uxname_code,the section on uxname>>.
+
+==== bin/
+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.
+
+==== dist.build.ini
+This is the "source-provided"/upstream example <<the_code_build_ini_code_file,`build.ini`>>. It will be sourced for any missing configuration options or the like.
+
+==== external/
+This directory contains external source code for use with extra features in BDisk that would otherwise be inconvenient to fetch and build dynamically.
+
+==== pkg.build.ini
+This is the recommended default <<the_code_build_ini_code_file,`build.ini`>> file for packagers of distro repositories to use when packaging BDisk for inclusion in a package manager.
+
+include::PREBUILD.adoc[]
+
+include::TEMPLATES.adoc[]

docs/manual/user/fslayout/OVERLAY.adoc

@@ -0,0 +1,13 @@
+=== overlay/
+This directory follows similar rules to the <<pre_build_d,pre-build.d/>> directory, except it is applied *after* the chroots are prepared (as it is designed to be user-centric rather than core functionality). We'll go more into this later in-depth, as this is where most of your customizations will be done.
+
+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 `overlay/etc/foo/bar.conf`.
+
+It follows the following structure:
+
+==== i686/
+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`.
+
+==== x86_64/
+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`.
+

docs/manual/user/fslayout/PREBUILD.adoc

@@ -0,0 +1,13 @@
+==== pre-build.d/
+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_2,`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:
+
+===== i686/
+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 `pre-build.d/i686/etc/a/b.conf`.
+
+===== x86_64/
+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 `pre-build.d/x86_64/etc/z/y.conf`.
+

docs/manual/user/fslayout/TEMPLATES.adoc

@@ -0,0 +1,48 @@
+==== templates/
+This directory contains dynamic templates used for dynamic configuration building and other such things. They are written in http://jinja.pocoo.org/[Jinja2^]. If you haven't used Jinja2 before, the http://jinja.pocoo.org/docs/dev/templates/[templating documentation^] will prove to be very useful.
+
+This allows you to customize low-level behaviour of BDisk without modifying the source.
+
+===== BIOS/
+The `isolinux.cfg.arch.j2` template controls boot options for the single-arch versions of BDisk. In other words if you only build an i686 or only an x86_64 version, this is the template that would be used for BIOS boot mode.
+
+The `isolinux.cfg.multi.j2` is used for multi-arch. It manages booting for both i686 and x86_64 versions.
+
+These files will let you change the behaviour of booting in BIOS systems. The menu colour, the menu entries, the menu default, etc.
+
+===== EFI/
+The files in here are https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/[systemd-boot^] configurations. The distributed defaults are:
+
+`base.conf.j2`, which controls the "main"/default entry.
+
+`loader.conf.j2`, the meta configuration file which tells the loader which entry to load by default and which entries to include.
+
+`ram.conf.j2` which allows BDisk to run entirely from RAM.
+
+`uefi1.conf.j2` which provides a UEFI shell (for older UEFI systems).
+
+`uefi2.conf.j2` which provides a UEFI shell (for newer UEFI systems).
+
+===== GPG.j2
+This file contains default parameters for the https://www.gnupg.org/documentation/manuals/gnupg/Unattended-GPG-key-generation.html[GPG key generation], if we need to automatically generate a key.
+
+===== iPXE/
+This directory holds templates for iPXE/mini builds.
+
+The `BIOS/` directory is similar to <<bios, BIOS/>> mentioned above, but it only needs one configuration file and is a much more minimal design (since its entire purpose is to chainload to the iPXE loader).
+
+The `EFI/` directory is similar to <<efi, EFI/>> above also, but needs fewer configuration files (its only purpose is to bootstrap iPXE).
+
+`EMBED.j2` is the iPXE http://ipxe.org/scripting[embedded script^] (http://ipxe.org/embed[more info^]). This is what chainloads the remote resources (kernel, intird, squashed filesystem images, and so forth).
+
+The `patches/` directory largely control branding of the mini ISO. They are in https://www.gnu.org/software/diffutils/manual/html_node/Unified-Format.html[unified diff^] (or "patch") format.
+
+===== overlay/
+This directory contains *templated* overlays. These are intended to be templated by the user. See <<overlay, the overlay section>> for more information on how to use this. Remember to suffix your template files with the `.j2` extension.
+
+===== pre-build.d/
+This directory contains *templated* overlays. These are intended to not be managed by the user, as they handle configuration necessary for building an ISO. See <<pre_build_d, the pre-build.d section>> for more information on this.
+
+===== VERSION_INFO.txt.j2
+This template specifies a VERSION_INFO.txt file placed in various locations throughout the builds to help identify which version, build, etc. the ISO is.
+