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