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 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
  25 wherever sensible.
  26
  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
  33 odd computer.
  34
  35 The subhost execution environment may be "entered" to perform
  36 adminstrative tasks with *overlay-go*, and it is later stopped with
  37 *overlay-stop*.
  38
  39 OPTIONS
  40 -------
  41
  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.
  49
  50 *NAME*::
  51
  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.
  57
  58 *BASE*::
  59
  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
  62 variable.
  63
  64 *CABLES*::
  65
  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.
  71
  72 INIT::
  73
  74 This variable is a command line to run, with envirnment 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+.
  78
  79 *LIVE*::
  80
  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.
  87
  88 *LOG*::
  89
  90 This variable nominates the logfile to use by +overlay-boot+ when
  91 running the subhost. The default is +/tmp/overlay-$NAME.log+.
  92
  93 *LOWER*::
  94
  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
  99 as UPPER.
 100
 101 *POSTMOUNT*::
 102
 103 This variable is a command line to run, with envirnment 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+
 107
 108 *PREMOUNT*::
 109
 110 This variable is a command line to run, with envirnment variable
 111 CONFIG set, just before the setup of the subhost root filesystem and
 112 before the services are started. The default for this variable is
 113 +overlay-premount+
 114
 115 *UPPER*::
 116
 117 This variable nominates the "upper" filesystem for an overlay mount.
 118 This will be accessed read-write and it constitutes the "private"
 119 files of the subhost.
 120 +
 121 If UPPER is different from LOWER, then the root file system is set up
 122 as an overlay mount. In that case WORK (below) must be defined as a
 123 directory outside of but on the same mount as UPPER.
 124 +
 125 If UPPER is the same as LOWER, then the subhost root filesystem is not
 126 setup as an overla. Rather it is set up as a bind mount, if UPPER is
 127 different from LIVE, or just as a pre-mounted LIVE filesystem.
 128
 129 *WORK*::
 130
 131 This variable nominates the "work" directory for an overlay mount. It
 132 has to be a writable directory on the same mount device as the UPPER
 133 directory.
 134
 135 *START*::
 136
 137 This variable tells which services should be started on the
 138 overlay-boot startup. The default value is +networking ssh+.
 139 +
 140 Note that if no services are started, then +overlay-init+ starts a
 141 +dummy_service+ so as to keep +/.reaper+ from running out of child
 142 processes, as it otherwise will exit and thereby terminate
 143 +overlay-boot+.
 144
 145 *RAM_SIZE*::
 146
 147 This variable may be used to configure the +/run+ directory which by
 148 defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use
 149 +none+ to avoid that mount, and otherwise the desired +tmpfs+ size.
 150
 151 Networking
 152 ----------
 153
 154 *overlay-boot* sets up a nework namespace named by the subhost
 155 +$NAME+, and uses the +$CABLES+ variable to set up +veth+ virtual
 156 cables. The host end of such cables are named by +$NAME+ followed by a
 157 number from 0 and up while the subhost end are named by +eth+ followed
 158 by the same number.
 159
 160 As mentioned above, +$CABLES+ consists of a space separated list of
 161 cable specifiers, each consisting of a bridge interface name and a
 162 with an equal sign ("=") between them. The equal sign is required
 163 while either or both of the bridge and MAC address may be left empty.
 164
 165 The bridge interface name, if given, will be given control of the host
 166 end cable interface. A cable specification with empty bridge name part
 167 results in that the host end is brought up at link level and then
 168 +ifup $IF+ is attempted.
 169
 170 The MAC address, if given, is used for the subhost end cable
 171 interface. A cable specification with empty MAC address part results
 172 in that the interface get its MAC address from the kernel, possibly a
 173 different one upon each start.
 174
 175 EXAMPLES
 176 --------
 177
 178 ./opt/subhost/mta/mta.conf
 179 ****
 180 ----
 181 BASE=.
 182 CABLES= =
 183 START= rsyslog networking ssh saslauthd postfix dovecot
 184 ----
 185 ****
 186
 187 The above example assumes a directory +/opt/subhost/mta+ that contains
 188 the configuration file +mta.conf+ and directories +root+, +work+ and
 189 +live+. *overlay-boot* will set up an overlay mount on +live+ with
 190 +root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of
 191 the main host filesystem. Further, the running subhost will feature a
 192 virtual cable to the main host, where the subhost end is named +eth0+
 193 and the main host end is named +mta0+, and upon start, an +ifup mta0+
 194 is attempted at the host end while the subhost end is handled via its
 195 neworking service.
 196
 197 ./opt/subhost/tiny/tiny.conf
 198 ****
 199 ----
 200 BASE=.
 201 CABLES= =
 202 START= none
 203 LOWER=!mkdir -p base work root live ; echo base
 204 WORK= work
 205 UPPER= root
 206 LIVE= live
 207 ----
 208 ****
 209
 210 The +tiny+ subhost would be for overlaying a separate +debootstrap+
 211 root filesystem, without any services (since +START+ is empty). This
 212 gets started with a +dummy_service+ to hold the overlay for access via
 213 +overlay-go+. The +dummy_service+ sets up and listens on a pipe at
 214 +/run/dummy_service+, and exits when anything is written to that.
 215
 216 SEE ALSO
 217 --------
 218
 219 *overlay-stop*, *overlay-go*