1 = The overlay-boot Project
2 :author: Ralph Ronnquist
3 :revdate: Sun, 30 Apr 2023 23:46:31 +1000
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.
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
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
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
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).
34 == A usage example (minimal)
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
44 Refer to the overlay-boot manpage for all the configuration options.
46 . The minimal overlay subhost setup
49 # mkdir /ex1 /ex1/work /ex1/root /ex1/live
50 # echo BASE=. > /ex1/ex1.conf
54 The minimal overlay subhost may then be started with
57 # overlay-boot /ex1/ex1.conf
61 and it may be stopped with:
64 # overlay-stop /ex1/ex1.conf
68 The subhost environment may be "entered" with
75 == Another usage example (MTA)
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
81 .Initial setup for /opt/mta
84 $ sudo mkdir -p /opt/mta/{live,root,work}
86 # sudo tee /opt/mta/mta.conf <EOF
88 CABLES= =06:20:03:4e:a6:f2
89 START= hostname.sh rsyslog networking ssh saslauthd postfix dovecot
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.
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.
104 .Initial networking setup (ifupdown, and e.g. MTANET=192.168.0)
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
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
114 # cat > /etc/network/interfaces.d/mta.conf <EOF
115 iface mta0 inet static
119 # cat > /opt/mta/root/etc/network/interfaces <EOF
121 iface lo inet loopback
122 iface eth0 inet static
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+
133 * the firewall rules direct incoming port 25 traffic onwards to the
134 subhost, and provides NAT for its outbound traffic
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.
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.
146 .Starting the subhost
149 # overlay-boot /opt/mta/mta.conf
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+.
159 It is also possible to enter with +overlay-go mta+ for administrative
162 .Stopping the subhost
165 # overlay-stop /opt/mta/mta.conf