README.adoc

   1 subhost scripts
   2 ===============
   3 :authors: rrq
   4 :font-family: sans-serif
   5
   6 This is the script collection for a bespoke "subhost" platform for
   7 running sandboxed services directly on the infrastructure hosts rather
   8 than within virtual machines (VM).
   9
  10 pretend-boot
  11 ------------
  12
  13 The +pretend-boot+ script works together with the +subhost-init+
  14 script to run a subhost almost as if booted in a virtual machine,
  15 except of course, that it really is merely an "unshared sandboxing"
  16 executed by the the host kernel.
  17
  18 .Example
  19 ----
  20 # ./pretend-boot mysubhost
  21 ----
  22
  23 The named subhost must then be set up in the directory
  24 +/opt/sub/mysubhost+ with firstly a +config+ file and secondly a
  25 +live+ subdirectory that will be used as root filesystem mount point.
  26
  27  1. +config+ configuration that defines +DISKS+ and +BRIDGES+
  28  2. +live+ empty directory for the root filesystem mount
  29
  30 The +config+ file is a textfile, or in fact a +bash+ source file, that
  31 should set the variables +DISKS+ and +BRIDGES+ for the subhost.
  32
  33
  34 ====
  35 **The +DISKS+ variable** is an array declaring the disks in terms the
  36 partitions to mount. Each array element has three parts with ":"
  37 between them:
  38
  39  1. the device node name to use in the subhost
  40  2. the partition index
  41  3. the disk image file on the host
  42
  43 The very first element of +DISKS+ is the subhost root filesystem,
  44 which gets loop-mounted during the "pretend boot".
  45 ====
  46
  47
  48 .Example of DISKS
  49 ----
  50 DISKS=( vda:1:/disks/disk1.raw vdb:1:/disks/disk2.raw )
  51 ----
  52
  53 ====
  54 **The +BRIDGES+ variable** is an array declaring the network interfaces in
  55 terms of their host appearance. Each array element has two parts with
  56 ":" between them:
  57
  58  1. the host bridge to link up with
  59  2. the subhost interface's MAC address
  60 ====
  61
  62
  63 .Example of BRIDGES
  64 ----
  65 BRIDGES=( homenet:06:a7:dd:b4:02:f2 )
  66 ----
  67
  68 Obviously the first ":" separates the bridge name from the MAC
  69 address, which in itself includes 5 (more) ":" characters.
  70
  71
  72 subhost-init
  73 ------------
  74
  75 The +subhost-init+ script is copied into the subhost root filesystem,
  76 and it first performs the rudimentary pre-pivot tasks (mounting "proc"
  77 etc.), the runs rcS and rc2 before entering into a plain wait for
  78 anything to be written to +/run/initctl+ which works as an immediate
  79 +poweroff+ for the subhost.
  80
  81 '''
  82 '''
  83 '''
  84
  85 control
  86 -------
  87
  88 The +control+ script is an alternative subhost run script used for
  89 experimentation and debugging.
  90
  91 It sets up the subhosts fully within the $SUBHOST directory tree,
  92 originally +/opt/subhost+, and each subhost system is represented
  93 there as its own directory tree whose top level contains the
  94 following:
  95
  96  * +config+ is a bash include file that declares the subhost setup for
  97  the control script.
  98
  99  * +live+ is the root of the subhost filesystem when activated. It
 100  gets set up either as an +rbind+ mount of the subhost +root+ or as an
 101  +overlay+ mount placing the subhost +root+ over a common, read-only
 102  base filesystem.
 103
 104  * +root+ is the directory that contains the subhost filesystem (root
 105  filesystem). This may be the file system in full, or the writable
 106  part of the overlay filesystem.
 107
 108  * +work+ is the work directory for the overlay mount, unless the
 109  subhost is equipped with an image file for its root filesystem (in
 110  which case that image file offers the work directory)
 111
 112  * +mnt+ is optional. It is used as the mount target for the image
 113  file when the subhost has one.
 114
 115  * +$SUB.img+ (for the subhost named +$SUB+)is the optional image file
 116  for a subhost. The image file must itself have top directories
 117  +/root+ and +/work+ which then are used instead of those of the
 118  subhost tree. I.e. with an image file, the overlay root portion is at
 119  +$SUB/mnt/root+ and the associated work directory is at
 120  +$SUB/mnt/work+ (following the mounting of the image +$SUB.img+ onto
 121  +mnt+.
 122
 123 Networking
 124 ----------
 125
 126 Each subhost +$SUB+ gets set up with a network namespace +$SUB+, with
 127 +veth+ virtual cabling for the +$BRIDGES+ it is declared to attach to.
 128
 129 The cable interfaces show up inside the +$SUB+ namespace as +eth0+,
 130 +eth1+, etc., while the host side interfaces have +$SUB+ as prefix,
 131 followed be the same number.
 132
 133
 134 Examples
 135 --------
 136
 137 .start a subhost named +future+
 138 ----
 139 # ./control start future
 140 ----
 141
 142 Starting a subhost will enter a bash shell "inside" the subhost. The
 143 subhost is "running" as long as that shell exists; it is basically
 144 like the "init" of the sandboxed subhost.
 145
 146 When exiting a subhost, its mounts and network namespace hang around,
 147 but all its processes have got killed. This is like a "hibernation
 148 state" for the subhost, which may be restarted (without stopping)
 149 using the start command again.
 150
 151 .stop a subhost named +future+
 152 ----
 153 # ./control stop future
 154 ----
 155
 156 The stop command unmounts everything for the subhost and deletes the
 157 network namespace.