some write-up

diff --git a/README.adoc b/README.adoc
new file mode 100644 (file)
index 0000000..3d6ed0d
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,74 @@
+subhost scripts
+===============
+
+This is the script collection for a bespoke "sub host" platform for
+running sandboxed services directly on the infrastructure hosts rather
+than within virtual machines (VM).
+
+It sets up the sub hosts fully within the $SUBHOST directory tree,
+originally +/opt/subhost+, and each subhost system is represented
+there as its own directory tree whose top level contains the
+following:
+
+ * +config+ is a bash include file that declares the subhost setup for
+ the control script.
+
+ * +live+ is the root of the subhost filesystem when activated. It
+ gets set up either as an +rbind+ mount of the subhost +root+ or as an
+ +overlay+ mount placing the subhost +root+ over a common, read-only
+ base filesystem.
+
+ * +root+ is the directory that contains the subhost filesystem (root
+ filesystem). This may be the file system in full, or the writable
+ part of the overlay filesystem.
+
+ * +work+ is the work directory for the overlay mount, unless the
+ subhost is equipped with an image file for its root filesystem (in
+ which case that image file offers the work directory)
+
+ * +mnt+ is optional. It is used as the mount target for the image
+ file when the subhost has one.
+
+ * +$SUB.img+ (for the subhost named +$SUB+)is the optional image file
+ for a subhost. The image file must itself have top directories
+ +/root+ and +/work+ which then are used instead of those of the
+ subhost tree. I.e. with an image file, the overlay root portion is at
+ +$SUB/mnt/root+ and the associated work directory is at
+ +$SUB/mnt/work+ (following the mounting of the image +$SUB.img+ onto
+ +mnt+.
+
+Networking
+----------
+
+Each subhost +$SUB+ gets set up with a network namespace +$SUB+, with
++veth+ virtual cabling for the +$BRIDGES+ it is declared to attach to.
+
+The cable interfaces show up inside the +$SUB+ namespace as +eth0+,
++eth1+, etc., while the host side interfaces have +$SUB+ as prefix,
+followed be the same number.
+
+
+Examples
+--------
+
+. start a subhost named +future+
+----
+# ./control start future
+----
+
+Starting a subhost will enter a bash shell "inside" the subhost. The
+subhost is "running" as long as that shell exists; it is basically
+like the "init" of the sandboxed subhost.
+
+When exiting a subhost, its mounts and network namespace hang around,
+but all its processes have got killed. This is like a "hibernation
+state" for the subhost, which may be restarted (without stopping)
+using the start command again.
+
+. stop a subhost named +future+
+----
+# ./control stop future
+----
+
+The stop command unmounts everything for the subhost and deletes the
+network namespace.