Configure storage

1 files changed, 47 insertions, 0 deletions

diff --git a/doc/manual.cli b/doc/manual.cli
index 1140db5..961627e 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -143,4 +143,51 @@ 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}).
+
+\h2#config-storage|Storage|
+
+Build OS configures storage based on the labels assigned to disks and
+partitions (collectively refered to as disks from now on).
+
+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
+case they should be labeled \c{buildos.machines.<volume>}. In both cases the
+disks must be formatted as \c{btrfs}.
+
+In a single disk configuration, the disk is mounted as \c{/build/machines}. In
+a multi-disk configuration, each disk is mounted as
+\c{/build/machines/<volume>}.
+
+If no disks are found for required storage, then the boot process is
+interrupted with a shell prompt where you can format and/or lable a suitable
+disk. You can also view the storage configuration on a booted Build OS
+instance by examining \c{/etc/fstab}.
+
+As an example, let's consider the first boot of a clean machine that has a 1TB
+SSD disk as \c{/dev/sda} and which we would like to use for virtual machine
+storage. We would also like to over-provision this SSD by 10% to (potentially)
+prolong its life and increase performance (you may want to skip this step if
+you are using a datacenter-grade SSD that would normally already be generously
+over-provisioned).
+
+On the first boot we will be presented with a shell prompt which we use to
+over-provision the disk:
+
+\
+# fdisk -l /dev/sda            # Query disk information.
+# hdparm -N /dev/sda           # Query disk/host protection area sizes.
+# hdparm -Np<COUNT> /dev/sda   # COUNT = sector count * 0.9
+# hdparm -N /dev/sda           # Verify disk/host protection area sizes.
+# ^D                           # Exit shell and reboot.
+\
+
+After the reboot we will be presented with a shell prompt again where we
+confirm over-provisioning, format the disk as \c{btrfs}, and label it as
+\c{buildos.machines}:
+
+\
+# fdisk -l /dev/sda            # Confirm disk size decreased by 10%.
+# mkfs.btrfs -L buildos.machines -m single /dev/sda
+# ^D                           # Exit shell and reboot.
+\
 "