overlay-boot(8) Manual Page
overlay-boot - Start a subhost with overlay root filesystem.
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.
An overlay-boot subhost is defined in the configuration file, which is a plain text file with a number of variable assignments.
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 pathname for a directory that is considered to be a "base" for the subhost setup. This is the only required variable.
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.
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.
This variable nominates the log file to use by
overlay-boot. The default is
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.
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".
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.
This variable tells which services should be started on the overlay-boot startup. They get started with
service $srv startbefore the startup ends by running
/.reaper(which is automatically installed by
overlay-boot). The default START includes
Note that if no services are started, then a
started so as to keep keep
/.reaper from running out of child
processes, as it otherwise will exit and thereby terminate
dummy_service may be killed by a signal, or by writing to the
This variable may be used to configure the
/rundirectory which by defult gets mounted as a
tmpfsof 50M. Use
noneto avoid that mount, and otherwise the desired tmpfs+ size.
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
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.
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
/.reaper which simply waits and "reaps" child processes
until it runs out of those and exist.