summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorr00t <bts@square-r00t.net>2016-12-30 19:57:34 -0500
committerr00t <bts@square-r00t.net>2016-12-30 19:57:34 -0500
commit32638dbdffb79839fdd1699ae0d970b91612e40f (patch)
tree46c85829cb0ee0ef8228201b80cf7a55d43ee318
parent17078f3d1d7a7ca7317777205988126540125886 (diff)
downloadBDisk-features.tar.xz
whew! docs finished. 3.00 beta is DONE!features
-rwxr-xr-xbdisk/prep.py8
-rw-r--r--docs/README202
-rw-r--r--docs/TODO35
-rw-r--r--docs/manual/dev/FUNCTIONS.adoc22
-rw-r--r--docs/manual/dev/functions/BCHROOT.adoc2
-rw-r--r--docs/manual/dev/functions/BGPG.adoc3
-rw-r--r--docs/manual/dev/functions/BSSL.adoc64
-rw-r--r--docs/manual/dev/functions/BSYNC.adoc26
-rw-r--r--docs/manual/dev/functions/BUILD.adoc43
-rw-r--r--docs/manual/dev/functions/HOST.adoc42
-rw-r--r--docs/manual/dev/functions/IPXE.adoc22
-rw-r--r--docs/manual/dev/functions/PREP.adoc52
-rw-r--r--docs/manual/user/IMPORTANT_CONCEPTS.adoc7
-rw-r--r--docs/manual/user/advanced/VPN.adoc4
-rw-r--r--docs/manual/user/fslayout/TEMPLATES.adoc4
l---------overlay/etc/systemd/system/multi-user.target.wants/openvpn-client@client.service1
16 files changed, 284 insertions, 253 deletions
diff --git a/bdisk/prep.py b/bdisk/prep.py
index d3357f0..b5a0e25 100755
--- a/bdisk/prep.py
+++ b/bdisk/prep.py
@@ -13,14 +13,14 @@ import host # bdisk.host
import bGPG # bdisk.bGPG
-def dirChk(config_dict):
+def dirChk(conf):
# Make dirs if they don't exist
for d in ('archboot', 'isodir', 'mountpt', 'srcdir', 'prepdir'):
- os.makedirs(config_dict['build'][d], exist_ok = True)
+ os.makedirs(conf['build'][d], exist_ok = True)
# Make dirs for sync staging if we need to
for x in ('http', 'tftp'):
- if config_dict['sync'][x]:
- os.makedirs(config_dict[x]['path'], exist_ok = True)
+ if conf['sync'][x]:
+ os.makedirs(conf[x]['path'], exist_ok = True)
def downloadTarball(conf):
build = conf['build']
diff --git a/docs/README b/docs/README
index 20d9a77..6e06b8a 100644
--- a/docs/README
+++ b/docs/README
@@ -1,200 +1,8 @@
-######################################################################################################################################
-##### BDisk #####
-##### #####
-##### Written by Brent Saner #####
-##### <bts@square-r00t.net> #####
-##### Built upon my (Brent's) 'BDisk' ISO-building framework (http://bdisk.square-r00t.net) #####
-######################################################################################################################################
+Please see the full documentation at https://bdisk.square-r00t.net
-!!!!!! WARNING !!!!!!!
-I do NOT recommend running this on a machine that is using wireless, as it will download a LOT of data.
-If you ignore this warning, be prepared to explain to anyone you share your wifi with why Facebook takes 20 seconds to load,
-because they WILL ask.
+Alternatively, you can compile the manual yourself (requires asciidoc and asciidoctor):
-It should be fine over ethernet, since hardware switches are much faster and efficient than a single duplex wireless radio.
+cd docs/manual
+asciidoctor -o /tmp/README.html HEAD.adoc
-Future versions, once this project has a dumping ground, will fetch highly compressed snapshotted chroot filesystems instead
-of dynamically building the entire install chroots (both x86_64 and i686) instead (with the option of building fresh locally,
-disabled by default).
-
-Maybe.
-
-Till then, sorry for the inconvenience.
-!!!!!!!!!!!!!!!!!!!!!!
-
-
-## Why Arch? ##
-Because it's a largely easy-to-use, well-documented (https://wiki.archlinux.org/) distro. It's no-frills and incredibly
-flexible/customizable, and can be made rather slim. It's also very friendly to run as a chroot inside any other distro.
-
-All commands below should be issued in the root working directory of this git repository. (For me, this is
-/opt/dev/work/BDisk but this may be entirely different for you, depending on where you cloned the repository to.)
-
-## Features ##
--Builds a hybrid ISO
- A hybrid ISO allows one to simply dd if=/path/to/file.iso of=/dev/<USB STICK> instead of using e.g. UNetBootin while also
- working with traditional optical media.
--Builds a dual-architecture ISO
- BDisk allows you to create both a 32-bit and 64-bit ISO, either separately or part of the same ISO, and customize each
- based on architecture.
--Supports both BIOS and UEFI booting in one ISO
- It can be difficult finding a live distribution that offers full UEFI support, which is frustrating if you're trying to
- install e.g. UEFI-enabled Gentoo, for instance. Not only does this ISO framework build support for both in the same ISO,
- but it also includes some UEFI shells as well.
--Arch install scripts
- This live distro, assuming default packages are kept, should be 100% compatible with the Arch install guide
- (https://wiki.archlinux.org/index.php/installation_guide).
--Allows for non-interactive runs, is git-friendly, logs all output while keeping the runtime output relatively sane, and allows
- the inclusion of arbitrary files in the finished filesystem.
--TFP/HTTP/PXE support
- It will automatically copy over some files to tftpboot/ and http/, greatly saving some time in PXE booting. It also
- supports, by default, booting PXE with HTTP fetching for the squashed filesystems. Say goodbye to NFS. You can even
- automatically rsync over after the build, if you wish, to your webserver (see sub-point)
- -Additionally, it supports iPXE if enabled in the configuration file. Please see examples/HTTP for an example of how to
- lay this out and what sort of directory hierarchy is needed.
--Automatic versioning based on git tags
-
-## Prerequisites ##
--At least ~20Gb disk space free (remember, you need room for not only four chroots (one developing and one staging for i686/x86_64),
-but also disk space for working, the finished ISO(s), etc.)
-
--The following packages installed on the build host:
-
-curl
-dosfstools
-libisoburn ("libisofs" on CentOS)
-lynx
-rsync
-sed
-squashfs-tools
-xorriso (in RPMForge repo for CentOS 7)
-xz
-
-and maybe a few others. The scripts run with set -e for the most part, so if something's missed, you'll know.
-Oh, you will know.
-
-If these packages are missing, they will be automatically installed. Currently, the following distros as host build systems
-are supported (assumes most recent release):
-
-Antergos
-Arch
-CentOS
-Debian
-Fedora
-Gentoo
-Mageia
-Manjaro
-openSUSE
-RHEL
-SUSE
-Ubuntu
-
-## Configuration ##
-See extra/build.conf.sample. Copy to <PROJECT ROOT>/build.conf if you wish to modify any of the values, otherwise the defaults
-will be used. I recommend enabling I_AM_A_RACECAR if you have the hardware for it, as it can speed things up greatly.
-The file should be well-commented.
-
-Also note the following files/paths:
-
--bin:
- The building/cleaning scripts.
---/build.sh:
- Supports several modes:
- bin/build.sh update Updates existing chroots (does an apacman -Syyu --devel, copies over fresh files from
- overlays, etc.)
- bin/build.sh chroot Chroots you into the runtime for any interactive tasks you may wish to run.
- bin/build.sh build (DEFAULT) Builds the chroots, ISO, etc.
- bin/build.sh all Same as bin/build.sh build
- bin/build.sh Same as bin/build.sh build
---/clean.sh:
- Supports several modes:
- bin/clean.sh all Clears everything out to a near-pristine working state. For convenience, it DOES NOT clear
- out build.conf.
- bin/clean.sh chroot Clears out only the working spaces, old ISOs, and the chroot directories. Hnady if you want to "start
- fresh" but still want to keep logs from earlier runs.
- bin/clean.sh squash Clears out only the working spaces and old ISOs. Useful if you're on a slow connection and would
- rather update the chroots instead of downloading filesystem snapshots again.
- bin/clean.sh Only clears workspaces and old ISOs.
---/mirror.lst.sh:
- Builds a fresh mirror list. Note that it is US based.
-
--docs:
- Documentation for BDisk.
---/COPYING:
- See LICENSE.
---/README:
- This file.
---/LICENSE:
- The license file.
---/FAQ:
- Several quick questions you might have.
---/TODO:
- Some features, bug fixes, etc. I have planned.
--examples:
- Included recommendation for how to lay things out, etc.
---/HTTP:
- Recommended layout for webserver layout if using iPXE.
--extra:
- Supporting files for the base building system (mirrorlist, etc.).
---/${UXNAME}.png:
-L A 640x480 8-bit RGBA colour PNG which will be used as the background for the bootsplash (if booting via BIOS and not UEFI)
---/bootstrap/apacman-*.tar.xz:
- An AUR-enabled package manager. Necessary for AUR support.
---/build.conf.sample:
- Sample/default config file. If you wish to override any settings, copy to <PROJECT ROOT>/build.conf and make your changes there.
- First run of the script will do this for you automatically.
---/mirrorlist:
- A set of default mirrorlists to be used for the chroots during building and runtime. Feel free to replace with your own
- mirrorlist (current list is speed-optimized for east coast US).
---/packages.32:
- A list of packages to install in the base system (32-bit runtime only).
---/packages.64:
- A list of packages to install in the base system (64-bit runtime only).
---/packages.both:
- A list of packages to install in the base system (these should be installed and are supported on both 64- AND 32-bit)
---/pre-build.d:
- Contains files injected into the system. Both 64-bit and 32-bit environments. Note: be sure to place them in hierarchical order
- (e.g. if you wish to have a file at /usr/foo/bar, you will need to place it in <PROJECT ROOT>/extra/pre-build.d/usr/foo/bar)
- (NOTE: Make sure all the packages you specify are valid package names. A mistyped or nonexistent package name will cause the chroot
- creation to break and everything else will break as a result.)
---/pre-build.d/32:
- Same as above, but only for 32-bit environments.
---/pre-build.d/64:
- You get the picture.
--http:
- Files to be hosted for PXE booting the environment go here. Set this as your root/DocumentRoot in nginx/Apache (or, ideally,
- copy over to a separate webserver). This directory is wiped out during any bin/clean.sh operation.
--lib:
- The "guts" of BDisk.
--logs:
- Here you can find full output of the runs. They are prefixed with run's PID number, and named after the function they occur in.
--overlay:
- These files are applied AFTER the initial setup of the chroots. Same hierarchy rules as extra/pre-build.d.
--src:
- Supporting source code/source code from other projects.
---ipxe/:
- For iPXE support.
---ipxe_local/:
- Various patches and supporting configs to tweak the iPXE build.
--tftpboot:
- Files to be served via TFTP for PXE booting. This directory is wiped out during any bin/clean.sh operation.
-
-
-You may notice other files come and go; they're mostly there for extra goodies/used to determine other things.
-
-## (Re)Building ##
-Building must be done as root, and on a supported distro (see Prerequisites for a list).
-
-# bin/build.sh
-
-Yeah. It's that easy. The finished product is in iso/.
-
-
-If you want more verbosity, check out the logs/ directory.
-
-
-## Submitting Patches ##
-If you have a fix or feature you'd like added, please follow the same pull request process for the kernel
-(https://www.kernel.org/doc/Documentation/SubmittingPatches) and email to bts@square-r00t.net
-
-Alternatively, file a bug at https://bugs.square-r00t.net/index.php?project=2 with a patch attached.
+Then point your browser to /tmp/README.html
diff --git a/docs/TODO b/docs/TODO
index 53455b7..5931a84 100644
--- a/docs/TODO
+++ b/docs/TODO
@@ -1,17 +1,9 @@
## Missing v2.x functionality ##
-i_am_a_racecar optimizations
--see also: grep -HnR bdisk/*.py
--TFTP, HTTP, RSYNC, git
--UPDATE THE README!
--sizes of build iso files
--GPG sigs on built files
+-incorporate this into the manual?
+-TFTP configs generated for pxelinux
-fix the branding, etc. on ipxe. :(
--fix links in docs. see the password generation section for bug :/ http://asciidoctor.org/docs/asciidoc-writers-guide/#cross-references
---http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#links
-add ipxe to full iso maybe?
-
-## General ##
-
-include benchmarking
-- http://sourceforge.net/projects/unixbench/
-- https://code.google.com/p/byte-unixbench/
@@ -24,25 +16,14 @@
-maybe remove lxde, firefox, chrome and replace with enlightenment/midori?
-custom repo? https://brainwreckedtech.wordpress.com/2013/01/27/making-your-own-arch-linux-repository/
--https://wiki.archlinux.org/index.php/Building_32-bit_packages_on_a_64-bit_system
---include arch repo clone script
-implement better "additional" packages list. specify for path in build.ini- these should be more easily changed by end users. DON'T TOUCH iso.pkgs.lst since those are necessary for booting.
-
-
-## NETWORKING ##
-
-shorewall/some other firewall?
--WISH: locked-down VPN?
-autodetection/configuration of network. DHCP is currently running by default, but does it need to support IPv6? if so, how would the user configure their network?
--SECURE SSH: https://stribika.github.io/2015/01/04/secure-secure-shell.html
-DISABLE NETWORKMANAGER AND "fi.w1.wpa_supplicant1"??? keeps spawning wpa_supplicant (and thusly killing networking proper)
--for netboot, custom user agent (should be defined by build.conf)
+-for netboot, custom user agent (should be defined by build.ini)
--iPXE's curl
--initrd's curl
-
-
-## Building ##
-
--WISH: Better logging[0]
+-WISH: Better logging/debugging
-WISH: signing for secureboot releases (PreLoader and loader.efi handle this okay, but require manual intervention)
-does loader.efi support splash backgrounds? can i implement that differently somehow?
--yes, see e.g. https://www.reddit.com/r/archlinux/comments/3bwgf0/where_put_the_splasharchbmp_to_splash_screen_boot/
@@ -63,16 +44,8 @@
--if it has mirror_SIG-X, set signature options e.g. _SIG-N would be "SigLevel = Never"
-iPXE background support. sed -rf "${BASEDIR}/src/ipxe_local/script.sed" ${SRCDIR}/ipxe/src/config/general.h ; sed -rf "${BASEDIR}/src/ipxe_local/script2.sed" ${SRCDIR}/ipxe/src/config/console.h
--note that iPXE VESAFB console is not (yet) supported in EFI, so this is on hold. check into this to see if it has changed.
-
-## Split into Separate Tools CD ##
-
-include WinMTR, build Mac OS X MTR for dist/tools on CD
-include pre-compiled LibreCrypt for opening LUKS parts on Windows (https://github.com/t-d-k/LibreCrypt)
--curl -s https://raw.githubusercontent.com/t-d-k/LibreCrypt/master/README.md | egrep 'InstallLibreCrypt_v[A-Za-z0-9\.]*.exe' | cut -f2 -d'"'
-__________________________________________________________
-FOOTNOTES:
-
-
-[0] Debugging mode would probably suffice for logging? Maybe? There are plenty of pythonic ways to do logging too.
diff --git a/docs/manual/dev/FUNCTIONS.adoc b/docs/manual/dev/FUNCTIONS.adoc
index c487ad2..e75c5ca 100644
--- a/docs/manual/dev/FUNCTIONS.adoc
+++ b/docs/manual/dev/FUNCTIONS.adoc
@@ -1,5 +1,5 @@
== Layout of BDisk functions
-These functions exist in <<_bdisk_,`bdisk/`>>
+These functions exist in <<_bdisk_,`bdisk/`>>.
include::functions/BCHROOT.adoc[]
@@ -10,23 +10,15 @@ It contains no functions, it just contains minimal logic to tie all the other fu
include::functions/BGPG.adoc[]
-=== `bSSL.py`
-Functions having to do with OpenSSL are stored here. This is used primarily for "mini" builds (via iPXE), they let you boot your BDisk distribution over the Internet. If an SSL key, CA certificate, etc. weren't defined and you want to build a mini image, this file contains functions that will build an SSL PKI (public key infrastructure) for you automatically.
+include::functions/BSSL.adoc[]
-=== `bsync.py`
-This file has functions relating to copying your BDisk build to various resources. For instance, if you want your ISO available to download then this file would be used to copy your finished build to an HTTP server/root you specify.
+include::functions/BSYNC.adoc[]
-=== `build.py`
-This is responsible for building the "full" ISO, building UEFI support, etc.
+include::functions/BUILD.adoc[]
-=== `host.py`
-These functions are used to perform "meta" tasks such as get information about the build host, find the `build.ini` file, and parse your configuration options.
-
-=== `ipxe.py`
-This file handles building the "mini" ISO via iPXE.
-
-=== `prep.py`
-This contains functions that download the base tarball releases, preps them for `bchroot.py`, builds necessary directory structures, and performs the overlay preparations.
+include::functions/HOST.adoc[]
+include::functions/IPXE.adoc[]
+include::functions/PREP.adoc[]
diff --git a/docs/manual/dev/functions/BCHROOT.adoc b/docs/manual/dev/functions/BCHROOT.adoc
index 9d54cdb..da87a28 100644
--- a/docs/manual/dev/functions/BCHROOT.adoc
+++ b/docs/manual/dev/functions/BCHROOT.adoc
@@ -25,5 +25,5 @@ See <<chrootdir>>.
This function performs some cleanup and optimizations to the chroot(s).
===== build
-A dictionary of <<code_build_code>>'s values (with some additional keys/values added). See (TODO: link to host.py's config parser).
+A dictionary of <<code_build_code>>'s values (with some additional keys/values added). See <<parseconfig_em_confs_em,parseConfig()>>.
diff --git a/docs/manual/dev/functions/BGPG.adoc b/docs/manual/dev/functions/BGPG.adoc
index 168642e..d5ae2cc 100644
--- a/docs/manual/dev/functions/BGPG.adoc
+++ b/docs/manual/dev/functions/BGPG.adoc
@@ -36,3 +36,6 @@ See <<conf>>.
==== delTempKeys(_conf_)
Delete automatically-generated keys (if we generated them) as well as the automatically imported verification key (<<code_gpgkey_code>>).
+
+===== conf
+See <<conf>>.
diff --git a/docs/manual/dev/functions/BSSL.adoc b/docs/manual/dev/functions/BSSL.adoc
new file mode 100644
index 0000000..fdfbbe2
--- /dev/null
+++ b/docs/manual/dev/functions/BSSL.adoc
@@ -0,0 +1,64 @@
+=== `bSSL.py`
+Functions having to do with OpenSSL are stored here. This is used primarily for "mini" builds (via iPXE), they let you boot your BDisk distribution over the Internet. If an SSL key, CA certificate, etc. weren't defined and you want to build a mini image, this file contains functions that will build an SSL PKI (public key infrastructure) for you automatically.
+
+==== verifyCert(_cert_, _key_, _CA_ = None)
+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).
+
+===== cert
+The certificate to be validated. Must be a PyOpenSSL certificate object.
+
+===== key
+The key to validate against <<cert>>. Must be a PyOpenSSL key object.
+
+===== CA
+The CA, or certificate authority, certificate to verify against.
+
+NOTE: This currently does not work, as PyOpenSSL does not currently support verifying against a specified CA certificate.
+
+==== sslCAKey(_conf_)
+This function imports a CA key (<<code_ssl_cakey_code>>) into a PyOpenSSL object (or generates one if necessary). Returns a PyOpenSSL key object.
+
+===== conf
+See <<conf>>.
+
+==== sslCA(_conf_, _key_ = None)
+This function imports a CA certificate (<<code_ssl_ca_code>>) into a PyOpenSSL object (or generates one if necessary). Returns a PyOpenSSL certificate object.
+
+===== conf
+See <<conf>>.
+
+===== key
+A PyOpenSSL key object that should be used to generate the CA certificate (or is paired to the CA certificate if specified).
+
+==== sslCKey(_conf_)
+This function imports a client key (<<code_ssl_key_code>>) into a PyOpenSSL object (or generates one if necessary). Returns a PyOpenSSL key object.
+
+===== conf
+See <<conf>>.
+
+==== ssslCSR(_conf_, _key_ = None)
+This function generates a CSR (certificate signing request).
+
+===== conf
+See <<conf>>.
+
+===== key
+A PyOpenSSL key object that should be used to generate the CSR. It should be a key that is paired to the client certificate.
+
+==== sslSign(_conf_, _ca_, _key_, _csr_)
+This function signs a CSR using a specified CA.
+
+===== conf
+See <<conf>>.
+
+===== ca
+A PyOpenSSL certificate object for the CA certificate. This certificate (object) should have signing capabilities.
+
+===== key
+A PyOpenSSL key object paired to <<ca_2>>.
+
+===== csr
+A PyOpenSSL CSR object. See <<ssslcsr_em_conf_em_em_key_em_none,sslCSR()>>.
+
+==== sslPKI(_conf_)
+Ties all the above together into one convenient function. Returns a PyOpenSSL certificate object of the signed client certificate. \ No newline at end of file
diff --git a/docs/manual/dev/functions/BSYNC.adoc b/docs/manual/dev/functions/BSYNC.adoc
new file mode 100644
index 0000000..78f4cf6
--- /dev/null
+++ b/docs/manual/dev/functions/BSYNC.adoc
@@ -0,0 +1,26 @@
+=== `bsync.py`
+This file has functions relating to copying your BDisk build to various resources. For instance, if you want your ISO available to download then this file would be used to copy your finished build to an HTTP server/root you specify.
+
+==== http(_conf_)
+This function prepares a *local* HTTP directory, or webroot. See <<code_http_code_2>>.
+
+===== conf
+See <<conf>>.
+
+==== tftp(_conf_)
+This function prepares a *local* TFTP directory (for traditional PXE). See <<code_tftp_code_2>>.
+
+===== conf
+See <<conf>>.
+
+==== git(_conf_)
+This function commits (and pushes) any changes you might have made to your project (<<code_basedir_code>>) automatically.
+
+===== conf
+See <<conf>>.
+
+==== rsync(_conf_)
+This function syncs your builds, HTTP directory (if enabled), TFTP directory (if enabled), etc. to a remote host. See <<code_rsync_code_2>>.
+
+===== conf
+See <<conf>>.
diff --git a/docs/manual/dev/functions/BUILD.adoc b/docs/manual/dev/functions/BUILD.adoc
new file mode 100644
index 0000000..cc3cb3d
--- /dev/null
+++ b/docs/manual/dev/functions/BUILD.adoc
@@ -0,0 +1,43 @@
+=== `build.py`
+This is responsible for building the "full" ISO, building UEFI support, etc.
+
+==== genImg(_conf_)
+This function builds the http://tldp.org/HOWTO/SquashFS-HOWTO/creatingandusing.html[squashed filesystem^] images and, <<code_gpg_code,if requested>>, signs them.
+
+===== conf
+See <<conf>>.
+
+==== genUEFI(_build_, _bdisk_)
+This function builds UEFI support for the ISO files. Returns the path of an embedded EFI bootable binary/ESP image.
+
+===== build
+The <<code_build_code,build section>> of the configuration.
+
+===== bdisk
+The <<code_bdisk_code,bdisk section>> of the configuration.
+
+==== genISO(_conf_)
+Builds the full ISO image(s). Returns a dictionary of information about the built ISO file (see <<iso>>).
+
+===== conf
+See <<conf>>.
+
+==== displayStats(_iso_)
+Parses the output of e.g. <<geniso_em_conf_em,genISO()>> and displays in a summary useful to the end-user.
+
+===== iso
+A dictionary of information about the ISO file. This is typically:
+
+ {'iso':
+ {'name':<'Main' for the full ISO, 'Mini' for the mini ISO, etc.>},
+ {<name>:
+ 'sha':<SHA256 sum of ISO file>,
+ 'file':<full/absolute path to ISO file>,
+ 'size':<size, in "humanized" format (e.g. #GB, #MB, etc.)>,
+ 'type':<Full or Mini>,
+ 'fmt':<human readable ISO type. e.g. Hybrid for an image that can be burned directly to a disk via dd or burned to optical media>
+ }
+ }
+
+==== cleanUp()
+Currently a no-op; this function is reserved for future usage to cleanup the build process automatically. \ No newline at end of file
diff --git a/docs/manual/dev/functions/HOST.adoc b/docs/manual/dev/functions/HOST.adoc
new file mode 100644
index 0000000..a7198ec
--- /dev/null
+++ b/docs/manual/dev/functions/HOST.adoc
@@ -0,0 +1,42 @@
+=== `host.py`
+These functions are used to perform "meta" tasks such as get information about the build host, find <<the_code_build_ini_code_file,the `build.ini` file>>, and parse your configuration options.
+
+==== getOS()
+Returns the distribution of the build host.
+
+==== getBits()
+Returns the "bitness" of the build host (e.g. `32bit` or `64bit`)
+
+==== getHostname()
+Returns the hostname of the build host.
+
+==== getConfig(_conf_file_ = '/etc/bdisk/build.ini')
+Returns a list of:
+
+. the default configuration file
+. the user-specified configuration file
+
+===== conf_file
+This is a full/absolute path that is searched first. If it exists and is a file, it is assumed to be the "canonical" <<the_code_build_ini_code_file,`build.ini` file>>.
+
+==== parseConfig(_confs_)
+This function parses the configuration file(s) and returns a list of:
+
+. A ConfigParser object
+. The configuration as a dictionary
+
+It performs some additional things, such as:
+
+* Converts "boolean" operations to true Python booleans
+* Tries to automatically detect the version if one isn't provided
+* Establishes the build number (this is a number that should be local to the build host)
+* Forms a list of the <<code_multiarch_code,architectures>> to build
+* Validates:
+** The bootstrap tarball mirror
+** The rsync destination (if <<code_rsync_code,enabled>>)
+** The iPXE remote URI (if <<code_ipxe_code,enabled>>)
+** That <<code_basedir_code>> is correctly set
+* Makes prerequisite directories
+
+===== confs
+A list of configuration files. See <<getconfig_em_conf_file_em_etc_bdisk_build_ini,getConfig()>>. \ No newline at end of file
diff --git a/docs/manual/dev/functions/IPXE.adoc b/docs/manual/dev/functions/IPXE.adoc
new file mode 100644
index 0000000..ee72faa
--- /dev/null
+++ b/docs/manual/dev/functions/IPXE.adoc
@@ -0,0 +1,22 @@
+=== `ipxe.py`
+This file handles building the "mini" ISO via iPXE.
+
+==== buildIPXE(_conf_)
+This function builds the iPXE core files.
+
+===== conf
+See <<conf>>.
+
+==== genISO(_conf_)
+This function builds the mini ISO (if <<code_iso_code,enabled>>). Returns a dictionary of information about the built ISO file (see <<iso>>).
+
+===== conf
+See <<conf>>.
+
+==== tftpbootEnv(_conf_)
+This function configures a TFTP boot/root directory for traditional PXE setups.
+
+NOTE: This function currently is a no-op; it will be implemented in future versions.
+
+===== conf
+See <<conf>>.
diff --git a/docs/manual/dev/functions/PREP.adoc b/docs/manual/dev/functions/PREP.adoc
new file mode 100644
index 0000000..be71025
--- /dev/null
+++ b/docs/manual/dev/functions/PREP.adoc
@@ -0,0 +1,52 @@
+=== `prep.py`
+This contains functions that download the base tarball releases, preps them for <<code_bchroot_py_code>>, builds necessary directory structures, and performs the overlay preparations.
+
+==== dirChk(_conf_)
+This function creates extra directories if needed.
+
+===== conf
+See <<conf>>.
+
+==== downloadTarball(_conf_)
+This function downloads the tarball (<<code_mirrorfile_code>>) from the <<code_mirror_code>>, and performs verifications (SHA1 and GPG signature <<code_mirrorgpgsig_code,if enabled>>). Returns the full/absolute path to the downloaded tarball.
+
+===== conf
+See <<conf>>.
+
+==== unpackTarball(_tarball_path_, _build_, _keep_ = False)
+This function extracts the tarball downloaded via <<downloadtarball_em_conf_em,downloadTarball()>>.
+
+===== tarball_path
+The full/absolute path to the downloaded tarball.
+
+===== build
+See <<build>>.
+
+===== keep
+`True` or `False`. Whether we should keep the downloaded tarball after unpacking/extracting. If your upstream tarball changes often enough, it's recommended to set this to `False`. However, setting it to `True` can speed up the build process if you're on a slower Internet connection.
+
+==== buildChroot(_conf_, _keep_ = False)
+This incorporates <<downloadtarball_em_conf_em,donwloading>> and <<unpacktarball_em_tarball_path_em_em_build_em_em_keep_em_false,extracting>> into one function, as well as applying the <<pre_build_d>> directory (and the <<pre_build_d_2,pre-build.d templates>>).
+
+===== conf
+See <<conf>>.
+
+===== keep
+See <<keep>>.
+
+==== prepChroot(_conf_)
+Returns a modified/updated <<build>>. This function:
+
+. Prepares some variables that <<changing_the_build_process,pre-build.sh>> needs inside the chroot(s)
+. Builds <<version_info_txt_j2,the VERSION_INFO.txt file>>
+. Updates the build number
+. Imports the <<code_mygpgkey_code,signing GPG key>>
+
+===== conf
+See <<conf>>.
+
+==== postChroot(_conf_)
+This function applies the <<overlay_2>> directory (and the <<overlay,overlay templates>>).
+
+===== conf
+See <<conf>>.
diff --git a/docs/manual/user/IMPORTANT_CONCEPTS.adoc b/docs/manual/user/IMPORTANT_CONCEPTS.adoc
index 4725859..cf7ae1a 100644
--- a/docs/manual/user/IMPORTANT_CONCEPTS.adoc
+++ b/docs/manual/user/IMPORTANT_CONCEPTS.adoc
@@ -32,7 +32,12 @@ Elementary, my dear imaginary reader! I touch on some reasons why one might want
* 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.
+* 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
diff --git a/docs/manual/user/advanced/VPN.adoc b/docs/manual/user/advanced/VPN.adoc
index dd0f498..b07cbbf 100644
--- a/docs/manual/user/advanced/VPN.adoc
+++ b/docs/manual/user/advanced/VPN.adoc
@@ -5,9 +5,9 @@ Setting up an OpenVPN server is outside the scope of this section, but there are
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.conf` -- note the changed file extension. Then, in the `<basedir>/overlay/etc/systemd/system/multi-user.target.wants/` directory, issue these commands:
+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\@.service openvpn\@client.service
+ ln -s /usr/lib/systemd/system/openvpn-client\@.service openvpn-client\@client.service
OpenVPN will then start on boot in the built BDisk instance.
diff --git a/docs/manual/user/fslayout/TEMPLATES.adoc b/docs/manual/user/fslayout/TEMPLATES.adoc
index 5abee1d..d036545 100644
--- a/docs/manual/user/fslayout/TEMPLATES.adoc
+++ b/docs/manual/user/fslayout/TEMPLATES.adoc
@@ -43,6 +43,6 @@ This directory contains *templated* overlays. These are intended to be templated
===== 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.txt.j2
-This template specifies a VERSION.txt file placed in various locations throughout the builds to help identify which version, build, etc. the ISO is.
+===== 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.
diff --git a/overlay/etc/systemd/system/multi-user.target.wants/openvpn-client@client.service b/overlay/etc/systemd/system/multi-user.target.wants/openvpn-client@client.service
new file mode 120000
index 0000000..8719131
--- /dev/null
+++ b/overlay/etc/systemd/system/multi-user.target.wants/openvpn-client@client.service
@@ -0,0 +1 @@
+/usr/lib/systemd/system/openvpn-client@.service \ No newline at end of file