more documentation...

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 < /dev/null
+ ssh-keygen -t rsa -b 4096 -f ssh_host_rsa_key < /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.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
+
+OpenVPN will then start on boot in the built BDisk instance.
+