From: Ralph Ronnquist Date: Sat, 26 Mar 2022 08:58:29 +0000 (+1100) Subject: initial README also man page X-Git-Tag: deb_0.1~13 X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=1962381a074900c46e81c122049bd4ce64cf4e59;p=rrq%2Foverlay-boot.git initial README also man page --- diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..c4cb404 --- /dev/null +++ b/README.adoc @@ -0,0 +1,159 @@ +overlay-boot(8) +=============== +:doctype: manpage +:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"} +:COLON: : +:EQUALS: = + +NAME +---- +overlay-boot - Start a subhost with overlay root filesystem. + +SYNOPSIS +-------- +*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. + +OPTIONS +------- + +An overlay-boot subhost is defined in the configuration file, which is +a plain text file with a number of variable assignments. + +*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. + +*BASE*:: + +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. + +*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. + +See the section on Networking below for more details. + +*LIVE*:: + +This variable nominates the mount point for the overlay mount, and it +defaults to +$BASE/live+ (which also must exist). + +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. + +*LOG*:: + +This variable nominates the log file to use by +overlay-boot+. 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 +system root file system. The default is +/+, i.e. the main host root +filesystem. + +*UPPER*:: + +This variable nominates the "upper" filesystem for the overlay. This +will be accessed read-write and 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". + +*WORK*:: + +This variable nominates the "work" directory for the 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+. + +Note that if no services are started, then a +dummy_service+ gets +started so as to keep 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. + +Networking +---------- + +*overlay-boot* sets up a nework namespace named by the subhost NAME, +and uses the CABLES variable to set up +veth+ 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. + +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 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. + +boot-up +------- + +*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.