added man page for diskfile

[rrq/overlay-boot.git] / overlay-boot.8.adoc

diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc
index 172a228ac31277eeeab3fb6462d08f684aee383a..e97a8e4676cad9d8da15cc23f55f5469923e9ce0 100644 (file)
--- a/overlay-boot.8.adoc
+++ b/overlay-boot.8.adoc
@@ -24,7 +24,7 @@ an overlay of the main host filesystem to keep the specifics of a
 service distinctly separate from the main host while sharing files
 wherever sensible.
 
 service distinctly separate from the main host while sharing files
 wherever sensible.
 

-A subhost is started by identifyinf its configuration file on the
+A subhost is started by identifying its configuration file on the

 command line for *overlay-boot*. The configuration file is a plain
 text file with a small collection of "variables" that tell how the
 subhost is set up. When all is good, *overlay-boot* spawns a
 command line for *overlay-boot*. The configuration file is a plain
 text file with a small collection of "variables" that tell how the
 subhost is set up. When all is good, *overlay-boot* spawns a


@@ -34,7 +34,7 @@ odd computer.
 
 The subhost execution environment may be "entered" to perform
 adminstrative tasks with *overlay-go*, and it is later stopped with
 
 The subhost execution environment may be "entered" to perform
 adminstrative tasks with *overlay-go*, and it is later stopped with

-*overlay-stop*.
+*overlay-stop*. 

 
 OPTIONS
 -------
 
 OPTIONS
 -------


@@ -71,7 +71,7 @@ section on Networking below for more details.
 
 INIT::
 
 
 INIT::
 

-This variable is a command line to run, with envirnment variable
+This variable is a command line to run, with environment variable

 CONFIG set, for producing the initial commands to the running subhost,
 similar to the initrd phase of a computer bootup. The default value
 for this variable is +overlay-init+.
 CONFIG set, for producing the initial commands to the running subhost,
 similar to the initrd phase of a computer bootup. The default value
 for this variable is +overlay-init+.


@@ -100,17 +100,21 @@ as UPPER.
 
 *POSTMOUNT*::
 
 
 *POSTMOUNT*::
 

-This variable is a command line to run, with envirnment variable
+This variable is a command line to run, with environment variable

 CONFIG set, just after the setup of the subhost root filesystem and
 before the services are started. The default for this variable is
 CONFIG set, just after the setup of the subhost root filesystem and
 before the services are started. The default for this variable is

-+overlay-postmount+
++overlay-postmount+. Note that this command is executed within the
+mount namespace of the subhost, and still with the main host as root
+filesystem.

 
 *PREMOUNT*::
 
 
 *PREMOUNT*::
 

-This variable is a command line to run, with envirnment variable
+This variable is a command line to run, with environment variable

 CONFIG set, just before the setup of the subhost root filesystem and
 before the services are started. The default for this variable is
 CONFIG set, just before the setup of the subhost root filesystem and
 before the services are started. The default for this variable is

-+overlay-premount+
++overlay-premount+  Note that this command is executed within the
+mount namespace of the subhost, and still with the main host as root
+filesystem.

 
 *UPPER*::
 
 
 *UPPER*::
 


@@ -123,8 +127,8 @@ as an overlay mount. In that case WORK (below) must be defined as a
 directory outside of but on the same mount as UPPER.
 +
 If UPPER is the same as LOWER, then the subhost root filesystem is not
 directory outside of but on the same mount as UPPER.
 +
 If UPPER is the same as LOWER, then the subhost root filesystem is not

-setup as an overla. Rather it is set up as a bind mount, if UPPER is
-different from LIVE, or just as a pre-mounted LIVE filesystem.
+setup as an overlay. It Is rather set up either as a bind mount if UPPER is
+different from LIVE, or just taken as a pre-mounted LIVE filesystem.

 
 *WORK*::
 
 
 *WORK*::
 


@@ -151,16 +155,16 @@ defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use
 Networking
 ----------
 
 Networking
 ----------
 

-*overlay-boot* sets up a nework namespace named by the subhost NAME,
-and uses the CABLES variable to set up +veth+ virtual cables. The host
-end of such cables are named by NAME followed by a number from 0 and
-up while the subhost end are named by +eth+ followed by the same
-number.
+*overlay-boot* sets up a nework namespace named by the subhost
++$NAME+, and uses the +$CABLES+ variable to set up +veth+ virtual
+cables. The host end of such cables are named by +$NAME+ followed by a
+number from 0 and up while the subhost end are named by +eth+ followed
+by the same number.

 
 

-As mentioned above, CABLES consists of a space separated list of cable
-specifiers, each consisting of a bridge interface name and a with an
-equal sign ("=") between them. The equal sign is required while either
-or both of the bridge and MAC address may be left empty.
+As mentioned above, +$CABLES+ consists of a space separated list of
+cable specifiers, each consisting of a bridge interface name and a
+with an equal sign ("=") between them. The equal sign is required
+while either or both of the bridge and MAC address may be left empty.

 
 The bridge interface name, if given, will be given control of the host
 end cable interface. A cable specification with empty bridge name part
 
 The bridge interface name, if given, will be given control of the host
 end cable interface. A cable specification with empty bridge name part


@@ -177,9 +181,11 @@ EXAMPLES
 
 ./opt/subhost/mta/mta.conf
 ****
 
 ./opt/subhost/mta/mta.conf
 ****

+----

 BASE=.
 CABLES= =
 BASE=.
 CABLES= =

-START= rsyslog newtorking ssh postfix
+START= rsyslog networking ssh saslauthd postfix dovecot
+----

 ****
 
 The above example assumes a directory +/opt/subhost/mta+ that contains
 ****
 
 The above example assumes a directory +/opt/subhost/mta+ that contains


@@ -192,5 +198,26 @@ and the main host end is named +mta0+, and upon start, an +ifup mta0+
 is attempted at the host end while the subhost end is handled via its
 neworking service.
 
 is attempted at the host end while the subhost end is handled via its
 neworking service.
 

+./opt/subhost/tiny/tiny.conf
+****
+----
+BASE=.
+CABLES= =
+START= none
+LOWER=!mkdir -p base work root live ; echo base
+WORK= work
+UPPER= root
+LIVE= live
+----
+****
+
+The +tiny+ subhost would be for overlaying a separate +debootstrap+
+root filesystem, without any services (since +START+ is empty). This
+gets started with a +dummy_service+ to hold the overlay for access via
++overlay-go+. The +dummy_service+ sets up and listens on a pipe at
++/run/dummy_service+, and exits when anything is written to that.

 
 

+SEE ALSO
+--------

 
 

+*overlay-stop*, *overlay-go*