subhost scripts
===============
:authors: rrq
:font-family: sans-serif

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

pretend-boot
------------

The +pretend-boot+ script runs a subhost almost as if booted in a
virtual machine, except of course, that it really is merely an
"unshared sandboxing" executed by the the host kernel.

.Example
----
# ./pretend-boot mysubhost
----

+pretend-boot+ sets up the +/opt/sub/mysubhost/live+ directory that it
uses as root filesystem mount point. It requires the variables DISKS
and BRIDGES to be set, either as environment variables, or via a
configuration file that it by default expects to find at
+/opt/sub/mysubhost/config+ That +config+ would be a textfile, or in
fact a +bash+ source file, that should set the variables +DISKS+ and
+BRIDGES+ for running the subhost.

====
**The +DISKS+ variable** is an array declaring the disks in terms the
partitions to mount. Each array element has three parts with ":"
between them:

 1. the device node name to use in the subhost
 2. the partition index
 3. the disk image file on the host

The very first element of +DISKS+ is the subhost root filesystem,
which gets loop-mounted during the "pretend boot".
====


.Example of DISKS
----
DISKS=( vda:1:/disks/disk1.raw vdb:1:/disks/disk2.raw )
----

====
**The +BRIDGES+ variable** is an array declaring the network interfaces in
terms of their host appearance. Each array element has two parts with
":" between them:

 1. the host bridge to link up with
 2. the subhost interface's MAC address
====


.Example of BRIDGES
----
BRIDGES=( homenet:06:a7:dd:b4:02:f2 )
----

Obviously the first ":" separates the bridge name from the MAC
address, which in itself includes 5 (more) ":" characters.


subhost-init
------------

The +subhost-init+ script is copied into the subhost root filesystem,
and it first performs the rudimentary pre-pivot tasks (mounting "proc"
etc.), the runs rcS and rc2 before entering into a plain wait for
anything to be written to +/run/initctl+ which works as an immediate
+poweroff+ for the subhost.

'''
'''
'''

control
-------

The +control+ script is an alternative subhost run script used for
experimentation and debugging.

It sets up the subhosts 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.