-overlay-boot(8)
-===============
-:doctype: manpage
-:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
-:COLON: :
-:EQUALS: =
-
-NAME
+= 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
+====
----
-overlay-boot - Start a subhost with overlay root filesystem.
-
-SYNOPSIS
---------
-*overlay-boot _conf_
-
-DESCRIPTION
------------
-*overlay-boot* attempts to run a "subhost" with an overlay root
-filesystem. The subhost is defined in a configuration file named on
-the command line. When all is good, *overlay-boot* spawns a subprocess
-that invokes a command shell within an chroot into "unshared" overlay
-root filesystem, to perform service initialisations before ending up
-in an indefinitely running "reaper" process. The overlay subhost is
-essentially like a light container or virtual virtual machine for
-running services in a relatively contained way without too much of
-cross-wise interactions between them.
-
-OPTIONS
--------
-
-An overlay-boot subhost is defined in the configuration file, which is
-a plain text file with a number of variable assignments.
-
-*NAME*::
-
-This variable declares the short name for the subhost, and should be
-no more than 12 printable ascii characters. The name of the
-configuration file is used by default.
-
-*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 networking setup to use for the subhost
-through a space separated list of "virtual cable specifiers", each
-consisting of a (possibly empty) bridge interface name and a (possibly
-empty) MAC address with a (required) equal sign ("=") between them.
-
-See the section on Networking below for more details.
-
-*LIVE*::
-
-This variable nominates the mount point for the overlay mount, and it
-defaults to +$BASE/live+ (which also must exist).
-
-If LIVE and LOWER (below) are the same then this is assumed to be a
-pre-mounted root filesystem for the later chroot without any overlay
-mount being attempted.
-
-*LOG*::
-
-This variable nominates the log file to use by +overlay-boot+. The
-default is +/tmp/overlay-$NAME.log+.
-
-*LOWER*::
-
-This variable nominates the "lower" filesystem of the overlay. 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.
-
-*UPPER*::
-
-This variable nominates the "upper" filesystem for the overlay. This
-will be accessed read-write and constitutes the "private" files of the
-subhost.
-
-If UPPER nominates an executable file raher than directory (i.e.
-program or script), then that will be run before overlay mounting with
-the environment variable ACTION set to "setup". The script must then
-print the pathname of the actual "upper" directory when successfully
-set up. Further upon termination of the subhost, that UPPER script
-will be run with ACTION set to "teardown".
-
-*WORK*::
-
-This variable nominates the "work" directory for the overlay mount. It
-has to be a writable directory on the same mount device as the UPPER
-directory.
+# mkdir /ex1 /ex1/work /ex1/root /ex1/live
+# echo BASE=. > /ex1/ex1.conf
+----
+====
-*START*::
+The minimal overlay subhost may then be started with
+====
+----
+# overlay-boot /ex1/ex1.conf
+----
+====
-This variable tells which services should be started on the
-overlay-boot startup. They get started with +service $srv start+
-before the startup ends by running +/.reaper+ (which is automatically
-installed by +overlay-boot+). The default START includes +networking+
-and +ssh+.
+and it may be stopped with:
+====
+----
+# overlay-stop /ex1/ex1.conf
+----
+====
-Note that if no services are started, then a +dummy_service+ gets
-started so as to keep keep +/.reaper+ from running out of child
-processes, as it otherwise will exit and thereby terminate
-+overlay-boot+.
+The subhost environment may be "entered" with
+====
+----
+# overlay-go ex1
+----
+====
-That +dummy_service+ may be killed by a signal, or by writing to the
-+/run/dummy_service+ pipe.
+== Another usage example (MTA)
-*RAM_SIZE*::
+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.
-This variable may be used to configure the +/run+ directory which by
-defult gets mounted as a +tmpfs+ of 50M. Use +none+ to avoid that
-mount, and otherwise the desired tmpfs+ size.
+.Initial setup for /opt/mta
+====
+----
+$ sudo mkdir -p /opt/mta/{live,root,work}
-Networking
-----------
+# sudo tee /opt/mta/mta.conf <EOF
+BASE=.
+CABLES= =06:20:03:4e:a6:f2
+START= hostname.sh rsyslog networking ssh saslauthd postfix dovecot
+EOF
+----
+====
-*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.
+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.
-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.
+This example includes networking setup which is necessary for the
+subhost services. That setup includes both host end configurations and
+subhost end configurations.
-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.
+.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 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.
+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+.
-boot-up
--------
+It is also possible to enter with +overlay-go mta+ for administrative
+purposes.
-*overlay-boot* includes a small boot-up section that consists of the
-following command sequence:
+.Stopping the subhost
+====
----
-mount -t proc proc /proc
-mount -t devpts devpts /dev/pts
-mount -t sysfs sysfs /sys
-if [ "$RAM_SIZE" != "none" ] && ! grep -q '/run tmpfs' /proc/mounts ; then
- mount -t tmpfs -osize=$RAM_SIZE,mode=755 tmpfs /run
-fi
-for srv in $START ; do
- service $srv start
-done
+# overlay-stop /opt/mta/mta.conf
----
-Thereafter the *overlay-boot* command shell (+/bin/sh+) morphs into
-running +/.reaper+ which simply waits and "reaps" child processes
-until it runs out of those and exist.
+====
projects / rrq / overlay-boot.git / blobdiff