README.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* attempts to run a "subhost" with an overlay root
  19 filesystem. The subhost is defined in a configuration file named on
  20 the command line. When all is good, *overlay-boot* spawns a subprocess
  21 that invokes a command shell within an chroot into "unshared" overlay
  22 root filesystem, to perform service initialisations before ending up
  23 in an indefinitely running "reaper" process. The overlay subhost is
  24 essentially like a light container or virtual virtual machine for
  25 running services in a relatively contained way without too much of
  26 cross-wise interactions between them.
  27
  28 OPTIONS
  29 -------
  30
  31 An overlay-boot subhost is defined in the configuration file, which is
  32 a plain text file with a number of variable assignments.
  33
  34 *NAME*::
  35
  36 This variable declares the short name for the subhost, and should be
  37 no more than 12 printable ascii characters. The name of the
  38 configuration file is used by default.
  39
  40 *BASE*::
  41
  42 This variable declares a pathname for a directory that is considered
  43 to be a "base" for the subhost setup. This is the only required
  44 variable.
  45
  46 *CABLES*::
  47
  48 This variable declares the networking setup to use for the subhost
  49 through a space separated list of "virtual cable specifiers", each
  50 consisting of a (possibly empty) bridge interface name and a (possibly
  51 empty) MAC address with a (required) equal sign ("=") between them.
  52
  53 See the section on Networking below for more details.
  54
  55 *LIVE*::
  56
  57 This variable nominates the mount point for the overlay mount, and it
  58 defaults to +$BASE/live+ (which also must exist).
  59
  60 If LIVE and LOWER (below) are the same then this is assumed to be a
  61 pre-mounted root filesystem for the later chroot without any overlay
  62 mount being attempted.
  63
  64 *LOG*::
  65
  66 This variable nominates the log file to use by +overlay-boot+. The
  67 default is +/tmp/overlay-$NAME.log+.
  68
  69 *LOWER*::
  70
  71 This variable nominates the "lower" filesystem of the overlay. This
  72 will be accessed read-only, an it is intended to be the operating
  73 system root file system. The default is +/+, i.e. the main host root
  74 filesystem.
  75
  76 *UPPER*::
  77
  78 This variable nominates the "upper" filesystem for the overlay. This
  79 will be accessed read-write and constitutes the "private" files of the
  80 subhost.
  81
  82 If UPPER nominates an executable file raher than directory (i.e.
  83 program or script), then that will be run before overlay mounting with
  84 the environment variable ACTION set to "setup". The script must then
  85 print the pathname of the actual "upper" directory when successfully
  86 set up. Further upon termination of the subhost, that UPPER script
  87 will be run with ACTION set to "teardown".
  88
  89 *WORK*::
  90
  91 This variable nominates the "work" directory for the overlay mount. It
  92 has to be a writable directory on the same mount device as the UPPER
  93 directory.
  94
  95 *START*::
  96
  97 This variable tells which services should be started on the
  98 overlay-boot startup. They get started with +service $srv start+
  99 before the startup ends by running +/.reaper+ (which is automatically
 100 installed by +overlay-boot+). The default START includes +networking+
 101 and +ssh+.
 102
 103 Note that if no services are started, then a +dummy_service+ gets
 104 started so as to keep keep +/.reaper+ from running out of child
 105 processes, as it otherwise will exit and thereby terminate
 106 +overlay-boot+.
 107
 108 That +dummy_service+ may be killed by a signal, or by writing to the
 109 +/run/dummy_service+ pipe.
 110
 111 *RAM_SIZE*::
 112
 113 This variable may be used to configure the +/run+ directory which by
 114 defult gets mounted as a +tmpfs+ of 50M. Use +none+ to avoid that
 115 mount, and otherwise the desired tmpfs+ size.
 116
 117 Networking
 118 ----------
 119
 120 *overlay-boot* sets up a nework namespace named by the subhost NAME,
 121 and uses the CABLES variable to set up +veth+ virtual cables. The host
 122 end of such cables are named by NAME followed by a number from 0 and
 123 up while the subhost end are named by +eth+ followed by the same
 124 number.
 125
 126 As mentioned above, CABLES consists of a space separated list of cable
 127 specifiers, each consisting of a bridge interface name and a with an
 128 equal sign ("=") between them. The equal sign is required while either
 129 or both of the bridge and MAC address may be left empty.
 130
 131 The bridge interface name, if given, will be given control of the host
 132 end cable interface. A cable specification with empty bridge name part
 133 results in that the host end is brought up at link level and then
 134 +ifup $IF+ is attempted.
 135
 136 The MAC address, if given, is used for the subhost end cable
 137 interface. A cable specification with empty MAC address part results
 138 in that the interface get its MAC address from the kernel, possibly a
 139 different one upon each start.
 140
 141 boot-up
 142 -------
 143
 144 *overlay-boot* includes a small boot-up section that consists of the
 145 following command sequence:
 146 ----
 147 mount -t proc proc /proc
 148 mount -t devpts devpts /dev/pts
 149 mount -t sysfs sysfs /sys
 150 if [ "$RAM_SIZE" != "none" ] && ! grep -q '/run tmpfs' /proc/mounts ; then
 151     mount -t tmpfs -osize=$RAM_SIZE,mode=755 tmpfs /run
 152 fi
 153 for srv in $START ; do
 154     service $srv start
 155 done
 156 ----
 157 Thereafter the *overlay-boot* command shell (+/bin/sh+) morphs into
 158 running +/.reaper+ which simply waits and "reaps" child processes
 159 until it runs out of those and exist.