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 on a small collection of
19 administration scripts for containerizing services with minimal ado.
20 The script starts a "subhost" with a dedicated network namespace, and
21 the mount and pid namespaces separated from the main host by means of
22 +unshare+. A subhost root file system may in particular be set up as
23 an overlay of the main host filesystem to keep the specifics of a
24 service distinctly separate from the main host while sharing files
27 A subhost is started by identifying its configuration file on the
28 command line for *overlay-boot*. The configuration file is a plain
29 text file with a small collection of "variables" that tell how the
30 subhost is set up. When all is good, *overlay-boot* spawns a
31 subprocess that invokes a command shell within an chroot into
32 "unshared" subhost root filesystem, all similar to the bootup of any
35 The subhost execution environment may be "entered" to perform
36 adminstrative tasks with *overlay-go*, and it is later stopped with
42 An overlay-boot subhost is defined in the configuration file, which is
43 a plain text file with a number of variable assignments. Each
44 assignment is written with the varable name flush left and immediately
45 followed by an equal sign, The rest of that line (ignoring leading and
46 trailing spaces) is its value, or if that value startes with an
47 exclamation mark, then the line is a command to run so as to generate
48 the value. See examples below.
52 This variable declares a short name for the subhost, and should be no
53 more than 12 printable ascii characters. The base name of the
54 configuration file is used by default. I.e., a configuration file
55 named +foo.conf+ by default names its subhost +foo+ unless there is a
56 +NAME+ variable says differently.
60 This variable declares a pathname for a directory that is considered
61 to be a "base" for the subhost setup. This is the only required
66 This variable declares the subhost networking in terms of its virtual
67 cables. The value is a space separated list of "virtual cable
68 specifiers", each consisting of an equal sign optionally with a bridge
69 name to the left and optinally a MAC address to the right. See the
70 section on Networking below for more details.
74 This variable is a command line to run, with environment variable
75 CONFIG set, for producing the initial commands to the running subhost,
76 similar to the initrd phase of a computer bootup. The default value
77 for this variable is +overlay-init+.
81 This variable nominates the mount point for the running subhost's root
82 file system. It defaults to +$BASE/live+ The nominated directory must
83 exist, and depending on the directory pathnames in the +UPPER+ and
84 +LOWER+ variables, the subhost root filesystem is either of a
85 pre-mounted directory, bind mounted or overlay mounted directory. See
86 the details of this with the UPPER variable below.
90 This variable nominates the logfile to use by +overlay-boot+ when
91 running the subhost. The default is +/tmp/overlay-$NAME.log+.
95 This variable nominates the "lower" filesystem of an overlay mount.
96 This will be accessed read-only, an it is intended to be the operating
97 system root file system. The default is +/+, i.e. the main host root
98 filesystem. When overlay is not desired, then LOWER should be the smae
103 This variable is a command line to run, with environment variable
104 CONFIG set, just after the setup of the subhost root filesystem and
105 before the services are started. The default for this variable is
106 +overlay-postmount+. Note that this command is executed within the
107 mount namespace of the subhost, and still with the main host as root
112 This variable is a command line to run, with environment variable
113 CONFIG set, just before the setup of the subhost root filesystem and
114 before the services are started. The default for this variable is
115 +overlay-premount+ Note that this command is executed within the
116 mount namespace of the subhost, and still with the main host as root
121 This variable nominates the "upper" filesystem for an overlay mount.
122 This will be accessed read-write and it constitutes the "private"
123 files of the subhost.
125 If UPPER is different from LOWER, then the root file system is set up
126 as an overlay mount. In that case WORK (below) must be defined as a
127 directory outside of but on the same mount as UPPER.
129 If UPPER is the same as LOWER, then the subhost root filesystem is not
130 setup as an overlay. It Is rather set up either as a bind mount if UPPER is
131 different from LIVE, or just taken as a pre-mounted LIVE filesystem.
135 This variable nominates the "work" directory for an overlay mount. It
136 has to be a writable directory on the same mount device as the UPPER
141 This variable tells which services should be started on the
142 overlay-boot startup. The default value is +networking ssh+.
144 Note that if no services are started, then +overlay-init+ starts a
145 +dummy_service+ so as to keep +/.reaper+ from running out of child
146 processes, as it otherwise will exit and thereby terminate
151 This variable may be used to configure the +/run+ directory which by
152 defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use
153 +none+ to avoid that mount, and otherwise the desired +tmpfs+ size.
158 *overlay-boot* sets up a nework namespace named by the subhost
159 +$NAME+, and uses the +$CABLES+ variable to set up +veth+ virtual
160 cables. The host end of such cables are named by +$NAME+ followed by a
161 number from 0 and up while the subhost end are named by +eth+ followed
164 As mentioned above, +$CABLES+ consists of a space separated list of
165 cable specifiers, each consisting of a bridge interface name and a
166 with an equal sign ("=") between them. The equal sign is required
167 while either or both of the bridge and MAC address may be left empty.
169 The bridge interface name, if given, will be given control of the host
170 end cable interface. A cable specification with empty bridge name part
171 results in that the host end is brought up at link level and then
172 +ifup $IF+ is attempted.
174 The MAC address, if given, is used for the subhost end cable
175 interface. A cable specification with empty MAC address part results
176 in that the interface get its MAC address from the kernel, possibly a
177 different one upon each start.
182 ./opt/subhost/mta/mta.conf
187 START= rsyslog networking ssh saslauthd postfix dovecot
191 The above example assumes a directory +/opt/subhost/mta+ that contains
192 the configuration file +mta.conf+ and directories +root+, +work+ and
193 +live+. *overlay-boot* will set up an overlay mount on +live+ with
194 +root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of
195 the main host filesystem. Further, the running subhost will feature a
196 virtual cable to the main host, where the subhost end is named +eth0+
197 and the main host end is named +mta0+, and upon start, an +ifup mta0+
198 is attempted at the host end while the subhost end is handled via its
201 ./opt/subhost/tiny/tiny.conf
207 LOWER=!mkdir -p base work root live ; echo base
214 The +tiny+ subhost would be for overlaying a separate +debootstrap+
215 root filesystem, without any services (since +START+ is empty). This
216 gets started with a +dummy_service+ to hold the overlay for access via
217 +overlay-go+. The +dummy_service+ sets up and listens on a pipe at
218 +/run/dummy_service+, and exits when anything is written to that.
223 *overlay-stop*, *overlay-go*
projects / rrq / overlay-boot.git / blob