From 17078f3d1d7a7ca7317777205988126540125886 Mon Sep 17 00:00:00 2001 From: r00t Date: Fri, 30 Dec 2016 00:09:24 -0500 Subject: [PATCH] documentation check-in... --- docs/manual/DEV.adoc | 2 +- docs/manual/FOOT.adoc | 16 +++++------ docs/manual/dev/FUNCTIONS.adoc | 30 ++++++++++++++++++-- docs/manual/dev/functions/BCHROOT.adoc | 29 ++++++++++++++++++++ docs/manual/dev/functions/BGPG.adoc | 38 ++++++++++++++++++++++++++ docs/manual/user/advanced/SSH.adoc | 4 +-- docs/manual/user/fslayout/BDISK.adoc | 35 ++++++------------------ 7 files changed, 114 insertions(+), 40 deletions(-) create mode 100644 docs/manual/dev/functions/BCHROOT.adoc create mode 100644 docs/manual/dev/functions/BGPG.adoc diff --git a/docs/manual/DEV.adoc b/docs/manual/DEV.adoc index e6c87a8..62a1a5f 100644 --- a/docs/manual/DEV.adoc +++ b/docs/manual/DEV.adoc @@ -2,7 +2,7 @@ [partintro] .What good is software if nobody changes it? -- -TODO. +BDisk can be sourced for other projects, as it's written in a modular manner. Future versions may support installation as a normal Python module. This will also provide information you may need to change parts of BDisk -- it *is* opensource, after all! -- include::dev/FUNCTIONS.adoc[] diff --git a/docs/manual/FOOT.adoc b/docs/manual/FOOT.adoc index 276d7ef..13ce12f 100644 --- a/docs/manual/FOOT.adoc +++ b/docs/manual/FOOT.adoc @@ -1,8 +1,8 @@ -[appendix] -= User Manual -[appendix] -= Developer Manual -[appendix] -= Netboot -[appendix] -= Bug Reports/Feature Requests \ No newline at end of file +//[appendix] +//= User Manual +//[appendix] +//= Developer Manual +//[appendix] +//= Netboot +//[appendix] +//= Bug Reports/Feature Requests \ No newline at end of file diff --git a/docs/manual/dev/FUNCTIONS.adoc b/docs/manual/dev/FUNCTIONS.adoc index 0a168d7..c487ad2 100644 --- a/docs/manual/dev/FUNCTIONS.adoc +++ b/docs/manual/dev/FUNCTIONS.adoc @@ -1,8 +1,32 @@ == Layout of BDisk functions -TODO. +These functions exist in <<_bdisk_,`bdisk/`>> -== Moar Functions -TODO. +include::functions/BCHROOT.adoc[] + +=== `bdisk.py` +This file is a sort of "wrapper" -- it pulls all the other files in this directory together into a single usable Python script. In other words, to build a BDisk distribution, you would simply run `bdisk/bdisk.py` -- that's it! See <>. + +It contains no functions, it just contains minimal logic to tie all the other functions together. + +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. + +=== `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. + +=== `build.py` +This is responsible for building the "full" ISO, building UEFI support, etc. + +=== `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. diff --git a/docs/manual/dev/functions/BCHROOT.adoc b/docs/manual/dev/functions/BCHROOT.adoc new file mode 100644 index 0000000..9d54cdb --- /dev/null +++ b/docs/manual/dev/functions/BCHROOT.adoc @@ -0,0 +1,29 @@ +=== `bchroot.py` +This file controls creation of the chroots -- the directories in which BDisk builds the actual system that is booted into. + +==== chroot(_chrootdir_, _chroot_hostname_, _cmd_ = '`/root/pre-build.sh`') +This function manages mounting the mountpoints for the chroot(s) in preparation for the images of the live media. It also runs <>. Returns `chrootdir` (same as the paramater provided). + +===== chrootdir +The directory where the filesystem tree for the chroot lies. Absolute path only. + +===== chroot_hostname +The hostname to use for the guest. + +NOTE: This paramater may be removed in future versions. + +===== cmd +The command to run inside the chroot once all the mountpoints are set up. + +==== chrootUnmount(_chrootdir_) +Unmount the mounts set up in <>. + +===== chrootdir +See <>. + +==== chrootTrim(_build_) +This function performs some cleanup and optimizations to the chroot(s). + +===== build +A dictionary of <>'s values (with some additional keys/values added). See (TODO: link to host.py's config parser). + diff --git a/docs/manual/dev/functions/BGPG.adoc b/docs/manual/dev/functions/BGPG.adoc new file mode 100644 index 0000000..168642e --- /dev/null +++ b/docs/manual/dev/functions/BGPG.adoc @@ -0,0 +1,38 @@ +=== `bGPG.py` +This contains functions having to do with GPG -- signing files, verifying other signatures, generating a key (if one wasn't specified), using a key (if one was specified), etc. + +==== genGPG(_conf_) +This function controls generating (or "importing" an existing) GnuPG key for use with other operations. Returns `gpg`, a <> object. + +===== conf +A dictionary of the <> (with some additional keys/values added). See (TODO: link to host.py's config parser). + +==== killStaleAgent(_conf_) +This function kills off any stale GnuPG agents running. Not doing so can cause some strange behaviour both during the build process and on the host. + +===== conf +See <>. + +==== signIMG(_path_, _conf_) +This function signs a given file with the keys BDisk was either configured to use or automatically generated. + +===== path +The full, absolute path to the file to be signed. An https://www.gnupg.org/gph/en/manual/r1290.html[ASCII-armored^] https://www.gnupg.org/gph/en/manual/x135.html[detached^] signature (plaintext) will be generated at `_path_.asc`, and a binary detached signature will be generated at `_path_.sig`. + +===== conf +See <>. + +==== gpgVerify(_sigfile_, _datafile_, _conf_) +This function verifies a detatched signature against a file containing data. Returns *True* if the file verifies, or *False* if not. + +===== sigfile +The detached signature file. Can be ASCII-armored or binary format. Full/absolute path only. + +===== datafile +The file containing the data to be verified. Full/absolute path only. + +===== conf +See <>. + +==== delTempKeys(_conf_) +Delete automatically-generated keys (if we generated them) as well as the automatically imported verification key (<>). diff --git a/docs/manual/user/advanced/SSH.adoc b/docs/manual/user/advanced/SSH.adoc index 05d85fc..a599be0 100644 --- a/docs/manual/user/advanced/SSH.adoc +++ b/docs/manual/user/advanced/SSH.adoc @@ -39,8 +39,8 @@ We'll want to create our own moduli. This can take a long time, but only needs t 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 `/overlay/etc/ssh/`: - ssh-keygen -t ed25519 -f ssh_host_ed25519_key < /dev/null - ssh-keygen -t rsa -b 4096 -f ssh_host_rsa_key < /dev/null + 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: diff --git a/docs/manual/user/fslayout/BDISK.adoc b/docs/manual/user/fslayout/BDISK.adoc index 2f883a2..fa122be 100644 --- a/docs/manual/user/fslayout/BDISK.adoc +++ b/docs/manual/user/fslayout/BDISK.adoc @@ -1,30 +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. -==== bchroot.py -This file controls creation of the chroots -- the directories in which BDisk builds the actual system that is booted into. - -==== bdisk.py -This file is a sort of "wrapper" -- it pulls all the other files in this directory together into a single usable python script. In other words, to build a BDisk distribution, you would simply run `bdisk/bdisk.py` -- that's it! - -==== bGPG.py -This contains functions having to do with GPG -- signing files, verifying other signatures, generating a key (if one wasn't specified), using a key (if one was specified), etc. - -==== 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. - -==== 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. - -==== build.py -This is responsible for building the "full" ISO, building UEFI support, etc. - -==== 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. +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <>