Browse Source

initial README also man page

Ralph Rönnquist 11 months ago
  1. 159


@ -0,0 +1,159 @@
:doctype: manpage
:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
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
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
This variable nominates the "upper" filesystem for the overlay. This
will be accessed read-write and constitutes the "private" files of the
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
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
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
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.