From ded272bc01244508aac88f7420fc0d32a7d21add Mon Sep 17 00:00:00 2001
From: Ralph Ronnquist <ralph.ronnquist@gmail.com>
Date: Thu, 3 Mar 2022 16:51:27 +1100
Subject: [PATCH] documenting prtend boot variant

---
 README.adoc | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 82 insertions(+), 2 deletions(-)

diff --git a/README.adoc b/README.adoc
index b7195a9..6547ccd 100644
--- a/README.adoc
+++ b/README.adoc
@@ -1,11 +1,91 @@
 subhost scripts
 ===============
+:authors: rrq
+:font-family: sans-serif
 
-This is the script collection for a bespoke "sub host" platform for
+This is the script collection for a bespoke "subhost" 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,
+pretend-boot
+------------
+
+The +pretend-boot+ script works together with the +subhost-init+
+script to run a subhost almost as if booted in a virtual machine,
+except of course, that it really is merely an "unshared sandboxing"
+executed by the the host kernel.
+
+.Example
+----
+# ./pretend-boot mysubhost
+----
+
+The named subhost must then be set up in the directory
++/opt/sub/mysubhost+ with firstly a +config+ file and secondly a
++live+ subdirectory that will be used as root filesystem mount point.
+
+ 1. +config+ configuration that defines +DISKS+ and +BRIDGES+
+ 2. +live+ empty directory for the root filesystem mount
+
+The +config+ file is a textfile, or in fact a +bash+ source file, that
+should set the variables +DISKS+ and +BRIDGES+ for the subhost.
+
+
+====
+**The +DISKS+ variable** is an array declaring the disks in terms the
+paritions to mount. Each array element has three parts with ":"
+between them:
+
+ 1. the device node name to use in the subhost
+ 2. the partition index
+ 3. the disk image file on the host
+
+The very first element of +DISKS+ is the subhost root filesystem,
+which gets loop-mounted during the "pretend boot".
+====
+
+
+.Example of DISKS
+----
+DISKS=( vda:1:/disks/disk1.raw vdb:1:/disks/disk2.raw )
+----
+
+====
+**The +BRIDGES+ variable** is an array declaring the network interfaces in
+terms of their host appearance. Each array element has two parts with
+":" between them:
+
+ 1. the host bridge to link up with
+ 2. the subhost interface's MAC address
+====
+
+
+.Example of BRIDGES
+----
+BRIDGES=( homenet:06:a7:dd:b4:02:f2 )
+----
+
+Obviously the first ":" separates the bridge name from the MAC
+address, which in itself includes 5 (more) ":" characters.
+
+
+subhost-init
+------------
+
+The +subhost-init+ script is copied into the subhost root filesystem,
+and it first performs the rudimentary pre-pivot tasks (mounting "proc"
+etc.), the runs rcS and rc2 before entering into a plain wait for
+anyting to be written to +/run/initctl+ which works as an immediate
++poweroff+ for the subhost.
+
+
+control
+-------
+
+The +control+ script is an alternative subhost run script used for
+experimentation and debugging.
+
+It sets up the subhosts 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:
-- 
2.39.2