editorial improvements

diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc
index e97a8e4676cad9d8da15cc23f55f5469923e9ce0..01ae70904f37c19e364352530171bba5ae26a4a5 100644 (file)
--- a/overlay-boot.8.adoc
+++ b/overlay-boot.8.adoc
@@ -15,37 +15,39 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
 
 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.
 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 identifying 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
 -------
 
 
 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*::
 
 
 *NAME*::
 


@@ -60,30 +62,37 @@ named +foo.conf+ by default names its subhost +foo+ unless there is a
 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.
 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
 
 *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::
 
 section on Networking below for more details.
 
 INIT::
 

-This variable is a command line to run, with environment 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
 
 *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*::
 
 
 *LOG*::
 


@@ -93,28 +102,47 @@ running the subhost. The default is +/tmp/overlay-$NAME.log+.
 *LOWER*::
 
 This variable nominates the "lower" filesystem of an overlay mount.
 *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*::
 
 
 *POSTMOUNT*::
 

-This variable is a command line to run, with environment 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
 before the services are started. The default for this variable is

-+overlay-postmount+. Note that this command is executed within the
-mount namespace of the subhost, and still with the main host as root
-filesystem.
++/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*::
 
 
 *PREMOUNT*::
 

-This variable is a command line to run, with environment 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
 before the services are started. The default for this variable is

-+overlay-premount+  Note that this command is executed within the
-mount namespace of the subhost, and still with the main host as root
-filesystem.
++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*::
 
 
 *UPPER*::
 


@@ -127,8 +155,10 @@ 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
 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 overlay. It Is rather set up either as a bind mount if UPPER is
-different from LIVE, or just taken 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*::
 
 
 *WORK*::
 


@@ -136,50 +166,33 @@ 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.
 
 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*::
-
-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.
-

 Networking
 ----------
 
 *overlay-boot* sets up a nework namespace named by the subhost
 Networking
 ----------
 
 *overlay-boot* sets up a nework namespace named by the subhost

-+$NAME+, and uses the +$CABLES+ variable to set up +veth+ virtual
++$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.
 
 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
 
 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
 --------
 
 
 EXAMPLES
 --------
 

-./opt/subhost/mta/mta.conf
+=== /opt/subhost/mta/mta.conf

 ****
 ----
 BASE=.
 ****
 ----
 BASE=.


@@ -198,13 +211,13 @@ 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.
 
 is attempted at the host end while the subhost end is handled via its
 neworking service.
 

-./opt/subhost/tiny/tiny.conf
+=== /opt/subhost/tiny/tiny.conf

 ****
 ----
 BASE=.
 CABLES= =
 START= none
 ****
 ----
 BASE=.
 CABLES= =
 START= none

-LOWER=!mkdir -p base work root live ; echo base
+LOWER= !mkdir -p base work root live ; echo base

 WORK= work
 UPPER= root
 LIVE= live
 WORK= work
 UPPER= root
 LIVE= live