-overlay-boot(8)
-===============
-:doctype: manpage
-:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
-:COLON: :
-:EQUALS: =
-
-NAME
-----
-overlay-boot - Start a subhost with overlay root filesystem.
-
-SYNOPSIS
---------
-*overlay-boot* _conf_
-
-DESCRIPTION
------------
-*overlay-boot* is the main script on a small collection of
-administration scripts for containerizing services with minimal ado.
-The script starts a "subhost" with a dedicated network namespace, and
-the mount and pid namespaces separated from the main host by means of
-+unshare+. A subhost root file system may in particular be set up as
-an overlay of the main host filesystem to keep the specifics of a
-service distinctly separate from the main host while sharing files
-wherever sensible.
-
-A subhost is started by identifyinf its configuration file on the
-command line for *overlay-boot*. The configuration file is a plain
-text file with a small collection of "variables" that tell how the
-subhost is set up. When all is good, *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.
-
-The subhost execution environment may be "entered" to perform
-adminstrative tasks with *overlay-go*, and it is later stopped with
-*overlay-stop*.
-
-OPTIONS
--------
-
-An overlay-boot subhost is defined in the configuration file, which is
-a plain text file with a number of variable assignments. Each
-assignment is written with the varable name flush left and immediately
-followed by an equal sign, The rest of that line (ignoring leading and
-trailing spaces) is its value, or if that value startes with an
-exclamation mark, then the line is a command to run so as to generate
-the value. See examples below.
-
-*NAME*::
-
-This variable declares a short name for the subhost, and should be no
-more than 12 printable ascii characters. The base name of the
-configuration file is used by default. I.e., a configuration file
-named +foo.conf+ by default names its subhost +foo+ unless there is a
-+NAME+ variable says differently.
-
-*BASE*::
-
-This variable declares a pathname for a directory that is considered
-to be a "base" for the subhost setup. This is the only required
-variable.
-
-*CABLES*::
-
-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 optinally a MAC address to the right. See the
-section on Networking below for more details.
-
-INIT::
-
-This variable is a command line to run, with envirnment variable
-CONFIG set, for producing the initial commands to the running subhost,
-similar to the initrd phase of a computer bootup. The default value
-for this variable is +overlay-init+.
-
-*LIVE*::
-
-This variable nominates the mount point for the running subhost's root
-file system. It defaults to +$BASE/live+ The nominated directory must
-exist, and depending on the directory pathnames in the +UPPER+ and
-+LOWER+ variables, the subhost root filesystem is either of a
-pre-mounted directory, bind mounted or overlay mounted directory. See
-the details of this with the UPPER variable below.
-
-*LOG*::
-
-This variable nominates the logfile to use by +overlay-boot+ when
-running the subhost. The default is +/tmp/overlay-$NAME.log+.
-
-*LOWER*::
-
-This variable nominates the "lower" filesystem of an overlay mount.
-This will be accessed read-only, an it is intended to be the operating
-system root file system. The default is +/+, i.e. the main host root
-filesystem. When overlay is not desired, then LOWER should be the smae
-as UPPER.
-
-*POSTMOUNT*::
-
-This variable is a command line to run, with envirnment variable
-CONFIG set, just after the setup of the subhost root filesystem and
-before the services are started. The default for this variable is
-+overlay-postmount+
-
-*PREMOUNT*::
-
-This variable is a command line to run, with envirnment variable
-CONFIG set, just before the setup of the subhost root filesystem and
-before the services are started. The default for this variable is
-+overlay-premount+
-
-*UPPER*::
-
-This variable nominates the "upper" filesystem for an overlay mount.
-This will be accessed read-write and it constitutes the "private"
-files of the subhost.
-+
-If UPPER is different from LOWER, then the root file system is set up
-as an overlay mount. In that case WORK (below) must be defined as a
-directory outside of but on the same mount as UPPER.
-+
-If UPPER is the same as LOWER, then the subhost root filesystem is not
-setup as an overla. Rather it is set up as a bind mount, if UPPER is
-different from LIVE, or just as a pre-mounted LIVE filesystem.
-
-*WORK*::
-
-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.
+= The overlay-boot Project
+:author: Ralph Ronnquist
+:revdate: Sun, 30 Apr 2023 23:46:31 +1000
+
+The *overlay-boot* project implements a "minimalist approach" for
+dividing a single host into "subhosts" for administratively separated
+services. The project provides core support for "subhosts" that are
+independent operating system environments but using overlay root
+filesystems, and with their services executed with separated
+namespaces by a common kernel.
+
+The concept is similar to "containers" and "virtual machines", but
+with much lighter touch that is aimed at light-weight technical
+separation of service environments within a common adminstration
+framework.
+
+ * *overlay-boot* implements a simple and efficient networking
+ principle where networking is achived via network namspaces and
+ virtual cabling. There is an overarching adminstrative control at
+ the host end while the subhosts are adminstrated separately as if
+ they were alone.
+
+ * *overlay-boot* includes support for overlay root filesystem with
+ persistent individual overlays for the subhosts. This is scripted
+ to be open for any storage solutions, including the sharing of file
+ system subtrees, disk and partition image files and logical volume
+ set ups.
+
+ * *overlay-boot* includes a scripted service oriented "subhost init"
+ procedure that is open for all kinds of service management,
+ including the trivial case of "no services" (as is necessary for
+ installing and configuring the service or services of a subhost).
+
+== A usage example (minimal)
+
+A subhost is techincally defined as a directory that contains three
+mount points "work", "root" and "live", and a configuration file with
+at least a definition of the BASE variable with the pathname of the
+subhost directory. For convenience, the BASE pathname is understood as
+relative to its own directory, and thus, if the configuration resides
+in the subhost directory a simple "BASE=." assignment is a sufficient
+configuration.
+
+Refer to the overlay-boot manpage for all the configuration options.
+
+. The minimal overlay subhost setup
+====
+----
+# mkdir /ex1 /ex1/work /ex1/root /ex1/live
+# echo BASE=. > /ex1/ex1.conf
+----
+====
-*START*::
-
-This variable tells which services should be started on the
-overlay-boot startup. The default value is +networking ssh+.
-+
-Note that if no services are started, then +overlay-init+ starts a
-+dummy_service+ so as to keep +/.reaper+ from running out of child
-processes, as it otherwise will exit and thereby terminate
-+overlay-boot+.
-
-*RAM_SIZE*::
+The minimal overlay subhost may then be started with
+====
+----
+# overlay-boot /ex1/ex1.conf
+----
+====
-This variable may be used to configure the +/run+ directory which by
-defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use
-+none+ to avoid that mount, and otherwise the desired +tmpfs+ size.
+and it may be stopped with:
+====
+----
+# overlay-stop /ex1/ex1.conf
+----
+====
-Networking
-----------
+The subhost environment may be "entered" with
+====
+----
+# overlay-go ex1
+----
+====
-*overlay-boot* sets up a nework namespace named by the subhost NAME,
-and uses the CABLES variable to set up +veth+ virtual cables. The host
-end of such cables are named by NAME followed by a number from 0 and
-up while the subhost end are named by +eth+ followed by the same
-number.
+== Another usage example (MTA)
-As mentioned above, CABLES consists of a space separated list of cable
-specifiers, each consisting of a bridge interface name and a with an
-equal sign ("=") between them. The equal sign is required while either
-or both of the bridge and MAC address may be left empty.
-
-The bridge interface name, if given, will be given control of the host
-end cable interface. A cable specification with empty bridge name part
-results in that the host end is brought up at link level and then
-+ifup $IF+ is attempted.
+This is an example setup at +/opt/mta+ of a larger overlay subhost
+for an MTA as primary service and with some additional useful
+companion services.
-The MAC address, if given, is used for the subhost end cable
-interface. A cable specification with empty MAC address part results
-in that the interface get its MAC address from the kernel, possibly a
-different one upon each start.
-
-EXAMPLES
---------
+.Initial setup for /opt/mta
+====
+----
+$ sudo mkdir -p /opt/mta/{live,root,work}
-./opt/subhost/mta/mta.conf
-****
+# sudo tee /opt/mta/mta.conf <EOF
BASE=.
-CABLES= =
-START= rsyslog newtorking ssh postfix
-****
+CABLES= =06:20:03:4e:a6:f2
+START= hostname.sh 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.
+Note that this initial setup includes a MAC address for the subhost
+end of the (single) virtual cable, and an enumeration of (sysv)
+services to start "automatically" within the subhost. Of course those
+services might not be available on the first start, and then the
+initial admin task is to install them inside the subhost.
+This example includes networking setup which is necessary for the
+subhost services. That setup includes both host end configurations and
+subhost end configurations.
+.Initial networking setup (ifupdown, and e.g. MTANET=192.168.0)
+====
+----
+# echo "source interfaces.d/mta.conf" >> /etc/network/interfaces
+# echo "$MTANET.2 mta" >> /etc/hosts
+# echo "mta" > /opt/mta/root/etc/hostname
+
+# iptables -t nat -I PREROUTING -p tcp --dport 25 -j DNAT --to-destination $MTANET.2
+# iptables -t nat -I POSTROUTING -s $MTANET.2 -j MASQUERADE
+
+# cat > /etc/network/interfaces.d/mta.conf <EOF
+iface mta0 inet static
+ address $MTANET.1/24
+EOF
+
+# cat > /opt/mta/root/etc/network/interfaces <EOF
+auto lo eth0
+iface lo inet loopback
+iface eth0 inet static
+ address $MTANET.2/24
+ gateway $MTANET.1
+EOF
+----
+====
+
+ * the host end cabling configuration is done in a separate file
+ (+/etc/network/interfaces.d/mta.conf+) that is explicitly sourced in
+ +/etc/network/interfaces+
+
+ * the firewall rules direct incoming port 25 traffic onwards to the
+ subhost, and provides NAT for its outbound traffic
+
+ * host names are not necessarily used, but it may be convenient. The
+ subhost has a separate UTS namespace and there might be an initial
+ confusion about hostname.
+
+ * the subhost cable end configuration is done directly into a "fresh"
+ subhost +root/etc/network/interfaces+. Note that +overlay-boot+ will
+ itself prepare a minimal fresh +root/etc/network/interfaces+ if there
+ is none; that is done so as to avoid "accidental" use of the main
+ host configuration in the subhost.
+
+.Starting the subhost
+====
+----
+# overlay-boot /opt/mta/mta.conf
+----
+====
+The subhost will start +ssh+ service which may allow user to enter the
+subhost via +ssh+. Since the subhost root filesystem is an overlay, it
+will in particular "inherit" the +/home+ tree as well as most of
++/etc+, and thus the main host user would be able to enter the subhost
+via +ssh+ in the same way as they enter the main host via +ssh+.
+
+It is also possible to enter with +overlay-go mta+ for administrative
+purposes.
+
+.Stopping the subhost
+====
+----
+# overlay-stop /opt/mta/mta.conf
+----
+====
projects / rrq / overlay-boot.git / blobdiff