4 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
10 overlay-boot - Start a subhost with overlay root filesystem.
18 *overlay-boot* is the main script in a small collection of
19 administration scripts for containerizing services with minimal ado.
20 The script starts a "subhost" whose root filesystem is an overlay on
21 the main host filesystem, and with separate mount, network and pid
22 namespaces. In effect an administrative sandboxing that is
23 prepopulated with a copy of the overlaid filesystem.
25 The subhost is defined by means of a configuration file, __conf__,
26 that is a simple text file with small collection of "variables"
27 telling how the subhost is set up. *overlay-boot* spawns a subprocess
28 that performs the boot-up of the "subhost" as an init script that ends
29 with a pid 1 +reaper+ that simply "reaps" any terminated child
32 The administrator may "enter" the subhost execution environment to
33 perform adminstrative tasks by means of *overlay-go*, which starts an
34 interactive shell within the subhost namespaces. Usually this is only
35 used initially for configuring the subhost's network and set up an
36 _sshd_ service for subsequent access.
38 Subhost execution is stopped with *overlay-stop*.
43 An *overlay-boot* subhost is defined in a configuration file that is a
44 plain text file with a number of variable assignments. Each assignment
45 is written with the varable name flush left and immediately followed
46 by an equal sign, The rest of that line (ignoring leading and trailing
47 spaces) is its value. But if that value startes with an exclamation
48 mark, then the line is a command to run during start-up so as to
49 generate the value. See examples below.
53 This variable declares a short name for the subhost, and should be no
54 more than 12 printable ascii characters. The base name of the
55 configuration file is used by default. I.e., a configuration file
56 named +foo.conf+ by default names its subhost +foo+ unless there is a
57 +NAME+ variable says differently.
61 This variable declares a pathname for a directory that is considered
62 to be a "base" for the subhost setup. This is the only required
65 A typical subhost setup is defined by a dedicated directory that
66 contains the configuration file and the three mount points "root",
71 This variable declares the subhost networking in terms of its virtual
72 cables. The value is a space separated list of "virtual cable
73 specifiers", each consisting of an equal sign optionally with a bridge
74 name to the left and optionally a MAC address to the right. See the
75 section on Networking below for more details.
79 This variable is a command to run (with environment variable CONFIG
80 set) that outputs on its standard output the series of commands for
81 the running subhost. The default value for this variable is
82 +/var/lib/overlay-boot/overlay-init+.
86 This variable nominates the mount point for the running subhost's root
87 file system. It defaults to +$BASE/live+ The nominated directory must
88 exist, and depending on the directory pathnames in the +UPPER+ and
89 +LOWER+ variables, the subhost root filesystem is one of
91 1. a pre-mounted directory,
92 2. bind mounted with UPPER, or
93 3. and overlay mount of UPPER (and WORK) over LOWER. See also the
98 This variable nominates the logfile to use by +overlay-boot+ when
99 running the subhost. The default is +/tmp/overlay-$NAME.log+.
103 This variable nominates the "lower" filesystem of an overlay mount.
104 This will be accessed read-only, and it is intended to be the
105 operating system root file system. The default is +/+, i.e. the main
106 host root filesystem. When overlay is not desired, then LOWER should
107 be the smae as UPPER.
111 This variable is a command line to run (with environment variable
112 CONFIG set) following the setup of the subhost root filesystem and
113 before the services are started. The default for this variable is
114 +/var/lib/overlay-mount/overlay-postmount+. Note that this command is
115 executed within the mount namespace of the subhost, and still with the
116 main host as root filesystem. The POSTMOUNT command is executed for
117 all of the three different root filesystem setup variants.
121 This variable is a command line to run (with environment variable
122 CONFIG set) just before the setup of the subhost root filesystem and
123 before the services are started. The default for this variable is
124 +overlay-premount+ Note that this command is executed within the mount
125 namespace of the subhost, and still with the main host as root
126 filesystem. The PREMOUNT command is executed for both the overlay and
127 bind mount variants of root filesystem setup but not for plain root
128 filesystem, which does not involve mounting LIVE.
132 This variable configures the subhost +/run+ directory which by default
133 is mounted as a +tmpfs+ of 50M. Use +none+ to avoid that mount, and
134 otherwise the desired +tmpfs+ size.
138 This variable names the services to be started on the overlay-boot
139 startup. The default value is +networking ssh+.
141 Note that if no services are started, then +overlay-init+ starts a
142 +dummy_service+ so as to keep +/.reaper+ from running out of child
143 processes, as it otherwise will exit and thereby terminate
148 This variable nominates the "upper" filesystem for an overlay mount.
149 This will be accessed read-write and it constitutes the "private"
150 files of the subhost.
152 If UPPER is different from LOWER, then the root file system is set up
153 as an overlay mount. In that case WORK (below) must be defined as a
154 directory outside of but on the same mount as UPPER.
156 If UPPER is the same as LOWER, then the subhost root filesystem is not
157 setup as an overlay. Rather, if UPPER is different from LIVE, the root
158 filesystem is set up as a bind mount, and if UPPER and LIVE are also
159 the same, then LIVE is used as root filesystem without additional
164 This variable nominates the "work" directory for an overlay mount. It
165 has to be a writable directory on the same mount device as the UPPER
170 This variable nominates a pathname under $LOWER to bind-mount onto the
171 same pathname under $LIVE so as to share that directory tree into the
172 overlay. The SHARE variable is a special configuration variable in
173 that the value does not allow exclamation mark evaluation, and that it
174 may occur many times for declaring multiple shared subdirectories.
179 *overlay-boot* sets up a nework namespace named by the subhost
180 +$NAME+, and uses the +CABLES+ variable to set up _veth_ type virtual
181 cables. The host end of such cables are named by +$NAME+ followed by a
182 number from 0 and up while the subhost end are named by +eth+ followed
185 As mentioned above, +CABLES+ is a space separated list of cable
186 specifiers, each consisting of an optional bridge interface name, an
187 optional MAC adddress and with a required equal sign ("=") between
190 The bridge interface name, when given, will be given control of the
191 host end cable interface. When the bridge interface name is omitted
192 (empty) then the host end interface attracts an _ifup $IF_ attempt
195 The MAC address, if given, is used for the subhost end cable
196 interface, which otherise gets its MAC address from the kernel,
197 possibly a different one upon each start.
202 === Smallest possible
204 # mkdir -p /opt/subhost/copy/{root,work,live}
205 # cat << EOF > /opt/subhost/copy/copy.conf
211 This setup has a minimal configuration for a subhost that overlays the
212 root filesystem but is without networking. The subhost must be entered
213 with *overlay-go*, although the default start might have started sshd
214 listening on a loopback interface in the subhost's network namespaces.
216 Note that *overlay-go* runs a shell within the namespaces, but not as
217 a child of the "subhost init" (aka +.reaper+).
219 === /opt/subhost/tiny/tiny.conf
229 The +tiny+ subhost would be for overlaying a separate +debootstrap+
230 root filesystem, without any services (since +START+ is "none"). This
231 gets started with a +dummy_service+ to hold the overlay for access via
232 +overlay-go+. The +dummy_service+ sets up and listens on a pipe at
233 +/run/dummy_service+, and exits when anything is written to that.
235 === /opt/subhost/mta/mta.conf
240 START= rsyslog networking ssh saslauthd postfix dovecot
244 The above example assumes a directory +/opt/subhost/mta+ that contains
245 the configuration file +mta.conf+ and directories +root+, +work+ and
246 +live+. *overlay-boot* will set up an overlay mount on +live+ with
247 +root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of
248 the main host filesystem. Further, the running subhost will feature a
249 virtual cable to the main host, where the subhost end is named +eth0+
250 and the main host end is named +mta0+, and upon start, an +ifup mta0+
251 is attempted at the host end while the subhost end is handled via its
257 *overlay-stop*, *overlay-go*