+overlay-boot(8)
+===============
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+:COLON: :
+:EQUALS: =
+
+NAME
+----
+overlay-boot - Start a subhost with overlay root filesystem.
+
+SYNOPSIS
+--------
+*overlay-boot* _conf_
+
+DESCRIPTION
+-----------
+*overlay-boot* is the main script on a small collection of
+administration scripts for containerizing services with minimal ado.
+The script starts a "subhost" with a dedicated network namespace, and
+the mount and pid namespaces separated from the main host by means of
++unshare+. A subhost root file system may in particular be set up as
+an overlay of the main host filesystem to keep the specifics of a
+service distinctly separate from the main host while sharing files
+wherever sensible.
+
+A subhost is started by identifyinf its configuration file on the
+command line for *overlay-boot*. The configuration file is a plain
+text file with a small collection of "variables" that tell how the
+subhost is set up. When all is good, *overlay-boot* spawns a
+subprocess that invokes a command shell within an chroot into
+"unshared" subhost root filesystem, all similar to the bootup of any
+odd computer.
+
+The subhost execution environment may be "entered" to perform
+adminstrative tasks with *overlay-go*, and it is later stopped with
+*overlay-stop*.
+
+OPTIONS
+-------
+
+An overlay-boot subhost is defined in the configuration file, which is
+a plain text file with a number of variable assignments. Each
+assignment is written with the varable name flush left and immediately
+followed by an equal sign, The rest of that line (ignoring leading and
+trailing spaces) is its value, or if that value startes with an
+exclamation mark, then the line is a command to run so as to generate
+the value. See examples below.
+
+*NAME*::
+
+This variable declares a short name for the subhost, and should be no
+more than 12 printable ascii characters. The base name of the
+configuration file is used by default. I.e., a configuration file
+named +foo.conf+ by default names its subhost +foo+ unless there is a
++NAME+ variable says differently.
+
+*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 subhost networking in terms of its virtual
+cables. The value is a space separated list of "virtual cable
+specifiers", each consisting of an equal sign optionally with a bridge
+name to the left and optinally a MAC address to the right. See the
+section on Networking below for more details.
+
+INIT::
+
+This variable is a command line to run, with envirnment variable
+CONFIG set, for producing the initial commands to the running subhost,
+similar to the initrd phase of a computer bootup. The default value
+for this variable is +overlay-init+.
+
+*LIVE*::
+
+This variable nominates the mount point for the running subhost's root
+file system. It defaults to +$BASE/live+ The nominated directory must
+exist, and depending on the directory pathnames in the +UPPER+ and
++LOWER+ variables, the subhost root filesystem is either of a
+pre-mounted directory, bind mounted or overlay mounted directory. See
+the details of this with the UPPER variable below.
+
+*LOG*::
+
+This variable nominates the logfile to use by +overlay-boot+ when
+running the subhost. The default is +/tmp/overlay-$NAME.log+.
+
+*LOWER*::
+
+This variable nominates the "lower" filesystem of an overlay mount.
+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. When overlay is not desired, then LOWER should be the smae
+as UPPER.
+
+*POSTMOUNT*::
+
+This variable is a command line to run, with envirnment variable
+CONFIG set, just after the setup of the subhost root filesystem and
+before the services are started. The default for this variable is
++overlay-postmount+
+
+*PREMOUNT*::
+
+This variable is a command line to run, with envirnment variable
+CONFIG set, just before the setup of the subhost root filesystem and
+before the services are started. The default for this variable is
++overlay-premount+
+
+*UPPER*::
+
+This variable nominates the "upper" filesystem for an overlay mount.
+This will be accessed read-write and it constitutes the "private"
+files of the subhost.
+
+If UPPER is different from LOWER, then the root file system is set up
+as an overlay mount. In that case WORK (below) must be defined as a
+directory outside of but on the same mount as UPPER.
+
+If UPPER is the same as LOWER, then the subhost root filesystem is not
+setup as an overla. Rather it is set up as a bind mount, if UPPER is
+different from LIVE, or just as a pre-mounted LIVE filesystem.
+
+*WORK*::
+
+This variable nominates the "work" directory for an 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. The default value is +networking ssh+.
+
+Note that if no services are started, then +overlay-init+ starts a
++dummy_service+ so as to keep +/.reaper+ from running out of child
+processes, as it otherwise will exit and thereby terminate
++overlay-boot+.
+
+*RAM_SIZE*::
+
+This variable may be used to configure the +/run+ directory which by
+defult gets mounted on an overlay mount 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.
+
+EXAMPLES
+--------
+
+./opt/subhost/mta/mta.conf
+****
+BASE=.
+START= rsyslog newtorking ssh postfix
+****
+
+The above example assumes a directory +/opt/subhost/mta+ that contains
+the configuration file +mta.conf+ and directories +root+, +work+ and
++live+. *overlay-boot* will set up an overlay mount on +live+ with
++root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of
+the main host filesystem.
+