Revised pretend-boot description

[rrq/subhost.git] / README.adoc

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


@@ -51,7 +130,7 @@ followed be the same number.
 Examples
 --------
 
 Examples
 --------
 

-. start a subhost named +future+
+.start a subhost named +future+

 ----
 # ./control start future
 ----
 ----
 # ./control start future
 ----


@@ -65,7 +144,7 @@ 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.
 
 state" for the subhost, which may be restarted (without stopping)
 using the start command again.
 

-. stop a subhost named +future+
+.stop a subhost named +future+

 ----
 # ./control stop future
 ----
 ----
 # ./control stop future
 ----