4 :font-family: sans-serif
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).
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.
20 # ./pretend-boot mysubhost
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.
27 1. +config+ configuration that defines +DISKS+ and +BRIDGES+
28 2. +live+ empty directory for the root filesystem mount
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.
35 **The +DISKS+ variable** is an array declaring the disks in terms the
36 partitions to mount. Each array element has three parts with ":"
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
43 The very first element of +DISKS+ is the subhost root filesystem,
44 which gets loop-mounted during the "pretend boot".
50 DISKS=( vda:1:/disks/disk1.raw vdb:1:/disks/disk2.raw )
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
58 1. the host bridge to link up with
59 2. the subhost interface's MAC address
65 BRIDGES=( homenet:06:a7:dd:b4:02:f2 )
68 Obviously the first ":" separates the bridge name from the MAC
69 address, which in itself includes 5 (more) ":" characters.
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.
85 The +control+ script is an alternative subhost run script used for
86 experimentation and debugging.
88 It sets up the subhosts fully within the $SUBHOST directory tree,
89 originally +/opt/subhost+, and each subhost system is represented
90 there as its own directory tree whose top level contains the
93 * +config+ is a bash include file that declares the subhost setup for
96 * +live+ is the root of the subhost filesystem when activated. It
97 gets set up either as an +rbind+ mount of the subhost +root+ or as an
98 +overlay+ mount placing the subhost +root+ over a common, read-only
101 * +root+ is the directory that contains the subhost filesystem (root
102 filesystem). This may be the file system in full, or the writable
103 part of the overlay filesystem.
105 * +work+ is the work directory for the overlay mount, unless the
106 subhost is equipped with an image file for its root filesystem (in
107 which case that image file offers the work directory)
109 * +mnt+ is optional. It is used as the mount target for the image
110 file when the subhost has one.
112 * +$SUB.img+ (for the subhost named +$SUB+)is the optional image file
113 for a subhost. The image file must itself have top directories
114 +/root+ and +/work+ which then are used instead of those of the
115 subhost tree. I.e. with an image file, the overlay root portion is at
116 +$SUB/mnt/root+ and the associated work directory is at
117 +$SUB/mnt/work+ (following the mounting of the image +$SUB.img+ onto
123 Each subhost +$SUB+ gets set up with a network namespace +$SUB+, with
124 +veth+ virtual cabling for the +$BRIDGES+ it is declared to attach to.
126 The cable interfaces show up inside the +$SUB+ namespace as +eth0+,
127 +eth1+, etc., while the host side interfaces have +$SUB+ as prefix,
128 followed be the same number.
134 .start a subhost named +future+
136 # ./control start future
139 Starting a subhost will enter a bash shell "inside" the subhost. The
140 subhost is "running" as long as that shell exists; it is basically
141 like the "init" of the sandboxed subhost.
143 When exiting a subhost, its mounts and network namespace hang around,
144 but all its processes have got killed. This is like a "hibernation
145 state" for the subhost, which may be restarted (without stopping)
146 using the start command again.
148 .stop a subhost named +future+
150 # ./control stop future
153 The stop command unmounts everything for the subhost and deletes the