Browse Source

freshen up

master
Ralph Rönnquist 8 months ago
parent
commit
76e38dcd5e
  1. 175
      README.adoc

175
README.adoc

@ -11,31 +11,49 @@ overlay-boot - Start a subhost with overlay root filesystem.
SYNOPSIS
--------
*overlay-boot _conf_
*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.
*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.
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 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.
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*::
@ -45,74 +63,90 @@ 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.
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.
See the section on Networking below for more details.
INIT::
*LIVE*::
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+.
This variable nominates the mount point for the overlay mount, and it
defaults to +$BASE/live+ (which also must exist).
*LIVE*::
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.
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 log file to use by +overlay-boot+. The
default is +/tmp/overlay-$NAME.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 the overlay. This
will be accessed read-only, an it is intended to be the operating
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.
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 the overlay. This
will be accessed read-write and constitutes the "private" files of the
subhost.
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 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".
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 the overlay mount. It
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. 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+.
overlay-boot startup. The default value is +networking ssh+.
Note that if no services are started, then a +dummy_service+ gets
started so as to keep keep +/.reaper+ from running out of child
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+.
That +dummy_service+ may be killed by a signal, or by writing to the
+/run/dummy_service+ pipe.
*RAM_SIZE*::
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.
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
----------
@ -138,22 +172,25 @@ 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.
boot-up
-------
EXAMPLES
--------
./opt/subhost/mta/mta.conf
****
BASE=.
CABLES= =
START= rsyslog newtorking ssh postfix
****
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.
*overlay-boot* includes a small boot-up section that consists of the
following command sequence:
----
mount -t proc proc /proc
mount -t devpts devpts /dev/pts
mount -t sysfs sysfs /sys
if [ "$RAM_SIZE" != "none" ] && ! grep -q '/run tmpfs' /proc/mounts ; then
mount -t tmpfs -osize=$RAM_SIZE,mode=755 tmpfs /run
fi
for srv in $START ; do
service $srv start
done
----
Thereafter the *overlay-boot* command shell (+/bin/sh+) morphs into
running +/.reaper+ which simply waits and "reaps" child processes
until it runs out of those and exist.

Loading…
Cancel
Save