documenting prtend boot variant

diff --git a/README.adoc b/README.adoc
index b7195a996998a0ec23bbcf63f8cf25543a709a50..6547ccd7af709764f051bc5e15a79cb47b0fe1f8 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -1,11 +1,91 @@
 subhost scripts
 ===============
 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).
 
 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:
 originally +/opt/subhost+, and each subhost system is represented
 there as its own directory tree whose top level contains the
 following: