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