README.adoc

   1 subhost scripts
   2 ===============
   3
   4 This is the script collection for a bespoke "sub host" platform for
   5 running sandboxed services directly on the infrastructure hosts rather
   6 than within virtual machines (VM).
   7
   8 It sets up the sub hosts fully within the $SUBHOST directory tree,
   9 originally +/opt/subhost+, and each subhost system is represented
  10 there as its own directory tree whose top level contains the
  11 following:
  12
  13  * +config+ is a bash include file that declares the subhost setup for
  14  the control script.
  15
  16  * +live+ is the root of the subhost filesystem when activated. It
  17  gets set up either as an +rbind+ mount of the subhost +root+ or as an
  18  +overlay+ mount placing the subhost +root+ over a common, read-only
  19  base filesystem.
  20
  21  * +root+ is the directory that contains the subhost filesystem (root
  22  filesystem). This may be the file system in full, or the writable
  23  part of the overlay filesystem.
  24
  25  * +work+ is the work directory for the overlay mount, unless the
  26  subhost is equipped with an image file for its root filesystem (in
  27  which case that image file offers the work directory)
  28
  29  * +mnt+ is optional. It is used as the mount target for the image
  30  file when the subhost has one.
  31
  32  * +$SUB.img+ (for the subhost named +$SUB+)is the optional image file
  33  for a subhost. The image file must itself have top directories
  34  +/root+ and +/work+ which then are used instead of those of the
  35  subhost tree. I.e. with an image file, the overlay root portion is at
  36  +$SUB/mnt/root+ and the associated work directory is at
  37  +$SUB/mnt/work+ (following the mounting of the image +$SUB.img+ onto
  38  +mnt+.
  39
  40 Networking
  41 ----------
  42
  43 Each subhost +$SUB+ gets set up with a network namespace +$SUB+, with
  44 +veth+ virtual cabling for the +$BRIDGES+ it is declared to attach to.
  45
  46 The cable interfaces show up inside the +$SUB+ namespace as +eth0+,
  47 +eth1+, etc., while the host side interfaces have +$SUB+ as prefix,
  48 followed be the same number.
  49
  50
  51 Examples
  52 --------
  53
  54 . start a subhost named +future+
  55 ----
  56 # ./control start future
  57 ----
  58
  59 Starting a subhost will enter a bash shell "inside" the subhost. The
  60 subhost is "running" as long as that shell exists; it is basically
  61 like the "init" of the sandboxed subhost.
  62
  63 When exiting a subhost, its mounts and network namespace hang around,
  64 but all its processes have got killed. This is like a "hibernation
  65 state" for the subhost, which may be restarted (without stopping)
  66 using the start command again.
  67
  68 . stop a subhost named +future+
  69 ----
  70 # ./control stop future
  71 ----
  72
  73 The stop command unmounts everything for the subhost and deletes the
  74 network namespace.