whew! docs finished. 3.00 beta is DONE!

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[]
 

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()>>.
 

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>>.

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.

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>>.

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.

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()>>.

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>>.

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>>.

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

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.
 

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.