From 373eeaa3aaec3af8eaae67ad1ac3f5fdf323ac37 Mon Sep 17 00:00:00 2001
From: Ralph Ronnquist <ralph.ronnquist@gmail.com>
Date: Sat, 2 Apr 2022 13:56:08 +1100
Subject: [PATCH] added a larger example

---
 README.adoc | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 96 insertions(+), 2 deletions(-)

diff --git a/README.adoc b/README.adoc
index 380911f..22edb21 100644
--- a/README.adoc
+++ b/README.adoc
@@ -23,8 +23,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.
 
@@ -75,3 +75,97 @@ 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
+----
+====
-- 
2.39.2