README.adoc

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