README.adoc

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