editorial improvements

diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc
index 974759eefe157a48f3111924992156cbc23b36ad..c7c35084ff5931998e1c37321eb9bf856568ed0d 100644 (file)
--- a/overlay-boot.8.adoc
+++ b/overlay-boot.8.adoc
@@ -17,24 +17,23 @@ DESCRIPTION
 -----------
 *overlay-boot* is the main script in a small collection of
 administration scripts for containerizing services with minimal ado.
-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 script starts a "subhost" whose root filesystem is an overlay on
+the main host filesystem, and with separate mount, network and pid
+namespaces. In effect an administrative sandboxing that is
+prepopulated with a copy of the overlaid filesystem.
+
+The subhost is defined by means of a configuration file, __conf__,
+that is a simple text file with small collection of "variables"
+telling how the subhost is set up. *overlay-boot* spawns a subprocess
+that performs the boot-up of the "subhost" as an init script that ends
+with a pid 1 +reaper+ that simply "reaps" any terminated child
+processes.
 
 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.
+interactive shell within the subhost namespaces. Usually this is only
+used initially for configuring the subhost's network and set up an
+_sshd_ service for subsequent access.
 
 Subhost execution is stopped with *overlay-stop*.
 
@@ -200,24 +199,22 @@ possibly a different one upon each start.
 EXAMPLES
 --------
 
-=== /opt/subhost/mta/mta.conf
-****
+=== Smallest possible
 ----
+# mkdir -p /opt/subhost/copy/{root,work,live}
+# cat << EOF > /opt/subhost/copy/copy.conf
 BASE=.
-CABLES= =
-START= rsyslog networking ssh saslauthd postfix dovecot
+EOF
 ----
-****
 
-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.
+
+This setup has a minimal configuration for a subhost that overlays the
+root filesystem but is without networking. The subhost must be entered
+with *overlay-go*, although the default start might have started sshd
+listening on a loopback interface in the subhost's network namespaces.
+
+Note that *overlay-go* runs a shell within the namespaces, but not as
+a child of the "subhost init" (aka +.reaper+).
 
 === /opt/subhost/tiny/tiny.conf
 ****
@@ -225,19 +222,35 @@ neworking service.
 BASE=.
 CABLES= =
 START= none
-LOWER= !mkdir -p base work root live ; echo base
-WORK= work
-UPPER= root
-LIVE= live
+LOWER= base
 ----
 ****
 
 The +tiny+ subhost would be for overlaying a separate +debootstrap+
-root filesystem, without any services (since +START+ is empty). This
+root filesystem, without any services (since +START+ is "none"). 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.
 
+=== /opt/subhost/mta/mta.conf
+****
+----
+BASE=.
+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. 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.
+
 SEE ALSO
 --------