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 an administrative sandboxing that is
  23 prepopulated with a copy of the overlaid filesystem.
  24
  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
  30 processes.
  31
  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.
  37
  38 Subhost execution is stopped with *overlay-stop*.
  39
  40 OPTIONS
  41 -------
  42
  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.
  50
  51 *NAME*::
  52
  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.
  58
  59 *BASE*::
  60
  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
  63 variable.
  64 +
  65 A typical subhost setup is defined by a dedicated directory that
  66 contains the configuration file and the three mount points "root",
  67 "work" and "live".
  68
  69 *CABLES*::
  70
  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.
  76
  77 INIT::
  78
  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+.
  83
  84 *LIVE*::
  85
  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
  90 +
  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
  94   UPPER variable below.
  95
  96 *LOG*::
  97
  98 This variable nominates the logfile to use by +overlay-boot+ when
  99 running the subhost. The default is +/tmp/overlay-$NAME.log+.
 100
 101 *LOWER*::
 102
 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.
 108
 109 *POSTMOUNT*::
 110
 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.
 118
 119 *PREMOUNT*::
 120
 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.
 129
 130 *RAM_SIZE*::
 131
 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.
 135
 136 *START*::
 137
 138 This variable names the services to be started on the overlay-boot
 139 startup. The default value is +networking ssh+.
 140 +
 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
 144 +overlay-boot+.
 145
 146 *UPPER*::
 147
 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.
 151 +
 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.
 155 +
 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
 160 mounting.
 161
 162 *WORK*::
 163
 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
 166 directory.
 167
 168 *SHARE*::
 169
 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.
 175
 176 Networking
 177 ----------
 178
 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
 183 by the same number.
 184
 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
 188 them.
 189
 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
 193 instead.
 194
 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.
 198
 199 EXAMPLES
 200 --------
 201
 202 === Smallest possible
 203 ----
 204 # mkdir -p /opt/subhost/copy/{root,work,live}
 205 # cat << EOF > /opt/subhost/copy/copy.conf
 206 BASE=.
 207 EOF
 208 ----
 209
 210
 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.
 215
 216 Note that *overlay-go* runs a shell within the namespaces, but not as
 217 a child of the "subhost init" (aka +.reaper+).
 218
 219 === /opt/subhost/tiny/tiny.conf
 220 ****
 221 ----
 222 BASE=.
 223 CABLES= =
 224 START= none
 225 LOWER= base
 226 ----
 227 ****
 228
 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.
 234
 235 === /opt/subhost/mta/mta.conf
 236 ****
 237 ----
 238 BASE=.
 239 CABLES= =
 240 START= rsyslog networking ssh saslauthd postfix dovecot
 241 ----
 242 ****
 243
 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
 252 neworking service.
 253
 254 SEE ALSO
 255 --------
 256
 257 *overlay-stop*, *overlay-go*