initial README also man page

README.adoc

@@ -0,0 +1,159 @@
+overlay-boot(8)
+===============
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+:COLON: :
+:EQUALS: =
+
+NAME
+----
+overlay-boot - Start a subhost with overlay root filesystem.
+
+SYNOPSIS
+--------
+*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.
+
+OPTIONS
+-------
+
+An overlay-boot subhost is defined in the configuration file, which is
+a plain text file with a number of variable assignments.
+
+*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.
+
+*BASE*::
+
+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.
+
+*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.
+
+See the section on Networking below for more details.
+
+*LIVE*::
+
+This variable nominates the mount point for the overlay mount, and it
+defaults to +$BASE/live+ (which also must exist).
+
+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.
+
+*LOG*::
+
+This variable nominates the log file to use by +overlay-boot+. 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
+system root file system. The default is +/+, i.e. the main host root
+filesystem.
+
+*UPPER*::
+
+This variable nominates the "upper" filesystem for the overlay. This
+will be accessed read-write and 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".
+
+*WORK*::
+
+This variable nominates the "work" directory for the 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+.
+
+Note that if no services are started, then a +dummy_service+ gets
+started so as to keep 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.
+
+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.
+
+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
+results in that the host end is brought up at link level and then
++ifup $IF+ is attempted.
+
+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.
+
+boot-up
+-------
+
+*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.