X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=README.adoc;h=99805d5cb02f51bbe4b1cd2f115361390e714099;hb=58dfafb85fc624cb93abad5bd5297a1e5194d5e3;hp=c4cb404afda2f4fb6a4fcd0b41630c53a09a1484;hpb=1962381a074900c46e81c122049bd4ce64cf4e59;p=rrq%2Foverlay-boot.git diff --git a/README.adoc b/README.adoc index c4cb404..99805d5 100644 --- a/README.adoc +++ b/README.adoc @@ -1,159 +1,167 @@ -overlay-boot(8) -=============== -:doctype: manpage -:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"} -:COLON: : -:EQUALS: = - -NAME += The overlay-boot Project +:author: Ralph Ronnquist +:revdate: Sun, 30 Apr 2023 23:46:31 +1000 + +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 +independent operating system environments but using overlay root +filesystems, and with their services executed with separated +namespaces by a common kernel. + +The concept is similar to "containers" and "virtual machines", but +with much lighter touch that is aimed at light-weight technical +separation of service environments within a common adminstration +framework. + + * *overlay-boot* implements a simple and efficient networking + principle where networking is achived via network namspaces and + virtual cabling. There is an overarching adminstrative control at + the host end while the subhosts are adminstrated separately as if + they were alone. + + * *overlay-boot* includes support for overlay root filesystem with + 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. + + * *overlay-boot* includes a scripted service oriented "subhost init" + procedure that is open for all kinds of service management, + including the trivial case of "no services" (as is necessary for + installing and configuring the service or services of a subhost). + +== A usage example (minimal) + +A subhost is techincally defined as a directory that contains three +mount points "work", "root" and "live", and a configuration file with +at least a definition of the BASE variable with the pathname of the +subhost directory. For convenience, the BASE pathname is understood as +relative to its own directory, and thus, if the configuration resides +in the subhost directory a simple "BASE=." assignment is a sufficient +configuration. + +Refer to the overlay-boot manpage for all the configuration options. + +. The minimal overlay subhost setup +==== ---- -overlay-boot - Start a subhost with overlay root filesystem. - -SYNOPSIS --------- -*overlay-boot _conf_ - -DESCRIPTION ------------ -*overlay-boot* attempts to run a "subhost" with an overlay root -filesystem. The subhost is defined in a configuration file named on -the command line. When all is good, *overlay-boot* spawns a subprocess -that invokes a command shell within an chroot into "unshared" overlay -root filesystem, to perform service initialisations before ending up -in an indefinitely running "reaper" process. The overlay subhost is -essentially like a light container or virtual virtual machine for -running services in a relatively contained way without too much of -cross-wise interactions between them. - -OPTIONS -------- - -An overlay-boot subhost is defined in the configuration file, which is -a plain text file with a number of variable assignments. - -*NAME*:: - -This variable declares the short name for the subhost, and should be -no more than 12 printable ascii characters. The name of the -configuration file is used by default. - -*BASE*:: - -This variable declares a pathname for a directory that is considered -to be a "base" for the subhost setup. This is the only required -variable. - -*CABLES*:: - -This variable declares the networking setup to use for the subhost -through a space separated list of "virtual cable specifiers", each -consisting of a (possibly empty) bridge interface name and a (possibly -empty) MAC address with a (required) equal sign ("=") between them. - -See the section on Networking below for more details. - -*LIVE*:: - -This variable nominates the mount point for the overlay mount, and it -defaults to +$BASE/live+ (which also must exist). - -If LIVE and LOWER (below) are the same then this is assumed to be a -pre-mounted root filesystem for the later chroot without any overlay -mount being attempted. - -*LOG*:: - -This variable nominates the log file to use by +overlay-boot+. The -default is +/tmp/overlay-$NAME.log+. - -*LOWER*:: - -This variable nominates the "lower" filesystem of the overlay. This -will be accessed read-only, an it is intended to be the operating -system root file system. The default is +/+, i.e. the main host root -filesystem. - -*UPPER*:: - -This variable nominates the "upper" filesystem for the overlay. This -will be accessed read-write and constitutes the "private" files of the -subhost. - -If UPPER nominates an executable file raher than directory (i.e. -program or script), then that will be run before overlay mounting with -the environment variable ACTION set to "setup". The script must then -print the pathname of the actual "upper" directory when successfully -set up. Further upon termination of the subhost, that UPPER script -will be run with ACTION set to "teardown". - -*WORK*:: - -This variable nominates the "work" directory for the overlay mount. It -has to be a writable directory on the same mount device as the UPPER -directory. +# mkdir /ex1 /ex1/work /ex1/root /ex1/live +# echo BASE=. > /ex1/ex1.conf +---- +==== -*START*:: +The minimal overlay subhost may then be started with +==== +---- +# overlay-boot /ex1/ex1.conf +---- +==== -This variable tells which services should be started on the -overlay-boot startup. They get started with +service $srv start+ -before the startup ends by running +/.reaper+ (which is automatically -installed by +overlay-boot+). The default START includes +networking+ -and +ssh+. +and it may be stopped with: +==== +---- +# overlay-stop /ex1/ex1.conf +---- +==== -Note that if no services are started, then a +dummy_service+ gets -started so as to keep keep +/.reaper+ from running out of child -processes, as it otherwise will exit and thereby terminate -+overlay-boot+. +The subhost environment may be "entered" with +==== +---- +# overlay-go ex1 +---- +==== -That +dummy_service+ may be killed by a signal, or by writing to the -+/run/dummy_service+ pipe. +== Another usage example (MTA) -*RAM_SIZE*:: +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. -This variable may be used to configure the +/run+ directory which by -defult gets mounted as a +tmpfs+ of 50M. Use +none+ to avoid that -mount, and otherwise the desired tmpfs+ size. +.Initial setup for /opt/mta +==== +---- +$ sudo mkdir -p /opt/mta/{live,root,work} -Networking ----------- +# sudo tee /opt/mta/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 /opt/mta/root/etc/network/interfaces