From 76e38dcd5eeb05812216dfabb059d2a2db7c2e7e Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Mon, 28 Mar 2022 21:16:05 +1100 Subject: [PATCH] freshen up --- README.adoc | 175 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 106 insertions(+), 69 deletions(-) diff --git a/README.adoc b/README.adoc index c4cb404..932cae0 100644 --- a/README.adoc +++ b/README.adoc @@ -11,31 +11,49 @@ overlay-boot - Start a subhost with overlay root filesystem. SYNOPSIS -------- -*overlay-boot _conf_ +*overlay-boot* _conf_ DESCRIPTION ----------- -*overlay-boot* attempts to run a "subhost" with an overlay root -filesystem. The subhost is defined in a configuration file named on -the command line. When all is good, *overlay-boot* spawns a subprocess -that invokes a command shell within an chroot into "unshared" overlay -root filesystem, to perform service initialisations before ending up -in an indefinitely running "reaper" process. The overlay subhost is -essentially like a light container or virtual virtual machine for -running services in a relatively contained way without too much of -cross-wise interactions between them. +*overlay-boot* is the main script on 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 identifyinf 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*. OPTIONS ------- An overlay-boot subhost is defined in the configuration file, which is -a plain text file with a number of variable assignments. +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. *NAME*:: -This variable declares the short name for the subhost, and should be -no more than 12 printable ascii characters. The name of the -configuration file is used by default. +This variable declares a short name for the subhost, and should be no +more than 12 printable ascii characters. The base name of the +configuration file is used by default. I.e., a configuration file +named +foo.conf+ by default names its subhost +foo+ unless there is a ++NAME+ variable says differently. *BASE*:: @@ -45,74 +63,90 @@ variable. *CABLES*:: -This variable declares the networking setup to use for the subhost -through a space separated list of "virtual cable specifiers", each -consisting of a (possibly empty) bridge interface name and a (possibly -empty) MAC address with a (required) equal sign ("=") between them. +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 +section on Networking below for more details. -See the section on Networking below for more details. +INIT:: -*LIVE*:: +This variable is a command line to run, with envirnment 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 nominates the mount point for the overlay mount, and it -defaults to +$BASE/live+ (which also must exist). +*LIVE*:: -If LIVE and LOWER (below) are the same then this is assumed to be a -pre-mounted root filesystem for the later chroot without any overlay -mount being attempted. +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. *LOG*:: -This variable nominates the log file to use by +overlay-boot+. The -default is +/tmp/overlay-$NAME.log+. +This variable nominates the logfile to use by +overlay-boot+ when +running the subhost. The default is +/tmp/overlay-$NAME.log+. *LOWER*:: -This variable nominates the "lower" filesystem of the overlay. This -will be accessed read-only, an it is intended to be the operating +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. +filesystem. When overlay is not desired, then LOWER should be the smae +as UPPER. + +*POSTMOUNT*:: + +This variable is a command line to run, with envirnment variable +CONFIG set, just after the setup of the subhost root filesystem and +before the services are started. The default for this variable is ++overlay-postmount+ + +*PREMOUNT*:: + +This variable is a command line to run, with envirnment 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+ *UPPER*:: -This variable nominates the "upper" filesystem for the overlay. This -will be accessed read-write and constitutes the "private" files of the -subhost. +This variable nominates the "upper" filesystem for an overlay mount. +This will be accessed read-write and it constitutes the "private" +files of the subhost. -If UPPER nominates an executable file raher than directory (i.e. -program or script), then that will be run before overlay mounting with -the environment variable ACTION set to "setup". The script must then -print the pathname of the actual "upper" directory when successfully -set up. Further upon termination of the subhost, that UPPER script -will be run with ACTION set to "teardown". +If UPPER is different from LOWER, then the root file system is set up +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 overla. Rather it is set up as a bind mount, if UPPER is +different from LIVE, or just as a pre-mounted LIVE filesystem. *WORK*:: -This variable nominates the "work" directory for the overlay mount. It +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. They get started with +service $srv start+ -before the startup ends by running +/.reaper+ (which is automatically -installed by +overlay-boot+). The default START includes +networking+ -and +ssh+. +overlay-boot startup. The default value is +networking ssh+. -Note that if no services are started, then a +dummy_service+ gets -started so as to keep keep +/.reaper+ from running out of child +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+. -That +dummy_service+ may be killed by a signal, or by writing to the -+/run/dummy_service+ pipe. - *RAM_SIZE*:: This variable may be used to configure the +/run+ directory which by -defult gets mounted as a +tmpfs+ of 50M. Use +none+ to avoid that -mount, and otherwise the desired tmpfs+ size. +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 ---------- @@ -138,22 +172,25 @@ 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. -boot-up -------- +EXAMPLES +-------- + +./opt/subhost/mta/mta.conf +**** +BASE=. +CABLES= = +START= rsyslog newtorking ssh postfix +**** + +The above example assumes a directory +/opt/subhost/mta+ that contains +the configuration file +mta.conf+ and directories +root+, +work+ and ++live+. *overlay-boot* will set up an overlay mount on +live+ with ++root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of +the main host filesystem. Further, the running subhost will feature a +virtual cable to the main host, where the subhost end is named +eth0+ +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. + + -*overlay-boot* includes a small boot-up section that consists of the -following command sequence: ----- -mount -t proc proc /proc -mount -t devpts devpts /dev/pts -mount -t sysfs sysfs /sys -if [ "$RAM_SIZE" != "none" ] && ! grep -q '/run tmpfs' /proc/mounts ; then - mount -t tmpfs -osize=$RAM_SIZE,mode=755 tmpfs /run -fi -for srv in $START ; do - service $srv start -done ----- -Thereafter the *overlay-boot* command shell (+/bin/sh+) morphs into -running +/.reaper+ which simply waits and "reaps" child processes -until it runs out of those and exist. -- 2.39.2