From: Ralph Ronnquist <ralph.ronnquist@gmail.com>
Date: Wed, 30 Mar 2022 21:49:50 +0000 (+1100)
Subject: added individual man pages
X-Git-Tag: deb_0.1.3~4
X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=03fde40e424f449064ac214be1d1fb499b42146e;p=rrq%2Foverlay-boot.git

added individual man pages
---

diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc
index 9646ee2..b2a1032 100644
--- a/overlay-boot.8.adoc
+++ b/overlay-boot.8.adoc
@@ -24,7 +24,7 @@ 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
+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
@@ -34,7 +34,7 @@ odd computer.
 
 The subhost execution environment may be "entered" to perform
 adminstrative tasks with *overlay-go*, and it is later stopped with
-*overlay-stop*.
+*overlay-stop*. 
 
 OPTIONS
 -------
@@ -151,16 +151,16 @@ defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use
 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+ 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+ 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.
 
 The bridge interface name, if given, will be given control of the host
 end cable interface. A cable specification with empty bridge name part
@@ -180,7 +180,7 @@ EXAMPLES
 ----
 BASE=.
 CABLES= =
-START= rsyslog networking ssh postfix
+START= rsyslog networking ssh saslauthd postfix dovecot
 ----
 ****
 
@@ -194,5 +194,26 @@ 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*
diff --git a/overlay-go.8.adoc b/overlay-go.8.adoc
new file mode 100644
index 0000000..4eab94f
--- /dev/null
+++ b/overlay-go.8.adoc
@@ -0,0 +1,40 @@
+overlay-go(8)
+=============
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+:COLON: :
+:EQUALS: =
+
+NAME
+----
+overlay-go - Start a shell within a subhost namespace environment.
+
+SYNOPSIS
+--------
+*overlay-go* _name_
+
+DESCRIPTION
+-----------
+*overlay-go* is an adminstration utility for entering the namespace
+environment of a "booted" subhost started witb +overlay-boot+. This
+starts a +bash+ shell within the subhost namespace, though not a child
+of its pid 1.
+
+OPTIONS
+-------
+
+no options.
+
+EXAMPLES
+--------
+
+====
+----
+overlay-go tiny
+----
+====
+
+SEE ALSO
+--------
+
+*overlay-boot*, *overlay-stop*
diff --git a/overlay-stop.8.adoc b/overlay-stop.8.adoc
new file mode 100644
index 0000000..3cd774f
--- /dev/null
+++ b/overlay-stop.8.adoc
@@ -0,0 +1,39 @@
+overlay-stop(8)
+=============
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+:COLON: :
+:EQUALS: =
+
+NAME
+----
+overlay-stop - Stop a subhost.
+
+SYNOPSIS
+--------
+*overlay-stop* _conf_
+
+DESCRIPTION
+-----------
+*overlay-stop* is an adminstration utility for terminating a subhost.
+This will stop its START services in reverse order, then forcefully
+kill the +reaper+ process if needed .
+
+OPTIONS
+-------
+
+no options.
+
+EXAMPLES
+--------
+
+====
+----
+overlay-stop tiny.conf
+----
+====
+
+SEE ALSO
+--------
+
+*overlay-boot*, *overlay-go*