From: Ralph Ronnquist Date: Mon, 5 Dec 2022 22:21:33 +0000 (+1100) Subject: editorial improvements X-Git-Tag: v0.1.10 X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=ab7139047b337f3e893e55707764b59c6f97a78f;p=rrq%2Foverlay-boot.git editorial improvements --- diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc index 974759e..c7c3508 100644 --- a/overlay-boot.8.adoc +++ b/overlay-boot.8.adoc @@ -17,24 +17,23 @@ DESCRIPTION ----------- *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 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. + +The 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. The subhost may also -be set up with users and an _sshd_ service as needed. +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. Subhost execution is stopped with *overlay-stop*. @@ -200,24 +199,22 @@ possibly a different one upon each start. EXAMPLES -------- -=== /opt/subhost/mta/mta.conf -**** +=== Smallest possible ---- +# mkdir -p /opt/subhost/copy/{root,work,live} +# cat << EOF > /opt/subhost/copy/copy.conf 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 **** @@ -225,19 +222,35 @@ neworking service. 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+ -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. +=== /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 --------