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 01ae70904f37c19e364352530171bba5ae26a4a5..dee7b10040cb2d1c032c2001241f54935fc06f49 100644 (file)
--- a/overlay-boot.8.adoc
+++ b/overlay-boot.8.adoc
@@ -17,24 +17,26 @@ DESCRIPTION
 -----------
 *overlay-boot* is the main script in a small collection of
 administration scripts for containerizing services with minimal ado.
 -----------
 *overlay-boot* is the main script in a small collection of
 administration scripts for containerizing services with minimal ado.

-It starts a "subhost" with a dedicated network namespace, and the
-mount and pid namespaces separated from the main host by means of
-_unshare_, and the subhost root file system may be set up as an
-overlay of the main host filesystem, for keeping the subhost services
-distinctly separate from the main host.
-
-A subhost is started by nominating its _configuration file_ on the
-command line for *overlay-boot*. This is a plain text file with a
-small collection of "variables" that tell how the subhost is set up.
-*overlay-boot* spawns a subprocess that invokes a command shell within
-an chroot into "unshared" subhost root filesystem, all similar to the
-bootup of any odd computer, and therafter the subhost "runs" in the
-way of a virtual machine or container environment.
-
-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. The subhost may also
-be set up with users and an _sshd_ service as needed.
+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 the default use case is merely an administrative
+sandboxing that is pre-populated with a copy of the overlaid
+filesystem.
+
+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.
+
+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*.
 


@@ -72,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::
 


@@ -166,6 +168,14 @@ This variable nominates the "work" directory for an overlay mount. It
 has to be a writable directory on the same mount device as the UPPER
 directory.
 
 has to be a writable directory on the same mount device as the UPPER
 directory.
 

+*SHARE*::
+
+This variable nominates a pathname under $LOWER to bind-mount onto the
+same pathname under $LIVE so as to share that directory tree into the
+overlay. The SHARE variable is a special configuration variable in
+that the value does not allow exclamation mark evaluation, and that it
+may occur many times for declaring multiple shared subdirectories.
+

 Networking
 ----------
 
 Networking
 ----------
 


@@ -177,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


@@ -189,27 +199,38 @@ 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
 --------
 

-=== /opt/subhost/mta/mta.conf
-****
+=== Smallest possible

 ----
 ----

+# mkdir -p /opt/subhost/copy/{root,work,live}
+# cat << EOF > /opt/subhost/copy/copy.conf

 BASE=.
 BASE=.

-CABLES= =
-START= rsyslog networking ssh saslauthd postfix dovecot
+EOF

 ----
 ----

-****

 
 

-The above example assumes a directory +/opt/subhost/mta+ that contains
-the configuration file +mta.conf+ and directories +root+, +work+ and
-+live+. *overlay-boot* will set up an overlay mount on +live+ with
-+root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of
-the main host filesystem. Further, the running subhost will feature a
-virtual cable to the main host, where the subhost end is named +eth0+
-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.
+
+This setup has a minimal configuration for a subhost that overlays the
+root filesystem but is without networking. The subhost must be entered
+with *overlay-go*, although the default start might have started sshd
+listening on a loopback interface in the subhost's network namespaces.
+
+Note that *overlay-go* runs a shell within the namespaces, but not as
+a child of the "subhost init" (aka +.reaper+).

 
 === /opt/subhost/tiny/tiny.conf
 ****
 
 === /opt/subhost/tiny/tiny.conf
 ****


@@ -217,19 +238,35 @@ neworking service.
 BASE=.
 CABLES= =
 START= none
 BASE=.
 CABLES= =
 START= none

-LOWER= !mkdir -p base work root live ; echo base
-WORK= work
-UPPER= root
-LIVE= live
+LOWER= base

 ----
 ****
 
 The +tiny+ subhost would be for overlaying a separate +debootstrap+
 ----
 ****
 
 The +tiny+ subhost would be for overlaying a separate +debootstrap+

-root filesystem, without any services (since +START+ is empty). This
+root filesystem, without any services (since +START+ is "none"). 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.
 
 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.
 

+=== /opt/subhost/mta/mta.conf
+****
+----
+BASE=.
+CABLES= =
+START= rsyslog networking ssh saslauthd postfix dovecot
+----
+****
+
+The above example assumes a directory +/opt/subhost/mta+ that contains
+the configuration file +mta.conf+ and directories +root+, +work+ and
++live+. *overlay-boot* will set up an overlay mount on +live+ with
++root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of
+the main host filesystem. Further, the running subhost will feature a
+virtual cable to the main host, where the subhost end is named +eth0+
+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.
+

 SEE ALSO
 --------
 
 SEE ALSO
 --------