X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=overlay-boot.8.adoc;h=dee7b10040cb2d1c032c2001241f54935fc06f49;hb=HEAD;hp=974759eefe157a48f3111924992156cbc23b36ad;hpb=a55dec2999e4c8b2ec82671d2f90f065c298e241;p=rrq%2Foverlay-boot.git diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc index 974759e..dee7b10 100644 --- 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. -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*. @@ -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 -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:: @@ -185,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 @@ -197,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. +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 -------- -=== /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 +238,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 --------