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 It starts a "subhost" with a dedicated network namespace, and the
  21 mount and pid namespaces separated from the main host by means of
  22 _unshare_, and the subhost root file system may be set up as an
  23 overlay of the main host filesystem, for keeping the subhost services
  24 distinctly separate from the main host.
  25
  26 A subhost is started by nominating its _configuration file_ on the
  27 command line for *overlay-boot*. This is a plain text file with a
  28 small collection of "variables" that tell how the subhost is set up.
  29 *overlay-boot* spawns a subprocess that invokes a command shell within
  30 an chroot into "unshared" subhost root filesystem, all similar to the
  31 bootup of any odd computer, and therafter the subhost "runs" in the
  32 way of a virtual machine or container environment.
  33
  34 The administrator may "enter" the subhost execution environment to
  35 perform adminstrative tasks by means of *overlay-go*, which starts an
  36 interactive shell within the subhost namespaces. The subhost may also
  37 be set up with users and an _sshd_ service as needed.
  38
  39 Subhost execution is stopped with *overlay-stop*.
  40
  41 OPTIONS
  42 -------
  43
  44 An *overlay-boot* subhost is defined in a configuration file that is a
  45 plain text file with a number of variable assignments. Each assignment
  46 is written with the varable name flush left and immediately followed
  47 by an equal sign, The rest of that line (ignoring leading and trailing
  48 spaces) is its value. But if that value startes with an exclamation
  49 mark, then the line is a command to run during start-up so as to
  50 generate the value. See examples below.
  51
  52 *NAME*::
  53
  54 This variable declares a short name for the subhost, and should be no
  55 more than 12 printable ascii characters. The base name of the
  56 configuration file is used by default. I.e., a configuration file
  57 named +foo.conf+ by default names its subhost +foo+ unless there is a
  58 +NAME+ variable says differently.
  59
  60 *BASE*::
  61
  62 This variable declares a pathname for a directory that is considered
  63 to be a "base" for the subhost setup. This is the only required
  64 variable.
  65 +
  66 A typical subhost setup is defined by a dedicated directory that
  67 contains the configuration file and the three mount points "root",
  68 "work" and "live".
  69
  70 *CABLES*::
  71
  72 This variable declares the subhost networking in terms of its virtual
  73 cables. The value is a space separated list of "virtual cable
  74 specifiers", each consisting of an equal sign optionally with a bridge
  75 name to the left and optionally a MAC address to the right. See the
  76 section on Networking below for more details.
  77
  78 INIT::
  79
  80 This variable is a command to run (with environment variable CONFIG
  81 set) that outputs on its standard output the series of commands for
  82 the running subhost. The default value for this variable is
  83 +/var/lib/overlay-boot/overlay-init+.
  84
  85 *LIVE*::
  86
  87 This variable nominates the mount point for the running subhost's root
  88 file system. It defaults to +$BASE/live+ The nominated directory must
  89 exist, and depending on the directory pathnames in the +UPPER+ and
  90 +LOWER+ variables, the subhost root filesystem is one of
  91 +
  92   1. a pre-mounted directory,
  93   2. bind mounted with UPPER, or
  94   3. and overlay mount of UPPER (and WORK) over LOWER. See also the
  95   UPPER variable below.
  96
  97 *LOG*::
  98
  99 This variable nominates the logfile to use by +overlay-boot+ when
 100 running the subhost. The default is +/tmp/overlay-$NAME.log+.
 101
 102 *LOWER*::
 103
 104 This variable nominates the "lower" filesystem of an overlay mount.
 105 This will be accessed read-only, and it is intended to be the
 106 operating system root file system. The default is +/+, i.e. the main
 107 host root filesystem. When overlay is not desired, then LOWER should
 108 be the smae as UPPER.
 109
 110 *POSTMOUNT*::
 111
 112 This variable is a command line to run (with environment variable
 113 CONFIG set) following the setup of the subhost root filesystem and
 114 before the services are started. The default for this variable is
 115 +/var/lib/overlay-mount/overlay-postmount+. Note that this command is
 116 executed within the mount namespace of the subhost, and still with the
 117 main host as root filesystem. The POSTMOUNT command is executed for
 118 all of the three different root filesystem setup variants.
 119
 120 *PREMOUNT*::
 121
 122 This variable is a command line to run (with environment variable
 123 CONFIG set) just before the setup of the subhost root filesystem and
 124 before the services are started. The default for this variable is
 125 +overlay-premount+ Note that this command is executed within the mount
 126 namespace of the subhost, and still with the main host as root
 127 filesystem. The PREMOUNT command is executed for both the overlay and
 128 bind mount variants of root filesystem setup but not for plain root
 129 filesystem, which does not involve mounting LIVE.
 130
 131 *RAM_SIZE*::
 132
 133 This variable configures the subhost +/run+ directory which by default
 134 is mounted as a +tmpfs+ of 50M. Use +none+ to avoid that mount, and
 135 otherwise the desired +tmpfs+ size.
 136
 137 *START*::
 138
 139 This variable names the services to be started on the overlay-boot
 140 startup. The default value is +networking ssh+.
 141 +
 142 Note that if no services are started, then +overlay-init+ starts a
 143 +dummy_service+ so as to keep +/.reaper+ from running out of child
 144 processes, as it otherwise will exit and thereby terminate
 145 +overlay-boot+.
 146
 147 *UPPER*::
 148
 149 This variable nominates the "upper" filesystem for an overlay mount.
 150 This will be accessed read-write and it constitutes the "private"
 151 files of the subhost.
 152 +
 153 If UPPER is different from LOWER, then the root file system is set up
 154 as an overlay mount. In that case WORK (below) must be defined as a
 155 directory outside of but on the same mount as UPPER.
 156 +
 157 If UPPER is the same as LOWER, then the subhost root filesystem is not
 158 setup as an overlay. Rather, if UPPER is different from LIVE, the root
 159 filesystem is set up as a bind mount, and if UPPER and LIVE are also
 160 the same, then LIVE is used as root filesystem without additional
 161 mounting.
 162
 163 *WORK*::
 164
 165 This variable nominates the "work" directory for an overlay mount. It
 166 has to be a writable directory on the same mount device as the UPPER
 167 directory.
 168
 169 *SHARE*::
 170
 171 This variable nominates a pathname under $LOWER to bind-mount onto the
 172 same pathname under $LIVE so as to share that directory tree into the
 173 overlay. The SHARE variable is a special configuration variable in
 174 that the value does not allow exclamation mark evaluation, and that it
 175 may occur many times for declaring multiple shared subdirectories.
 176
 177 Networking
 178 ----------
 179
 180 *overlay-boot* sets up a nework namespace named by the subhost
 181 +$NAME+, and uses the +CABLES+ variable to set up _veth_ type virtual
 182 cables. The host end of such cables are named by +$NAME+ followed by a
 183 number from 0 and up while the subhost end are named by +eth+ followed
 184 by the same number.
 185
 186 As mentioned above, +CABLES+ is a space separated list of cable
 187 specifiers, each consisting of an optional bridge interface name, an
 188 optional MAC adddress and with a required equal sign ("=") between
 189 them.
 190
 191 The bridge interface name, when given, will be given control of the
 192 host end cable interface. When the bridge interface name is omitted
 193 (empty) then the host end interface attracts an _ifup $IF_ attempt
 194 instead.
 195
 196 The MAC address, if given, is used for the subhost end cable
 197 interface, which otherise gets its MAC address from the kernel,
 198 possibly a different one upon each start.
 199
 200 EXAMPLES
 201 --------
 202
 203 === /opt/subhost/mta/mta.conf
 204 ****
 205 ----
 206 BASE=.
 207 CABLES= =
 208 START= rsyslog networking ssh saslauthd postfix dovecot
 209 ----
 210 ****
 211
 212 The above example assumes a directory +/opt/subhost/mta+ that contains
 213 the configuration file +mta.conf+ and directories +root+, +work+ and
 214 +live+. *overlay-boot* will set up an overlay mount on +live+ with
 215 +root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of
 216 the main host filesystem. Further, the running subhost will feature a
 217 virtual cable to the main host, where the subhost end is named +eth0+
 218 and the main host end is named +mta0+, and upon start, an +ifup mta0+
 219 is attempted at the host end while the subhost end is handled via its
 220 neworking service.
 221
 222 === /opt/subhost/tiny/tiny.conf
 223 ****
 224 ----
 225 BASE=.
 226 CABLES= =
 227 START= none
 228 LOWER= !mkdir -p base work root live ; echo base
 229 WORK= work
 230 UPPER= root
 231 LIVE= live
 232 ----
 233 ****
 234
 235 The +tiny+ subhost would be for overlaying a separate +debootstrap+
 236 root filesystem, without any services (since +START+ is empty). This
 237 gets started with a +dummy_service+ to hold the overlay for access via
 238 +overlay-go+. The +dummy_service+ sets up and listens on a pipe at
 239 +/run/dummy_service+, and exits when anything is written to that.
 240
 241 SEE ALSO
 242 --------
 243
 244 *overlay-stop*, *overlay-go*