subhost scripts
===============

This is the script collection for a bespoke "sub host" platform for
running sandboxed services directly on the infrastructure hosts rather
than within virtual machines (VM).

It sets up the sub hosts fully within the $SUBHOST directory tree,
originally +/opt/subhost+, and each subhost system is represented
there as its own directory tree whose top level contains the
following:

 * +config+ is a bash include file that declares the subhost setup for
 the control script.

 * +live+ is the root of the subhost filesystem when activated. It
 gets set up either as an +rbind+ mount of the subhost +root+ or as an
 +overlay+ mount placing the subhost +root+ over a common, read-only
 base filesystem.

 * +root+ is the directory that contains the subhost filesystem (root
 filesystem). This may be the file system in full, or the writable
 part of the overlay filesystem.

 * +work+ is the work directory for the overlay mount, unless the
 subhost is equipped with an image file for its root filesystem (in
 which case that image file offers the work directory)

 * +mnt+ is optional. It is used as the mount target for the image
 file when the subhost has one.

 * +$SUB.img+ (for the subhost named +$SUB+)is the optional image file
 for a subhost. The image file must itself have top directories
 +/root+ and +/work+ which then are used instead of those of the
 subhost tree. I.e. with an image file, the overlay root portion is at
 +$SUB/mnt/root+ and the associated work directory is at
 +$SUB/mnt/work+ (following the mounting of the image +$SUB.img+ onto
 +mnt+.

Networking
----------

Each subhost +$SUB+ gets set up with a network namespace +$SUB+, with
+veth+ virtual cabling for the +$BRIDGES+ it is declared to attach to.

The cable interfaces show up inside the +$SUB+ namespace as +eth0+,
+eth1+, etc., while the host side interfaces have +$SUB+ as prefix,
followed be the same number.


Examples
--------

.start a subhost named +future+
----
# ./control start future
----

Starting a subhost will enter a bash shell "inside" the subhost. The
subhost is "running" as long as that shell exists; it is basically
like the "init" of the sandboxed subhost.

When exiting a subhost, its mounts and network namespace hang around,
but all its processes have got killed. This is like a "hibernation
state" for the subhost, which may be restarted (without stopping)
using the start command again.

.stop a subhost named +future+
----
# ./control stop future
----

The stop command unmounts everything for the subhost and deletes the
network namespace.