overlay-boot(8) Manual Page
overlay-boot - Start a subhost with overlay root filesystem.
overlay-boot is the main script in a small collection of administration scripts for containerizing services with minimal ado. It starts a "subhost" with a dedicated network namespace, and the mount and pid namespaces separated from the main host by means of unshare, and the subhost root file system may be set up as an overlay of the main host filesystem, for keeping the subhost services distinctly separate from the main host.
A subhost is started by nominating its configuration file on the command line for overlay-boot. This is a plain text file with a small collection of "variables" that tell how the subhost is set up. 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, and therafter the subhost "runs" in the way of a virtual machine or container environment.
The administrator may "enter" the subhost execution environment to perform adminstrative tasks by means of overlay-go, which starts an interactive shell within the subhost namespaces. The subhost may also be set up with users and an sshd service as needed.
Subhost execution is stopped with overlay-stop.
An overlay-boot subhost is defined in a configuration file that 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. But if that value startes with an exclamation mark, then the line is a command to run during start-up so as to generate the value. See examples below.
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.confby default names its subhost
foounless there is a
NAMEvariable says differently.
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.
A typical subhost setup is defined by a dedicated directory that contains the configuration file and the three mount points "root", "work" and "live".
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 optionally a MAC address to the right. See the section on Networking below for more details.
This variable is a command to run (with environment variable CONFIG set) that outputs on its standard output the series of commands for the running subhost. The default value for this variable is
This variable nominates the mount point for the running subhost’s root file system. It defaults to
$BASE/liveThe nominated directory must exist, and depending on the directory pathnames in the
LOWERvariables, the subhost root filesystem is one of
a pre-mounted directory,
bind mounted with UPPER, or
and overlay mount of UPPER (and WORK) over LOWER. See also the UPPER variable below.
This variable nominates the logfile to use by
overlay-bootwhen running the subhost. The default is
This variable nominates the "lower" filesystem of an overlay mount. This will be accessed read-only, and 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.
This variable is a command line to run (with environment variable CONFIG set) following the setup of the subhost root filesystem and before the services are started. The default for this variable is
/var/lib/overlay-mount/overlay-postmount. Note that this command is executed within the mount namespace of the subhost, and still with the main host as root filesystem. The POSTMOUNT command is executed for all of the three different root filesystem setup variants.
This variable is a command line to run (with environment 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-premountNote that this command is executed within the mount namespace of the subhost, and still with the main host as root filesystem. The PREMOUNT command is executed for both the overlay and bind mount variants of root filesystem setup but not for plain root filesystem, which does not involve mounting LIVE.
This variable configures the subhost
/rundirectory which by default is mounted as a
tmpfsof 50M. Use
noneto avoid that mount, and otherwise the desired
This variable names the services to be started on the overlay-boot startup. The default value is
Note that if no services are started, then
dummy_serviceso as to keep
/.reaperfrom running out of child processes, as it otherwise will exit and thereby terminate
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 overlay. Rather, if UPPER is different from LIVE, the root filesystem is set up as a bind mount, and if UPPER and LIVE are also the same, then LIVE is used as root filesystem without additional mounting.
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.
overlay-boot sets up a nework namespace named by the subhost
$NAME, and uses the
CABLES variable to set up veth type 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
by the same number.
As mentioned above,
CABLES is a space separated list of cable
specifiers, each consisting of an optional bridge interface name, an
optional MAC adddress and with a required equal sign ("=") between
The bridge interface name, when given, will be given control of the host end cable interface. When the bridge interface name is omitted (empty) then the host end interface attracts an ifup $IF attempt instead.
The MAC address, if given, is used for the subhost end cable interface, which otherise gets its MAC address from the kernel, possibly a different one upon each start.
BASE=. CABLES= = START= rsyslog networking ssh saslauthd postfix dovecot
The above example assumes a directory
/opt/subhost/mta that contains
the configuration file
mta.conf and directories
live. overlay-boot will set up an overlay mount on
root as UPPER,
work as WORK and
/ as LOWER, i.e. an overlay of
the main host filesystem. Further, the running subhost will feature a
virtual cable to the main host, where the subhost end is named
and the main host end is named
mta0, and upon start, an
is attempted at the host end while the subhost end is handled via its
BASE=. CABLES= = START= none LOWER= !mkdir -p base work root live ; echo base WORK= work UPPER= root LIVE= live
tiny subhost would be for overlaying a separate
root filesystem, without any services (since
START is empty). This
gets started with a
dummy_service to hold the overlay for access via
dummy_service sets up and listens on a pipe at
/run/dummy_service, and exits when anything is written to that.