From 999258bf0b00eaefd93ea5daea53cd9fab5cbdcd Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Mon, 4 Apr 2022 14:10:19 +1000 Subject: [PATCH] editorial improvements --- overlay-boot.8.adoc | 175 ++++++++++++++++++++++++-------------------- 1 file changed, 94 insertions(+), 81 deletions(-) diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc index e97a8e4..01ae709 100644 --- a/overlay-boot.8.adoc +++ b/overlay-boot.8.adoc @@ -15,37 +15,39 @@ SYNOPSIS DESCRIPTION ----------- -*overlay-boot* is the main script on a small collection of +*overlay-boot* is the main script in a small collection of administration scripts for containerizing services with minimal ado. -The script starts a "subhost" with a dedicated network namespace, and -the mount and pid namespaces separated from the main host by means of -+unshare+. A subhost root file system may in particular be set up as -an overlay of the main host filesystem to keep the specifics of a -service distinctly separate from the main host while sharing files -wherever sensible. - -A subhost is started by identifying its configuration file on the -command line for *overlay-boot*. The configuration file is a plain -text file with a small collection of "variables" that tell how the -subhost is set up. When all is good, *overlay-boot* spawns a -subprocess that invokes a command shell within an chroot into -"unshared" subhost root filesystem, all similar to the bootup of any -odd computer. - -The subhost execution environment may be "entered" to perform -adminstrative tasks with *overlay-go*, and it is later stopped with -*overlay-stop*. +It starts a "subhost" with a dedicated network namespace, and the +mount and pid namespaces separated from the main host by means of +_unshare_, and the subhost root file system may be set up as an +overlay of the main host filesystem, for keeping the subhost services +distinctly separate from the main host. + +A subhost is started by nominating its _configuration file_ on the +command line for *overlay-boot*. This is a plain text file with a +small collection of "variables" that tell how the subhost is set up. +*overlay-boot* spawns a subprocess that invokes a command shell within +an chroot into "unshared" subhost root filesystem, all similar to the +bootup of any odd computer, and therafter the subhost "runs" in the +way of a virtual machine or container environment. + +The administrator may "enter" the subhost execution environment to +perform adminstrative tasks by means of *overlay-go*, which starts an +interactive shell within the subhost namespaces. The subhost may also +be set up with users and an _sshd_ service as needed. + +Subhost execution is stopped with *overlay-stop*. OPTIONS ------- -An overlay-boot subhost is defined in the configuration file, which is -a plain text file with a number of variable assignments. Each -assignment is written with the varable name flush left and immediately -followed by an equal sign, The rest of that line (ignoring leading and -trailing spaces) is its value, or if that value startes with an -exclamation mark, then the line is a command to run so as to generate -the value. See examples below. +An *overlay-boot* subhost is defined in a configuration file that is a +plain text file with a number of variable assignments. Each assignment +is written with the varable name flush left and immediately followed +by an equal sign, The rest of that line (ignoring leading and trailing +spaces) is its value. But if that value startes with an exclamation +mark, then the line is a command to run during start-up so as to +generate the value. See examples below. *NAME*:: @@ -60,30 +62,37 @@ named +foo.conf+ by default names its subhost +foo+ unless there is a This variable declares a pathname for a directory that is considered to be a "base" for the subhost setup. This is the only required variable. ++ +A typical subhost setup is defined by a dedicated directory that +contains the configuration file and the three mount points "root", +"work" and "live". *CABLES*:: This variable declares the subhost networking in terms of its virtual cables. The value is a space separated list of "virtual cable specifiers", each consisting of an equal sign optionally with a bridge -name to the left and optinally a MAC address to the right. See the +name to the left and optionally a MAC address to the right. See the section on Networking below for more details. INIT:: -This variable is a command line to run, with environment variable -CONFIG set, for producing the initial commands to the running subhost, -similar to the initrd phase of a computer bootup. The default value -for this variable is +overlay-init+. +This variable is a command to run (with environment variable CONFIG +set) that outputs on its standard output the series of commands for +the running subhost. The default value for this variable is ++/var/lib/overlay-boot/overlay-init+. *LIVE*:: This variable nominates the mount point for the running subhost's root file system. It defaults to +$BASE/live+ The nominated directory must exist, and depending on the directory pathnames in the +UPPER+ and -+LOWER+ variables, the subhost root filesystem is either of a -pre-mounted directory, bind mounted or overlay mounted directory. See -the details of this with the UPPER variable below. ++LOWER+ variables, the subhost root filesystem is one of ++ + 1. a pre-mounted directory, + 2. bind mounted with UPPER, or + 3. and overlay mount of UPPER (and WORK) over LOWER. See also the + UPPER variable below. *LOG*:: @@ -93,28 +102,47 @@ running the subhost. The default is +/tmp/overlay-$NAME.log+. *LOWER*:: This variable nominates the "lower" filesystem of an overlay mount. -This will be accessed read-only, an it is intended to be the operating -system root file system. The default is +/+, i.e. the main host root -filesystem. When overlay is not desired, then LOWER should be the smae -as UPPER. +This will be accessed read-only, and it is intended to be the +operating system root file system. The default is +/+, i.e. the main +host root filesystem. When overlay is not desired, then LOWER should +be the smae as UPPER. *POSTMOUNT*:: -This variable is a command line to run, with environment variable -CONFIG set, just after the setup of the subhost root filesystem and +This variable is a command line to run (with environment variable +CONFIG set) following the setup of the subhost root filesystem and before the services are started. The default for this variable is -+overlay-postmount+. Note that this command is executed within the -mount namespace of the subhost, and still with the main host as root -filesystem. ++/var/lib/overlay-mount/overlay-postmount+. Note that this command is +executed within the mount namespace of the subhost, and still with the +main host as root filesystem. The POSTMOUNT command is executed for +all of the three different root filesystem setup variants. *PREMOUNT*:: -This variable is a command line to run, with environment variable -CONFIG set, just before the setup of the subhost root filesystem and +This variable is a command line to run (with environment variable +CONFIG set) just before the setup of the subhost root filesystem and before the services are started. The default for this variable is -+overlay-premount+ Note that this command is executed within the -mount namespace of the subhost, and still with the main host as root -filesystem. ++overlay-premount+ Note that this command is executed within the mount +namespace of the subhost, and still with the main host as root +filesystem. The PREMOUNT command is executed for both the overlay and +bind mount variants of root filesystem setup but not for plain root +filesystem, which does not involve mounting LIVE. + +*RAM_SIZE*:: + +This variable configures the subhost +/run+ directory which by default +is mounted as a +tmpfs+ of 50M. Use +none+ to avoid that mount, and +otherwise the desired +tmpfs+ size. + +*START*:: + +This variable names the services to be started on the overlay-boot +startup. The default value is +networking ssh+. ++ +Note that if no services are started, then +overlay-init+ starts a ++dummy_service+ so as to keep +/.reaper+ from running out of child +processes, as it otherwise will exit and thereby terminate ++overlay-boot+. *UPPER*:: @@ -127,8 +155,10 @@ as an overlay mount. In that case WORK (below) must be defined as a directory outside of but on the same mount as UPPER. + If UPPER is the same as LOWER, then the subhost root filesystem is not -setup as an overlay. It Is rather set up either as a bind mount if UPPER is -different from LIVE, or just taken as a pre-mounted LIVE filesystem. +setup as an overlay. Rather, if UPPER is different from LIVE, the root +filesystem is set up as a bind mount, and if UPPER and LIVE are also +the same, then LIVE is used as root filesystem without additional +mounting. *WORK*:: @@ -136,50 +166,33 @@ This variable nominates the "work" directory for an overlay mount. It has to be a writable directory on the same mount device as the UPPER directory. -*START*:: - -This variable tells which services should be started on the -overlay-boot startup. The default value is +networking ssh+. -+ -Note that if no services are started, then +overlay-init+ starts a -+dummy_service+ so as to keep +/.reaper+ from running out of child -processes, as it otherwise will exit and thereby terminate -+overlay-boot+. - -*RAM_SIZE*:: - -This variable may be used to configure the +/run+ directory which by -defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use -+none+ to avoid that mount, and otherwise the desired +tmpfs+ size. - Networking ---------- *overlay-boot* sets up a nework namespace named by the subhost -+$NAME+, and uses the +$CABLES+ variable to set up +veth+ virtual ++$NAME+, and uses the +CABLES+ variable to set up _veth_ type virtual cables. The host end of such cables are named by +$NAME+ followed by a number from 0 and up while the subhost end are named by +eth+ followed by the same number. -As mentioned above, +$CABLES+ consists of a space separated list of -cable specifiers, each consisting of a bridge interface name and a -with an equal sign ("=") between them. The equal sign is required -while either or both of the bridge and MAC address may be left empty. +As mentioned above, +CABLES+ is a space separated list of cable +specifiers, each consisting of an optional bridge interface name, an +optional MAC adddress and with a required equal sign ("=") between +them. -The bridge interface name, if given, will be given control of the host -end cable interface. A cable specification with empty bridge name part -results in that the host end is brought up at link level and then -+ifup $IF+ is attempted. +The bridge interface name, when given, will be given control of the +host end cable interface. When the bridge interface name is omitted +(empty) then the host end interface attracts an _ifup $IF_ attempt +instead. The MAC address, if given, is used for the subhost end cable -interface. A cable specification with empty MAC address part results -in that the interface get its MAC address from the kernel, possibly a -different one upon each start. +interface, which otherise gets its MAC address from the kernel, +possibly a different one upon each start. EXAMPLES -------- -./opt/subhost/mta/mta.conf +=== /opt/subhost/mta/mta.conf **** ---- BASE=. @@ -198,13 +211,13 @@ and the main host end is named +mta0+, and upon start, an +ifup mta0+ is attempted at the host end while the subhost end is handled via its neworking service. -./opt/subhost/tiny/tiny.conf +=== /opt/subhost/tiny/tiny.conf **** ---- BASE=. CABLES= = START= none -LOWER=!mkdir -p base work root live ; echo base +LOWER= !mkdir -p base work root live ; echo base WORK= work UPPER= root LIVE= live -- 2.39.2