overlay-boot.8.adoc

   1 overlay-boot(8)
   2 ===============
   3 :doctype: manpage
   4 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
   5 :COLON: :
   6 :EQUALS: =
   7
   8 NAME
   9 ----
  10 overlay-boot - Start a subhost with overlay root filesystem.
  11
  12 SYNOPSIS
  13 --------
  14 *overlay-boot* _conf_
  15
  16 DESCRIPTION
  17 -----------
  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 the default use case is merely an administrative
  23 sandboxing that is pre-populated with a copy of the overlaid
  24 filesystem.
  25
  26 Each subhost is defined by means of a configuration file, __conf__,
  27 that is a simple text file with small collection of "variables"
  28 telling how the subhost is set up. *overlay-boot* spawns a subprocess
  29 that performs the boot-up of the "subhost" as an init script that ends
  30 with a pid 1 +reaper+ that simply "reaps" any terminated child
  31 processes.
  32
  33 An administrator may "enter" the subhost execution environment to
  34 perform adminstrative tasks by means of *overlay-go*, which uses
  35 +chroot+ to start an interactive shell within the subhost namespaces.
  36 Such a shell however is not a child of the subhost +pid 1+ and it
  37 would normally only be used initially for configuring the subhost's
  38 network, and set up network based services, such as _sshd_, for
  39 subsequent access.
  40
  41 Subhost execution is stopped with *overlay-stop*.
  42
  43 OPTIONS
  44 -------
  45
  46 An *overlay-boot* subhost is defined in a configuration file that is a
  47 plain text file with a number of variable assignments. Each assignment
  48 is written with the varable name flush left and immediately followed
  49 by an equal sign, The rest of that line (ignoring leading and trailing
  50 spaces) is its value. But if that value startes with an exclamation
  51 mark, then the line is a command to run during start-up so as to
  52 generate the value. See examples below.
  53
  54 *NAME*::
  55
  56 This variable declares a short name for the subhost, and should be no
  57 more than 12 printable ascii characters. The base name of the
  58 configuration file is used by default. I.e., a configuration file
  59 named +foo.conf+ by default names its subhost +foo+ unless there is a
  60 +NAME+ variable says differently.
  61
  62 *BASE*::
  63
  64 This variable declares a pathname for a directory that is considered
  65 to be a "base" for the subhost setup. This is the only required
  66 variable.
  67 +
  68 A typical subhost setup is defined by a dedicated directory that
  69 contains the configuration file and the three mount points "root",
  70 "work" and "live".
  71
  72 *CABLES*::
  73
  74 This variable declares the subhost networking in terms of its virtual
  75 cables. The value is a space separated list of "virtual cable
  76 specifiers", each consisting of an equal sign optionally with a bridge
  77 name to the left and optionally a MAC address or VLAN tag to the
  78 right. See the section on Networking below for more details.
  79
  80 INIT::
  81
  82 This variable is a command to run (with environment variable CONFIG
  83 set) that outputs on its standard output the series of commands for
  84 the running subhost. The default value for this variable is
  85 +/var/lib/overlay-boot/overlay-init+.
  86
  87 *LIVE*::
  88
  89 This variable nominates the mount point for the running subhost's root
  90 file system. It defaults to +$BASE/live+ The nominated directory must
  91 exist, and depending on the directory pathnames in the +UPPER+ and
  92 +LOWER+ variables, the subhost root filesystem is one of
  93 +
  94   1. a pre-mounted directory,
  95   2. bind mounted with UPPER, or
  96   3. and overlay mount of UPPER (and WORK) over LOWER. See also the
  97   UPPER variable below.
  98
  99 *LOG*::
 100
 101 This variable nominates the logfile to use by +overlay-boot+ when
 102 running the subhost. The default is +/tmp/overlay-$NAME.log+.
 103
 104 *LOWER*::
 105
 106 This variable nominates the "lower" filesystem of an overlay mount.
 107 This will be accessed read-only, and it is intended to be the
 108 operating system root file system. The default is +/+, i.e. the main
 109 host root filesystem. When overlay is not desired, then LOWER should
 110 be the smae as UPPER.
 111
 112 *POSTMOUNT*::
 113
 114 This variable is a command line to run (with environment variable
 115 CONFIG set) following the setup of the subhost root filesystem and
 116 before the services are started. The default for this variable is
 117 +/var/lib/overlay-mount/overlay-postmount+. Note that this command is
 118 executed within the mount namespace of the subhost, and still with the
 119 main host as root filesystem. The POSTMOUNT command is executed for
 120 all of the three different root filesystem setup variants.
 121
 122 *PREMOUNT*::
 123
 124 This variable is a command line to run (with environment variable
 125 CONFIG set) just before the setup of the subhost root filesystem and
 126 before the services are started. The default for this variable is
 127 +overlay-premount+ Note that this command is executed within the mount
 128 namespace of the subhost, and still with the main host as root
 129 filesystem. The PREMOUNT command is executed for both the overlay and
 130 bind mount variants of root filesystem setup but not for plain root
 131 filesystem, which does not involve mounting LIVE.
 132
 133 *RAM_SIZE*::
 134
 135 This variable configures the subhost +/run+ directory which by default
 136 is mounted as a +tmpfs+ of 50M. Use +none+ to avoid that mount, and
 137 otherwise the desired +tmpfs+ size.
 138
 139 *START*::
 140
 141 This variable names the services to be started on the overlay-boot
 142 startup. The default value is +networking ssh+.
 143 +
 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
 147 +overlay-boot+.
 148
 149 *UPPER*::
 150
 151 This variable nominates the "upper" filesystem for an overlay mount.
 152 This will be accessed read-write and it constitutes the "private"
 153 files of the subhost.
 154 +
 155 If UPPER is different from LOWER, then the root file system is set up
 156 as an overlay mount. In that case WORK (below) must be defined as a
 157 directory outside of but on the same mount as UPPER.
 158 +
 159 If UPPER is the same as LOWER, then the subhost root filesystem is not
 160 setup as an overlay. Rather, if UPPER is different from LIVE, the root
 161 filesystem is set up as a bind mount, and if UPPER and LIVE are also
 162 the same, then LIVE is used as root filesystem without additional
 163 mounting.
 164
 165 *WORK*::
 166
 167 This variable nominates the "work" directory for an overlay mount. It
 168 has to be a writable directory on the same mount device as the UPPER
 169 directory.
 170
 171 *SHARE*::
 172
 173 This variable nominates a pathname under $LOWER to bind-mount onto the
 174 same pathname under $LIVE so as to share that directory tree into the
 175 overlay. The SHARE variable is a special configuration variable in
 176 that the value does not allow exclamation mark evaluation, and that it
 177 may occur many times for declaring multiple shared subdirectories.
 178
 179 Networking
 180 ----------
 181
 182 *overlay-boot* sets up a nework namespace named by the subhost
 183 +$NAME+, and uses the +CABLES+ variable to set up _veth_ type virtual
 184 cables. The host end of such cables are named by +$NAME+ followed by a
 185 number from 0 and up while the subhost end are named by +eth+ followed
 186 by the same number.
 187
 188 As mentioned above, +CABLES+ is a space separated list of cable
 189 specifiers, each consisting of an optional bridge interface name, an
 190 optional MAC adddress or VLAN tag and with a required equal sign ("=")
 191 between them.
 192
 193 The bridge interface name, when given, will be given control of the
 194 host end cable interface. When the bridge interface name is omitted
 195 (empty) then the host end interface attracts an _ifup $IF_ attempt
 196 instead.
 197
 198 The MAC address, if given, is used for the subhost end cable
 199 interface, which otherise gets its MAC address from the kernel,
 200 possibly a different one upon each start.
 201
 202 A VLAN tag has the format ".N" where N is a number between 1 and 4095.
 203 This modifies the cable function to set up a VLAN host interface on
 204 the prior host interface, and skip subhost side setup. E.g. if the
 205 prior host interface is +example1+ and the tag is +.302+ then the VLAN
 206 interface would be +example1.302+. The host side setup uses _ifup $IF_
 207 and thus, the host needs to have a supporting configuration entry in
 208 +/etc/network/interfaces+ for the VLAN interface.
 209
 210 Note that it may be a good practice to keep a local +interfaces+ file
 211 as sibling to the subhost configuration file on the host and use a
 212 _source_ statement to include this into the system networking
 213 configuration.
 214
 215 EXAMPLES
 216 --------
 217
 218 === Smallest possible
 219 ----
 220 # mkdir -p /opt/subhost/copy/{root,work,live}
 221 # cat << EOF > /opt/subhost/copy/copy.conf
 222 BASE=.
 223 EOF
 224 ----
 225
 226
 227 This setup has a minimal configuration for a subhost that overlays the
 228 root filesystem but is without networking. The subhost must be entered
 229 with *overlay-go*, although the default start might have started sshd
 230 listening on a loopback interface in the subhost's network namespaces.
 231
 232 Note that *overlay-go* runs a shell within the namespaces, but not as
 233 a child of the "subhost init" (aka +.reaper+).
 234
 235 === /opt/subhost/tiny/tiny.conf
 236 ****
 237 ----
 238 BASE=.
 239 CABLES= =
 240 START= none
 241 LOWER= base
 242 ----
 243 ****
 244
 245 The +tiny+ subhost would be for overlaying a separate +debootstrap+
 246 root filesystem, without any services (since +START+ is "none"). This
 247 gets started with a +dummy_service+ to hold the overlay for access via
 248 +overlay-go+. The +dummy_service+ sets up and listens on a pipe at
 249 +/run/dummy_service+, and exits when anything is written to that.
 250
 251 === /opt/subhost/mta/mta.conf
 252 ****
 253 ----
 254 BASE=.
 255 CABLES= =
 256 START= rsyslog networking ssh saslauthd postfix dovecot
 257 ----
 258 ****
 259
 260 The above example assumes a directory +/opt/subhost/mta+ that contains
 261 the configuration file +mta.conf+ and directories +root+, +work+ and
 262 +live+. *overlay-boot* will set up an overlay mount on +live+ with
 263 +root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of
 264 the main host filesystem. Further, the running subhost will feature a
 265 virtual cable to the main host, where the subhost end is named +eth0+
 266 and the main host end is named +mta0+, and upon start, an +ifup mta0+
 267 is attempted at the host end while the subhost end is handled via its
 268 neworking service.
 269
 270 SEE ALSO
 271 --------
 272
 273 *overlay-stop*, *overlay-go*