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.