X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=overlay-boot.8.adoc;h=dee7b10040cb2d1c032c2001241f54935fc06f49;hb=HEAD;hp=c7c35084ff5931998e1c37321eb9bf856568ed0d;hpb=ab7139047b337f3e893e55707764b59c6f97a78f;p=rrq%2Foverlay-boot.git

diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc
index c7c3508..dee7b10 100644
--- 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
-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.
 
-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*.
 
@@ -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
-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::
 
@@ -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
-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
@@ -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.
 
+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
 --------