From 63a3b5512db926a35bcce42999d4fc8438ff5a4f Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Fri, 1 Apr 2022 22:31:14 +1100 Subject: [PATCH] rewrite as overview --- README.adoc | 261 ++++++++++++++-------------------------------------- 1 file changed, 70 insertions(+), 191 deletions(-) diff --git a/README.adoc b/README.adoc index 9646ee2..380911f 100644 --- a/README.adoc +++ b/README.adoc @@ -1,198 +1,77 @@ -overlay-boot(8) -=============== -:doctype: manpage -:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"} -:COLON: : -:EQUALS: = - -NAME +The overlay-boot Project +======================== + +Brief +----- + +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 idividual 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* is the main script on a small collection of -administration scripts for containerizing services with minimal ado. -The script starts a "subhost" with a dedicated network namespace, and -the mount and pid namespaces separated from the main host by means of -+unshare+. A subhost root file system may in particular be set up as -an overlay of the main host filesystem to keep the specifics of a -service distinctly separate from the main host while sharing files -wherever sensible. - -A subhost is started by identifyinf its configuration file on the -command line for *overlay-boot*. The configuration file is a plain -text file with a small collection of "variables" that tell how the -subhost is set up. When all is good, *overlay-boot* spawns a -subprocess that invokes a command shell within an chroot into -"unshared" subhost root filesystem, all similar to the bootup of any -odd computer. - -The subhost execution environment may be "entered" to perform -adminstrative tasks with *overlay-go*, and it is later stopped with -*overlay-stop*. - -OPTIONS -------- - -An overlay-boot subhost is defined in the configuration file, which is -a plain text file with a number of variable assignments. Each -assignment is written with the varable name flush left and immediately -followed by an equal sign, The rest of that line (ignoring leading and -trailing spaces) is its value, or if that value startes with an -exclamation mark, then the line is a command to run so as to generate -the value. See examples below. - -*NAME*:: - -This variable declares a short name for the subhost, and should be no -more than 12 printable ascii characters. The base name of the -configuration file is used by default. I.e., a configuration file -named +foo.conf+ by default names its subhost +foo+ unless there is a -+NAME+ variable says differently. - -*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 subhost networking in terms of its virtual -cables. The value is a space separated list of "virtual cable -specifiers", each consisting of an equal sign optionally with a bridge -name to the left and optinally a MAC address to the right. See the -section on Networking below for more details. - -INIT:: - -This variable is a command line to run, with envirnment variable -CONFIG set, for producing the initial commands to the running subhost, -similar to the initrd phase of a computer bootup. The default value -for this variable is +overlay-init+. - -*LIVE*:: - -This variable nominates the mount point for the running subhost's root -file system. It defaults to +$BASE/live+ The nominated directory must -exist, and depending on the directory pathnames in the +UPPER+ and -+LOWER+ variables, the subhost root filesystem is either of a -pre-mounted directory, bind mounted or overlay mounted directory. See -the details of this with the UPPER variable below. - -*LOG*:: - -This variable nominates the logfile to use by +overlay-boot+ when -running the subhost. The default is +/tmp/overlay-$NAME.log+. - -*LOWER*:: - -This variable nominates the "lower" filesystem of an overlay mount. -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. When overlay is not desired, then LOWER should be the smae -as UPPER. - -*POSTMOUNT*:: - -This variable is a command line to run, with envirnment variable -CONFIG set, just after the setup of the subhost root filesystem and -before the services are started. The default for this variable is -+overlay-postmount+ - -*PREMOUNT*:: - -This variable is a command line to run, with envirnment variable -CONFIG set, just before the setup of the subhost root filesystem and -before the services are started. The default for this variable is -+overlay-premount+ - -*UPPER*:: - -This variable nominates the "upper" filesystem for an overlay mount. -This will be accessed read-write and it constitutes the "private" -files of the subhost. -+ -If UPPER is different from LOWER, then the root file system is set up -as an overlay mount. In that case WORK (below) must be defined as a -directory outside of but on the same mount as UPPER. -+ -If UPPER is the same as LOWER, then the subhost root filesystem is not -setup as an overla. Rather it is set up as a bind mount, if UPPER is -different from LIVE, or just as a pre-mounted LIVE filesystem. - -*WORK*:: - -This variable nominates the "work" directory for an overlay mount. It -has to be a writable directory on the same mount device as the UPPER -directory. - -*START*:: - -This variable tells which services should be started on the -overlay-boot startup. The default value is +networking ssh+. -+ -Note that if no services are started, then +overlay-init+ starts a -+dummy_service+ so as to keep +/.reaper+ from running out of child -processes, as it otherwise will exit and thereby terminate -+overlay-boot+. - -*RAM_SIZE*:: - -This variable may be used to configure the +/run+ directory which by -defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use -+none+ to avoid that mount, and otherwise the desired +tmpfs+ size. - -Networking ----------- - -*overlay-boot* sets up a nework namespace named by the subhost NAME, -and uses the CABLES variable to set up +veth+ virtual cables. The host -end of such cables are named by NAME followed by a number from 0 and -up while the subhost end are named by +eth+ followed by the same -number. - -As mentioned above, CABLES consists of a space separated list of cable -specifiers, each consisting of a bridge interface name and a with an -equal sign ("=") between them. The equal sign is required while either -or both of the bridge and MAC address may be left empty. - -The bridge interface name, if given, will be given control of the host -end cable interface. A cable specification with empty bridge name part -results in that the host end is brought up at link level and then -+ifup $IF+ is attempted. - -The MAC address, if given, is used for the subhost end cable -interface. A cable specification with empty MAC address part results -in that the interface get its MAC address from the kernel, possibly a -different one upon each start. - -EXAMPLES --------- +# mkdir /ex1 /ex1/work /ex1/root /ex1/live +# echo BASE=. > /ex1/ex1.conf +---- +==== -./opt/subhost/mta/mta.conf -**** +The minimal overlay subhost may then be started with +==== ---- -BASE=. -CABLES= = -START= rsyslog networking ssh postfix +# overlay-boot /ex1/ex1.conf ---- -**** - -The above example assumes a directory +/opt/subhost/mta+ that contains -the configuration file +mta.conf+ and directories +root+, +work+ and -+live+. *overlay-boot* will set up an overlay mount on +live+ with -+root+ as UPPER, +work+ as WORK and +/+ as LOWER, i.e. an overlay of -the main host filesystem. Further, the running subhost will feature a -virtual cable to the main host, where the subhost end is named +eth0+ -and the main host end is named +mta0+, and upon start, an +ifup mta0+ -is attempted at the host end while the subhost end is handled via its -neworking service. +==== +and it may be stopped with: +==== +---- +# overlay-stop /ex1/ex1.conf +---- +==== +The subhost environment may be "entered" with +==== +---- +# overlay-go ex1 +---- +==== -- 2.39.2