Add bind-mount for /etc/adjtime to make subhost use host clock without ado

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

diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc
index c7c35084ff5931998e1c37321eb9bf856568ed0d..dee7b10040cb2d1c032c2001241f54935fc06f49 100644 (file)
--- a/overlay-boot.8.adoc
+++ b/overlay-boot.8.adoc
@@ -19,21 +19,24 @@ DESCRIPTION
 administration scripts for containerizing services with minimal ado.
 The script starts a "subhost" whose root filesystem is an overlay on
 the main host filesystem, and with separate mount, network and pid
 administration scripts for containerizing services with minimal ado.
 The script starts a "subhost" whose root filesystem is an overlay on
 the main host filesystem, and with separate mount, network and pid

-namespaces. In effect an administrative sandboxing that is
-prepopulated with a copy of the overlaid filesystem.
+namespaces. In effect the default use case is merely an administrative
+sandboxing that is pre-populated with a copy of the overlaid
+filesystem.

 
 

-The subhost is defined by means of a configuration file, __conf__,
+Each subhost is defined by means of a configuration file, __conf__,

 that is a simple text file with small collection of "variables"
 telling how the subhost is set up. *overlay-boot* spawns a subprocess
 that performs the boot-up of the "subhost" as an init script that ends
 with a pid 1 +reaper+ that simply "reaps" any terminated child
 processes.
 
 that is a simple text file with small collection of "variables"
 telling how the subhost is set up. *overlay-boot* spawns a subprocess
 that performs the boot-up of the "subhost" as an init script that ends
 with a pid 1 +reaper+ that simply "reaps" any terminated child
 processes.
 

-The administrator may "enter" the subhost execution environment to
-perform adminstrative tasks by means of *overlay-go*, which starts an
-interactive shell within the subhost namespaces. Usually this is only
-used initially for configuring the subhost's network and set up an
-_sshd_ service for subsequent access.
+An administrator may "enter" the subhost execution environment to
+perform adminstrative tasks by means of *overlay-go*, which uses
++chroot+ to start an interactive shell within the subhost namespaces.
+Such a shell however is not a child of the subhost +pid 1+ and it
+would normally only be used initially for configuring the subhost's
+network, and set up network based services, such as _sshd_, for
+subsequent access.

 
 Subhost execution is stopped with *overlay-stop*.
 
 
 Subhost execution is stopped with *overlay-stop*.
 


@@ -71,8 +74,8 @@ contains the configuration file and the three mount points "root",
 This variable declares the subhost networking in terms of its virtual
 cables. The value is a space separated list of "virtual cable
 specifiers", each consisting of an equal sign optionally with a bridge
 This variable declares the subhost networking in terms of its virtual
 cables. The value is a space separated list of "virtual cable
 specifiers", each consisting of an equal sign optionally with a bridge

-name to the left and optionally a MAC address to the right. See the
-section on Networking below for more details.
+name to the left and optionally a MAC address or VLAN tag to the
+right. See the section on Networking below for more details.

 
 INIT::
 
 
 INIT::
 


@@ -184,8 +187,8 @@ by the same number.
 
 As mentioned above, +CABLES+ is a space separated list of cable
 specifiers, each consisting of an optional bridge interface name, an
 
 As mentioned above, +CABLES+ is a space separated list of cable
 specifiers, each consisting of an optional bridge interface name, an

-optional MAC adddress and with a required equal sign ("=") between
-them.
+optional MAC adddress or VLAN tag and with a required equal sign ("=")
+between them.

 
 The bridge interface name, when given, will be given control of the
 host end cable interface. When the bridge interface name is omitted
 
 The bridge interface name, when given, will be given control of the
 host end cable interface. When the bridge interface name is omitted


@@ -196,6 +199,19 @@ The MAC address, if given, is used for the subhost end cable
 interface, which otherise gets its MAC address from the kernel,
 possibly a different one upon each start.
 
 interface, which otherise gets its MAC address from the kernel,
 possibly a different one upon each start.
 

+A VLAN tag has the format ".N" where N is a number between 1 and 4095.
+This modifies the cable function to set up a VLAN host interface on
+the prior host interface, and skip subhost side setup. E.g. if the
+prior host interface is +example1+ and the tag is +.302+ then the VLAN
+interface would be +example1.302+. The host side setup uses _ifup $IF_
+and thus, the host needs to have a supporting configuration entry in
++/etc/network/interfaces+ for the VLAN interface.
+
+Note that it may be a good practice to keep a local +interfaces+ file
+as sibling to the subhost configuration file on the host and use a
+_source_ statement to include this into the system networking
+configuration.
+

 EXAMPLES
 --------
 
 EXAMPLES
 --------