DESCRIPTION
-----------
-*overlay-boot* is the main script on a small collection of
+*overlay-boot* is the main script in a small collection of
administration scripts for containerizing services with minimal ado.
-The script starts a "subhost" with a dedicated network namespace, and
-the mount and pid namespaces separated from the main host by means of
-+unshare+. A subhost root file system may in particular be set up as
-an overlay of the main host filesystem to keep the specifics of a
-service distinctly separate from the main host while sharing files
-wherever sensible.
-
-A subhost is started by identifyinf its configuration file on the
-command line for *overlay-boot*. The configuration file is a plain
-text file with a small collection of "variables" that tell how the
-subhost is set up. When all is good, *overlay-boot* spawns a
-subprocess that invokes a command shell within an chroot into
-"unshared" subhost root filesystem, all similar to the bootup of any
-odd computer.
-
-The subhost execution environment may be "entered" to perform
-adminstrative tasks with *overlay-go*, and it is later stopped with
-*overlay-stop*.
+It starts a "subhost" with a dedicated network namespace, and the
+mount and pid namespaces separated from the main host by means of
+_unshare_, and the subhost root file system may be set up as an
+overlay of the main host filesystem, for keeping the subhost services
+distinctly separate from the main host.
+
+A subhost is started by nominating its _configuration file_ on the
+command line for *overlay-boot*. This is a plain text file with a
+small collection of "variables" that tell how the subhost is set up.
+*overlay-boot* spawns a subprocess that invokes a command shell within
+an chroot into "unshared" subhost root filesystem, all similar to the
+bootup of any odd computer, and therafter the subhost "runs" in the
+way of a virtual machine or container environment.
+
+The administrator may "enter" the subhost execution environment to
+perform adminstrative tasks by means of *overlay-go*, which starts an
+interactive shell within the subhost namespaces. The subhost may also
+be set up with users and an _sshd_ service as needed.
+
+Subhost execution is stopped with *overlay-stop*.
OPTIONS
-------
-An overlay-boot subhost is defined in the configuration file, which is
-a plain text file with a number of variable assignments. Each
-assignment is written with the varable name flush left and immediately
-followed by an equal sign, The rest of that line (ignoring leading and
-trailing spaces) is its value, or if that value startes with an
-exclamation mark, then the line is a command to run so as to generate
-the value. See examples below.
+An *overlay-boot* subhost is defined in a configuration file that is a
+plain text file with a number of variable assignments. Each assignment
+is written with the varable name flush left and immediately followed
+by an equal sign, The rest of that line (ignoring leading and trailing
+spaces) is its value. But if that value startes with an exclamation
+mark, then the line is a command to run during start-up so as to
+generate the value. See examples below.
*NAME*::
This variable declares a pathname for a directory that is considered
to be a "base" for the subhost setup. This is the only required
variable.
++
+A typical subhost setup is defined by a dedicated directory that
+contains the configuration file and the three mount points "root",
+"work" and "live".
*CABLES*::
This variable declares the subhost networking in terms of its virtual
cables. The value is a space separated list of "virtual cable
specifiers", each consisting of an equal sign optionally with a bridge
-name to the left and optinally a MAC address to the right. See the
+name to the left and optionally a MAC address to the right. See the
section on Networking below for more details.
INIT::
-This variable is a command line to run, with envirnment variable
-CONFIG set, for producing the initial commands to the running subhost,
-similar to the initrd phase of a computer bootup. The default value
-for this variable is +overlay-init+.
+This variable is a command to run (with environment variable CONFIG
+set) that outputs on its standard output the series of commands for
+the running subhost. The default value for this variable is
++/var/lib/overlay-boot/overlay-init+.
*LIVE*::
This variable nominates the mount point for the running subhost's root
file system. It defaults to +$BASE/live+ The nominated directory must
exist, and depending on the directory pathnames in the +UPPER+ and
-+LOWER+ variables, the subhost root filesystem is either of a
-pre-mounted directory, bind mounted or overlay mounted directory. See
-the details of this with the UPPER variable below.
++LOWER+ variables, the subhost root filesystem is one of
++
+ 1. a pre-mounted directory,
+ 2. bind mounted with UPPER, or
+ 3. and overlay mount of UPPER (and WORK) over LOWER. See also the
+ UPPER variable below.
*LOG*::
*LOWER*::
This variable nominates the "lower" filesystem of an overlay mount.
-This will be accessed read-only, an it is intended to be the operating
-system root file system. The default is +/+, i.e. the main host root
-filesystem. When overlay is not desired, then LOWER should be the smae
-as UPPER.
+This will be accessed read-only, and it is intended to be the
+operating system root file system. The default is +/+, i.e. the main
+host root filesystem. When overlay is not desired, then LOWER should
+be the smae as UPPER.
*POSTMOUNT*::
-This variable is a command line to run, with envirnment variable
-CONFIG set, just after the setup of the subhost root filesystem and
+This variable is a command line to run (with environment variable
+CONFIG set) following the setup of the subhost root filesystem and
before the services are started. The default for this variable is
-+overlay-postmount+
++/var/lib/overlay-mount/overlay-postmount+. Note that this command is
+executed within the mount namespace of the subhost, and still with the
+main host as root filesystem. The POSTMOUNT command is executed for
+all of the three different root filesystem setup variants.
*PREMOUNT*::
-This variable is a command line to run, with envirnment variable
-CONFIG set, just before the setup of the subhost root filesystem and
+This variable is a command line to run (with environment variable
+CONFIG set) just before the setup of the subhost root filesystem and
before the services are started. The default for this variable is
-+overlay-premount+
++overlay-premount+ Note that this command is executed within the mount
+namespace of the subhost, and still with the main host as root
+filesystem. The PREMOUNT command is executed for both the overlay and
+bind mount variants of root filesystem setup but not for plain root
+filesystem, which does not involve mounting LIVE.
+
+*RAM_SIZE*::
+
+This variable configures the subhost +/run+ directory which by default
+is mounted as a +tmpfs+ of 50M. Use +none+ to avoid that mount, and
+otherwise the desired +tmpfs+ size.
+
+*START*::
+
+This variable names the services to be started on the overlay-boot
+startup. The default value is +networking ssh+.
++
+Note that if no services are started, then +overlay-init+ starts a
++dummy_service+ so as to keep +/.reaper+ from running out of child
+processes, as it otherwise will exit and thereby terminate
++overlay-boot+.
*UPPER*::
This variable nominates the "upper" filesystem for an overlay mount.
This will be accessed read-write and it constitutes the "private"
files of the subhost.
-
++
If UPPER is different from LOWER, then the root file system is set up
as an overlay mount. In that case WORK (below) must be defined as a
directory outside of but on the same mount as UPPER.
-
++
If UPPER is the same as LOWER, then the subhost root filesystem is not
-setup as an overla. Rather it is set up as a bind mount, if UPPER is
-different from LIVE, or just as a pre-mounted LIVE filesystem.
+setup as an overlay. Rather, if UPPER is different from LIVE, the root
+filesystem is set up as a bind mount, and if UPPER and LIVE are also
+the same, then LIVE is used as root filesystem without additional
+mounting.
*WORK*::
has to be a writable directory on the same mount device as the UPPER
directory.
-*START*::
-
-This variable tells which services should be started on the
-overlay-boot startup. The default value is +networking ssh+.
-
-Note that if no services are started, then +overlay-init+ starts a
-+dummy_service+ so as to keep +/.reaper+ from running out of child
-processes, as it otherwise will exit and thereby terminate
-+overlay-boot+.
-
-*RAM_SIZE*::
+*SHARE*::
-This variable may be used to configure the +/run+ directory which by
-defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use
-+none+ to avoid that mount, and otherwise the desired +tmpfs+ size.
+This variable nominates a pathname under $LOWER to bind-mount onto the
+same pathname under $LIVE so as to share that directory tree into the
+overlay. The SHARE variable is a special configuration variable in
+that the value does not allow exclamation mark evaluation, and that it
+may occur many times for declaring multiple shared subdirectories.
Networking
----------
-*overlay-boot* sets up a nework namespace named by the subhost NAME,
-and uses the CABLES variable to set up +veth+ virtual cables. The host
-end of such cables are named by NAME followed by a number from 0 and
-up while the subhost end are named by +eth+ followed by the same
-number.
+*overlay-boot* sets up a nework namespace named by the subhost
++$NAME+, and uses the +CABLES+ variable to set up _veth_ type virtual
+cables. The host end of such cables are named by +$NAME+ followed by a
+number from 0 and up while the subhost end are named by +eth+ followed
+by the same number.
-As mentioned above, CABLES consists of a space separated list of cable
-specifiers, each consisting of a bridge interface name and a with an
-equal sign ("=") between them. The equal sign is required while either
-or both of the bridge and MAC address may be left empty.
+As mentioned above, +CABLES+ is a space separated list of cable
+specifiers, each consisting of an optional bridge interface name, an
+optional MAC adddress and with a required equal sign ("=") between
+them.
-The bridge interface name, if given, will be given control of the host
-end cable interface. A cable specification with empty bridge name part
-results in that the host end is brought up at link level and then
-+ifup $IF+ is attempted.
+The bridge interface name, when given, will be given control of the
+host end cable interface. When the bridge interface name is omitted
+(empty) then the host end interface attracts an _ifup $IF_ attempt
+instead.
The MAC address, if given, is used for the subhost end cable
-interface. A cable specification with empty MAC address part results
-in that the interface get its MAC address from the kernel, possibly a
-different one upon each start.
+interface, which otherise gets its MAC address from the kernel,
+possibly a different one upon each start.
EXAMPLES
--------
-./opt/subhost/mta/mta.conf
+=== /opt/subhost/mta/mta.conf
****
+----
BASE=.
-START= rsyslog newtorking ssh postfix
+CABLES= =
+START= rsyslog networking ssh saslauthd postfix dovecot
+----
****
The above example assumes a directory +/opt/subhost/mta+ that contains
the configuration file +mta.conf+ and directories +root+, +work+ and
+live+. *overlay-boot* will set up an overlay mount on +live+ with
+root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of
-the main host filesystem.
+the main host filesystem. Further, the running subhost will feature a
+virtual cable to the main host, where the subhost end is named +eth0+
+and the main host end is named +mta0+, and upon start, an +ifup mta0+
+is attempted at the host end while the subhost end is handled via its
+neworking service.
+
+=== /opt/subhost/tiny/tiny.conf
+****
+----
+BASE=.
+CABLES= =
+START= none
+LOWER= !mkdir -p base work root live ; echo base
+WORK= work
+UPPER= root
+LIVE= live
+----
+****
+
+The +tiny+ subhost would be for overlaying a separate +debootstrap+
+root filesystem, without any services (since +START+ is empty). This
+gets started with a +dummy_service+ to hold the overlay for access via
++overlay-go+. The +dummy_service+ sets up and listens on a pipe at
++/run/dummy_service+, and exits when anything is written to that.
+
+SEE ALSO
+--------
+*overlay-stop*, *overlay-go*
projects / rrq / overlay-boot.git / blobdiff