diff options
Diffstat (limited to 'doc/manual.cli')
| -rw-r--r-- | doc/manual.cli | 58 |
1 files changed, 46 insertions, 12 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index a2484aa..2852064 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -1,5 +1,4 @@ // file : doc/manual.cli -// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd // license : MIT; see accompanying LICENSE file "\name=build2-buildos-manual" @@ -182,23 +181,47 @@ sudo kvm \ A Build OS instances divides available CPUs and RAM (minus reserved, see below) into \i{slices} that are then \i{committed} to each instance of each -toolchain. If you don't expect your builds to utilize these resources at the -same time, then it may make sense to overcommit them to improve utilization. -The respective overcommit values can be specified as ratios with the -\c{buildos.cpu_overcommit} and \c{buildos.ram_overcommit} kernel command -line parameters. For example, given the following CPU overcommit: +toolchain. In case of CPU it normally makes sense to overcommit this resource +in order to improve utilization. This can be achieved by specifying the +overcommit values as a ratio with \c{buildos.cpu_overcommit}. For example, +given the following CPU overcommit: \ buildos.cpu_overcommit=3/2 \ -A Build OS machine with 8 CPUs (hardware threads) and three toolchains will +A Build OS machine with 8 CPUs (hardware threads) and three instances will assign 4 CPUs (\c{8 * 3/2 / 3}) to each slice. -It is also possible to reserve a number of CPUs and an amount of RAM to -Build OS with the \c{buildos.cpu_reserved} and \c{buildos.ram_reserved} -(in GB) kernel command line parameters. If unspecified, 4GB of RAM is -reserved by default. +It is also possible to specify CPU affinity with \c{buildos.cpu_affinity}. +For example, specifying: + +\ +buildos.cpu_affinity=2-9 +\ + +Will restrict the instances to only running on CPUs 2-9. + +It is possible to reserve a number of CPUs and an amount of RAM to Build OS +with the \c{buildos.cpu_reserved} and \c{buildos.ram_reserved} (in GiB) kernel +command line parameters. If unspecified, 4GiB of RAM is reserved by default. + +An amount of RAM can be reserved for auxiliary machines with +\c{buildos.ram_auxiliary}. This amount will also be divided into slices and +committed to each instance. + +Finally, if the total available RAM cannot be auto-detected, it can be +specified manually with \c{buildos.ram_total}. Here is a complete example of +specifying all the possible RAM values: + +\ +buildos.ram_total=64 +buildos.ram_reserved=4 +buildos.ram_auxiliary=12 +\ + +Assuming three instances, the configuration will assign 16GiB of build and +4GiB of auxiliary RAM to each instance and keep 4GiB reserved to Build OS. \h#config-storage|Storage| @@ -218,7 +241,7 @@ 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. +small, good-quality USB flash drive or flash card is a good option. 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: @@ -227,6 +250,11 @@ journaling disabled if used on a flash drive/card. For example: mkfs.ext4 -L buildos.state -O ^has_journal /dev/sdX \ +\N|Flash drives and cards tend to fail over time and while the state is not +precious, recreating it would also require updating the public key on all the +controllers that this build host serves. As a result, it may be prudent to +backup it up.| + \h2#config-storage-machines|Machines| For virtual machine and container storage we can use a single disk, in which @@ -276,6 +304,12 @@ confirm over-provisioning, format the disk as \c{btrfs}, and label it as # ^D # Exit shell and reboot. \ +To create a single \c{btrfs} disk that spans multiple physical devices: + +\ +# mkfs.btrfs -L buildos.machines -d single -m single /dev/sda /dev/sdb +\ + \h#config-net|Network| Network is configured via DHCP. Initially, all Ethernet interfaces that have |