README.adoc

   1 = The overlay-boot Project
   2 :author: Ralph Ronnquist
   3 :revdate: Sun, 30 Apr 2023 23:46:31 +1000
   4
   5 The *overlay-boot* project implements a "minimalist approach" for
   6 dividing a single host into "subhosts" for administratively separated
   7 services. The project provides core support for "subhosts" that are
   8 independent operating system environments but using overlay root
   9 filesystems, and with their services executed with separated
  10 namespaces by a common kernel.
  11
  12 The concept is similar to "containers" and "virtual machines", but
  13 with much lighter touch that is aimed at light-weight technical
  14 separation of service environments within a common adminstration
  15 framework.
  16
  17  * *overlay-boot* implements a simple and efficient networking
  18    principle where networking is achived via network namspaces and
  19    virtual cabling. There is an overarching adminstrative control at
  20    the host end while the subhosts are adminstrated separately as if
  21    they were alone.
  22
  23  * *overlay-boot* includes support for overlay root filesystem with
  24    persistent individual overlays for the subhosts. This is scripted
  25    to be open for any storage solutions, including the sharing of file
  26    system subtrees, disk and partition image files and logical volume
  27    set ups.
  28
  29  * *overlay-boot* includes a scripted service oriented "subhost init"
  30    procedure that is open for all kinds of service management,
  31    including the trivial case of "no services" (as is necessary for
  32    installing and configuring the service or services of a subhost).
  33
  34 == A usage example (minimal)
  35
  36 A subhost is techincally defined as a directory that contains three
  37 mount points "work", "root" and "live", and a configuration file with
  38 at least a definition of the BASE variable with the pathname of the
  39 subhost directory. For convenience, the BASE pathname is understood as
  40 relative to its own directory, and thus, if the configuration resides
  41 in the subhost directory a simple "BASE=." assignment is a sufficient
  42 configuration.
  43
  44 Refer to the overlay-boot manpage for all the configuration options.
  45
  46 . The minimal overlay subhost setup
  47 ====
  48 ----
  49 # mkdir /ex1 /ex1/work /ex1/root /ex1/live
  50 # echo BASE=. > /ex1/ex1.conf
  51 ----
  52 ====
  53
  54 The minimal overlay subhost may then be started with
  55 ====
  56 ----
  57 # overlay-boot /ex1/ex1.conf
  58 ----
  59 ====
  60
  61 and it may be stopped with:
  62 ====
  63 ----
  64 # overlay-stop /ex1/ex1.conf
  65 ----
  66 ====
  67
  68 The subhost environment may be "entered" with
  69 ====
  70 ----
  71 # overlay-go ex1
  72 ----
  73 ====
  74
  75 == Another usage example (MTA)
  76
  77 This is an example setup at +/opt/mta+ of a larger overlay subhost
  78 for an MTA as primary service and with some additional useful
  79 companion services.
  80
  81 .Initial setup for /opt/mta
  82 ====
  83 ----
  84 $ sudo mkdir -p /opt/mta/{live,root,work}
  85
  86 # sudo tee /opt/mta/mta.conf <EOF
  87 BASE=.
  88 CABLES= =06:20:03:4e:a6:f2
  89 START= hostname.sh rsyslog networking ssh saslauthd postfix dovecot
  90 EOF
  91 ----
  92 ====
  93
  94 Note that this initial setup includes a MAC address for the subhost
  95 end of the (single) virtual cable, and an enumeration of (sysv)
  96 services to start "automatically" within the subhost. Of course those
  97 services might not be available on the first start, and then the
  98 initial admin task is to install them inside the subhost.
  99
 100 This example includes networking setup which is necessary for the
 101 subhost services. That setup includes both host end configurations and
 102 subhost end configurations.
 103
 104 .Initial networking setup (ifupdown, and e.g. MTANET=192.168.0)
 105 ====
 106 ----
 107 # echo "source interfaces.d/mta.conf" >> /etc/network/interfaces
 108 # echo "$MTANET.2 mta" >> /etc/hosts
 109 # echo "mta" > /opt/mta/root/etc/hostname
 110
 111 # iptables -t nat -I PREROUTING -p tcp --dport 25 -j DNAT --to-destination $MTANET.2
 112 # iptables -t nat -I POSTROUTING -s $MTANET.2 -j MASQUERADE
 113
 114 # cat > /etc/network/interfaces.d/mta.conf <EOF
 115 iface mta0 inet static
 116     address $MTANET.1/24
 117 EOF
 118
 119 # cat > /opt/mta/root/etc/network/interfaces <EOF
 120 auto lo eth0
 121 iface lo inet loopback
 122 iface eth0 inet static
 123     address $MTANET.2/24
 124     gateway $MTANET.1
 125 EOF
 126 ----
 127 ====
 128
 129  * the host end cabling configuration is done in a separate file
 130  (+/etc/network/interfaces.d/mta.conf+) that is explicitly sourced in
 131  +/etc/network/interfaces+
 132
 133  * the  firewall rules direct incoming port 25 traffic onwards to the
 134  subhost, and provides NAT for its outbound traffic
 135
 136  * host names are not necessarily used, but it may be convenient. The
 137  subhost has a separate UTS namespace and there might be an initial
 138  confusion about hostname.
 139
 140  * the subhost cable end configuration is done directly into a "fresh"
 141  subhost +root/etc/network/interfaces+. Note that +overlay-boot+ will
 142  itself prepare a minimal fresh +root/etc/network/interfaces+ if there
 143  is none; that is done so as to avoid "accidental" use of the main
 144  host configuration in the subhost.
 145
 146 .Starting the subhost
 147 ====
 148 ----
 149 # overlay-boot /opt/mta/mta.conf
 150 ----
 151 ====
 152
 153 The subhost will start +ssh+ service which may allow user to enter the
 154 subhost via +ssh+. Since the subhost root filesystem is an overlay, it
 155 will in particular "inherit" the +/home+ tree as well as most of
 156 +/etc+, and thus the main host user would be able to enter the subhost
 157 via +ssh+ in the same way as they enter the main host via +ssh+.
 158
 159 It is also possible to enter with +overlay-go mta+ for administrative
 160 purposes.
 161
 162 .Stopping the subhost
 163 ====
 164 ----
 165 # overlay-stop /opt/mta/mta.conf
 166 ----
 167 ====