service distinctly separate from the main host while sharing files
wherever sensible.
-A subhost is started by identifyinf its configuration file on the
+A subhost is started by identifying 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
The subhost execution environment may be "entered" to perform
adminstrative tasks with *overlay-go*, and it is later stopped with
-*overlay-stop*.
+*overlay-stop*.
OPTIONS
-------
INIT::
-This variable is a command line to run, with envirnment variable
+This variable is a command line to run, with environment 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+.
*POSTMOUNT*::
-This variable is a command line to run, with envirnment variable
+This variable is a command line to run, with environment 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+
++overlay-postmount+. Note that this command is executed within the
+mount namespace of the subhost, and still with the main host as root
+filesystem.
*PREMOUNT*::
-This variable is a command line to run, with envirnment variable
+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-premount+
++overlay-premount+ Note that this command is executed within the
+mount namespace of the subhost, and still with the main host as root
+filesystem.
*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.
+setup as an overlay. It Is rather set up either as a bind mount if UPPER is
+different from LIVE, or just taken as a pre-mounted LIVE filesystem.
*WORK*::
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
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.
+*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.
+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
./opt/subhost/mta/mta.conf
****
+----
BASE=.
-START= rsyslog newtorking ssh postfix
+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 +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.
+the main host filesystem. Further, the running subhost will feature a
+virtual cable to the main host, where the subhost end is named +eth0+
+and the main host end is named +mta0+, and upon start, an +ifup mta0+
+is attempted at the host end while the subhost end is handled via its
+neworking service.
+
+./opt/subhost/tiny/tiny.conf
+****
+----
+BASE=.
+CABLES= =
+START= none
+LOWER=!mkdir -p base work root live ; echo base
+WORK= work
+UPPER= root
+LIVE= live
+----
+****
+
+The +tiny+ subhost would be for overlaying a separate +debootstrap+
+root filesystem, without any services (since +START+ is empty). This
+gets started with a +dummy_service+ to hold the overlay for access via
++overlay-go+. The +dummy_service+ sets up and listens on a pipe at
++/run/dummy_service+, and exits when anything is written to that.
+
+SEE ALSO
+--------
+*overlay-stop*, *overlay-go*