You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Ralph Rönnquist 1962381a07 initial README also man page 1 year ago
asm renamed directory 1 year ago
debian renamed directory 1 year ago
olle revised test config 1 year ago
Makefile adding man pages 1 year ago
README.adoc initial README also man page 1 year ago
functions added listing of subhosts 1 year ago
overlay-boot pre-packaging fixes 1 year ago
overlay-go added listing of subhosts 1 year ago
overlay-stop added stop script 1 year ago


overlay-boot(8) Manual Page


overlay-boot - Start a subhost with overlay root filesystem.


*overlay-boot conf


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 /tmp/overlay-$NAME.log.


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 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.


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.


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.


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
for srv in $START ; do
    service $srv start

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.