SYNOPSIS
--------
-*overlay-boot _conf_
+*overlay-boot* _conf_
DESCRIPTION
-----------
-*overlay-boot* attempts to run a "subhost" with an overlay root
-filesystem. The subhost is defined in a configuration file named on
-the command line. When all is good, *overlay-boot* spawns a subprocess
-that invokes a command shell within an chroot into "unshared" overlay
-root filesystem, to perform service initialisations before ending up
-in an indefinitely running "reaper" process. The overlay subhost is
-essentially like a light container or virtual virtual machine for
-running services in a relatively contained way without too much of
-cross-wise interactions between them.
+*overlay-boot* is the main script on 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*.
OPTIONS
-------
An overlay-boot subhost is defined in the configuration file, which is
-a plain text file with a number of variable assignments.
+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.
*NAME*::
-This variable declares the short name for the subhost, and should be
-no more than 12 printable ascii characters. The name of the
-configuration file is used by default.
+This variable declares a short name for the subhost, and should be no
+more than 12 printable ascii characters. The base name of the
+configuration file is used by default. I.e., a configuration file
+named +foo.conf+ by default names its subhost +foo+ unless there is a
++NAME+ variable says differently.
*BASE*::
*CABLES*::
-This variable declares the networking setup to use for the subhost
-through a space separated list of "virtual cable specifiers", each
-consisting of a (possibly empty) bridge interface name and a (possibly
-empty) MAC address with a (required) equal sign ("=") between them.
+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
+section on Networking below for more details.
-See the section on Networking below for more details.
+INIT::
-*LIVE*::
+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 nominates the mount point for the overlay mount, and it
-defaults to +$BASE/live+ (which also must exist).
+*LIVE*::
-If LIVE and LOWER (below) are the same then this is assumed to be a
-pre-mounted root filesystem for the later chroot without any overlay
-mount being attempted.
+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.
*LOG*::
-This variable nominates the log file to use by +overlay-boot+. The
-default is +/tmp/overlay-$NAME.log+.
+This variable nominates the logfile to use by +overlay-boot+ when
+running the subhost. The default is +/tmp/overlay-$NAME.log+.
*LOWER*::
-This variable nominates the "lower" filesystem of the overlay. This
-will be accessed read-only, an it is intended to be the operating
+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.
+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
+before the services are started. The default for this variable is
++overlay-postmount+
+
+*PREMOUNT*::
+
+This variable is a command line to run, with envirnment 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+
*UPPER*::
-This variable nominates the "upper" filesystem for the overlay. This
-will be accessed read-write and constitutes the "private" files of the
-subhost.
+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 nominates an executable file raher than directory (i.e.
-program or script), then that will be run before overlay mounting with
-the environment variable ACTION set to "setup". The script must then
-print the pathname of the actual "upper" directory when successfully
-set up. Further upon termination of the subhost, that UPPER script
-will be run with ACTION set to "teardown".
+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.
*WORK*::
-This variable nominates the "work" directory for the overlay mount. It
+This variable nominates the "work" directory for an overlay mount. It
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. They get started with +service $srv start+
-before the startup ends by running +/.reaper+ (which is automatically
-installed by +overlay-boot+). The default START includes +networking+
-and +ssh+.
+overlay-boot startup. The default value is +networking ssh+.
-Note that if no services are started, then a +dummy_service+ gets
-started so as to keep keep +/.reaper+ from running out of child
+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+.
-That +dummy_service+ may be killed by a signal, or by writing to the
-+/run/dummy_service+ pipe.
-
*RAM_SIZE*::
This variable may be used to configure the +/run+ directory which by
-defult gets mounted as a +tmpfs+ of 50M. Use +none+ to avoid that
-mount, and otherwise the desired tmpfs+ size.
+defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use
++none+ to avoid that mount, and otherwise the desired +tmpfs+ size.
Networking
----------
in that the interface get its MAC address from the kernel, possibly a
different one upon each start.
-boot-up
--------
+EXAMPLES
+--------
+
+./opt/subhost/mta/mta.conf
+****
+BASE=.
+CABLES= =
+START= rsyslog newtorking ssh postfix
+****
+
+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. 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.
+
+
-*overlay-boot* includes a small boot-up section that consists of the
-following command sequence:
-----
-mount -t proc proc /proc
-mount -t devpts devpts /dev/pts
-mount -t sysfs sysfs /sys
-if [ "$RAM_SIZE" != "none" ] && ! grep -q '/run tmpfs' /proc/mounts ; then
- mount -t tmpfs -osize=$RAM_SIZE,mode=755 tmpfs /run
-fi
-for srv in $START ; do
- service $srv start
-done
-----
-Thereafter the *overlay-boot* command shell (+/bin/sh+) morphs into
-running +/.reaper+ which simply waits and "reaps" child processes
-until it runs out of those and exist.
projects / rrq / overlay-boot.git / commitdiff