X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=README.adoc;h=99805d5cb02f51bbe4b1cd2f115361390e714099;hb=HEAD;hp=380911fcd78f01481a66695af2482bd7d845eb00;hpb=63a3b5512db926a35bcce42999d4fc8438ff5a4f;p=rrq%2Foverlay-boot.git

diff --git a/README.adoc b/README.adoc
index 380911f..99805d5 100644
--- a/README.adoc
+++ b/README.adoc
@@ -1,8 +1,6 @@
-The overlay-boot Project
-========================
-
-Brief
------
+= 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
@@ -23,8 +21,8 @@ framework.
    they were alone.
 
  * *overlay-boot* includes support for overlay root filesystem with
-   persistent idividual overlays for the subhosts. This is scripted to
-   be open for any storage solutions, including the sharing of file
+   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.
 
@@ -33,11 +31,10 @@ framework.
    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 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
+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
@@ -75,3 +72,96 @@ The subhost environment may be "entered" with
 ----
 ====
 
+== Another usage example (MTA)
+
+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.
+
+.Initial setup for /opt/mta
+====
+----
+$ sudo mkdir -p /opt/mta/{live,root,work}
+
+# 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
+----
+====
+
+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
+----
+====