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

diff --git a/README.adoc b/README.adoc
index 380911f..f5d0643 100644
--- a/README.adoc
+++ b/README.adoc
@@ -1,9 +1,6 @@
 The overlay-boot Project
 ========================
 
-Brief
------
-
 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
@@ -23,8 +20,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 +72,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
+----
+====