Revised pretend-boot description

[rrq/subhost.git] / README.adoc

diff --git a/README.adoc b/README.adoc
index b7195a996998a0ec23bbcf63f8cf25543a709a50..e1ebe93ea560be845dea593022df42eeaff353d2 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -1,11 +1,90 @@
 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 runs 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
+----
+
++pretend-boot+ sets up the +/opt/sub/mysubhost/live+ directory that it
+uses as root filesystem mount point. It requires the variables DISKS
+and BRIDGES to be set, either as environment variables, or via a
+configuration file that it by default expects to find at
++/opt/sub/mysubhost/config+ That +config+ would be a textfile, or in
+fact a +bash+ source file, that should set the variables +DISKS+ and
++BRIDGES+ for running the subhost.
+
+====
+**The +DISKS+ variable** is an array declaring the disks in terms the
+partitions 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
+anything 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: