diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual.cli | 116 |
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\" +\ " |