overlay-boot(8) Manual Page

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.