Add support for persistent state, SSH

1 files changed, 76 insertions, 40 deletions

diff --git a/doc/manual.cli b/doc/manual.cli
index eae02d3..eaf8d93 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -36,7 +36,7 @@ mode} and receive \i{build tasks} from their respective agents.
 \c{buildos} is normally booted from the network using PXE but can also be
 booted locally from the kernel image and initrd directly.
 
-\h2#boot-reboot|Reboot|
+\h#boot-reboot|Reboot|
 
 Build OS can detect when the OS build has been updated and automatically
 reboot the build host. This is achieved by polling the URL specified
@@ -44,7 +44,7 @@ with the \c{buildos.buildid_url} kernel command line parameter. It should
 point to the \c{buildos-buildid} file that comes along the kernel image
 and initrd. See \l{#boot-net Network Boot} for the usage example.
 
-\h2#boot-net|Network Boot|
+\h#boot-net|Network Boot|
 
 Here we assume that you have already established your PXE setup using
 PXELINUX. That is, you have configured a TFTP server that hosts the
@@ -100,7 +100,7 @@ $ sudo kvm \
 
 ||
 
-\h2#boot-local|Local Boot|
+\h#boot-local|Local Boot|
 
 During testing it is often useful to boot \c{buildos} directly from the
 kernel image and initrd files. As an example, here is how this can be done
@@ -116,50 +116,33 @@ sudo kvm \
 
 \h1#config|Configuration|
 
-\h2#config-net|Network|
+\h#config-storage|Storage|
 
-Network is configured via DHCP. Initially, all Ethernet interfaces that have
-carrier are tried in (some) order and the first interface that is successfully
-configured via DHCP is used.
-
-Hostname is configured from the DHCP information. Failed that, a name is
-generated based on the MAC address, in the form \c{build-xxxxxxxxxx}.
-@@ Maybe also kernel cmdline?
-
-Based on the discovery of the Ethernet interface, two bridge interfaces are
-configured: \c{br0} is a public bridge that includes the Ethernet interface
-and is configured via DHCP. \c{br1} is a private interface with NAT to \c{br0}
-with \c{dnsmasq} configured as a DHCP on this interface.
-
-Normally, \c{br0} is used for \c{bslave} virtual machines/container (since
-they may need to be accessed directly) and \c{br1} \- for \c{bbot} virtual
-machines. You can view the bridge configuration on a booted \c{buildos}
-instance by examining \c{/etc/network/interfaces}.
-
-@@ TODO: private network parameters.
+Build OS configures storage based on the labels assigned to disks and
+partitions (collectively refered to as disks from now on). Build OS requires
+storage for state as well as virtual machines and containers.
 
-\h2#config-email|Email|
+\h2#config-storage-state|State|
 
-A \c{buildos} instance sends various notifications (including all messages to
-\c{root}) to the admin email address. The admin email is specified with
-the \c{buildos.admin_email} kernel command line parameter.
+Build OS stores a small amount of state on a disk labeled \c{buildos.state}
+(mounted as \c{/state}). This includes random number generator state, SSH
+server host keys, and so on. While this state is persistent, it is not
+precious.
 
-In order to deliver mail, the \c{postfix} MTA is configured to forward to a
-relay. The relay host is specified with the \c{buildos.smtp_relay} kernel
-command line parameter.
+The stored state is fairly small (hundreds of megabytes) and is not
+performance-critical. While one can create a small state partition on the same
+physical disk as used for machines (see below), having it on a separate disk
+makes it easier to move machine disks around. Based on these requirements, a
+small USB flash drive or flash card is a good option.
 
-Note that no authentication of any kind is configured for relaying. This means
-that the relay host should accept emails from build hosts either because of
-their network location (for example, because they are on your organization's
-local network and you are using your organization's relay) or because the
-relay host accepts emails send to the admin address from anyone (which is
-normally the case if the relay is the final destination for the admin
-address, for example, \c{example.org} and \c{admin@example.org}).
+While any suitable filesystem can be used, \c{ext4} is a good choice, with
+journaling disabled if used on a flash drive/card. For example:
 
-\h2#config-storage|Storage|
+\
+mkfs.ext4 -L buildos.machines -O ^has_journal /dev/sdX
+\
 
-Build OS configures storage based on the labels assigned to disks and
-partitions (collectively refered to as disks from now on).
+\h2#config-storage-machines|Machines|
 
 For virtual machine and container storage we can use a single disk, in which
 case it should be labeled \c{buildos.machines} or multiple disks, in which
@@ -206,4 +189,57 @@ confirm over-provisioning, format the disk as \c{btrfs}, and label it as
 # mkfs.btrfs -L buildos.machines -m single /dev/sda
 # ^D                           # Exit shell and reboot.
 \
+
+\h#config-net|Network|
+
+Network is configured via DHCP. Initially, all Ethernet interfaces that have
+carrier are tried in (some) order and the first interface that is successfully
+configured via DHCP is used.
+
+Hostname is configured from the DHCP information. Failed that, a name is
+generated based on the MAC address, in the form \c{build-xxxxxxxxxx}.
+@@ Maybe also kernel cmdline?
+
+Based on the discovery of the Ethernet interface, two bridge interfaces are
+configured: \c{br0} is a public bridge that includes the Ethernet interface
+and is configured via DHCP. \c{br1} is a private interface with NAT to \c{br0}
+with \c{dnsmasq} configured as a DHCP on this interface.
+
+Normally, \c{br0} is used for \c{bslave} virtual machines/container (since
+they may need to be accessed directly) and \c{br1} \- for \c{bbot} virtual
+machines. You can view the bridge configuration on a booted \c{buildos}
+instance by examining \c{/etc/network/interfaces}.
+
+@@ TODO: private network parameters.
+
+\h#config-email|Email|
+
+A \c{buildos} instance sends various notifications (including all messages to
+\c{root}) to the admin email address. The admin email is specified with
+the \c{buildos.admin_email} kernel command line parameter.
+
+In order to deliver mail, the \c{postfix} MTA is configured to forward to a
+relay. The relay host is specified with the \c{buildos.smtp_relay} kernel
+command line parameter.
+
+Note that no authentication of any kind is configured for relaying. This means
+that the relay host should accept emails from build hosts either because of
+their network location (for example, because they are on your organization's
+local network and you are using your organization's relay) or because the
+relay host accepts emails send to the admin address from anyone (which is
+normally the case if the relay is the final destination for the admin
+address, for example, \c{example.org} and \c{admin@example.org}).
+
+
+\h#config-ssh|SSH|
+
+Build OS runs an OpenSSH server with password authentication disabled. As a
+result, the only way to login remotely is via a public key. To add a public
+key into the \c{root} user's \c{authorized_keys} file we can use the
+\c{buildos.ssh_key} kernel command line parameter. For example (note the
+quotes):
+
+\
+buildos.ssh_key=\"ssh-rsa AAA...OA0DB user@host\"
+\
 "