-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
+----
+====
projects / rrq / overlay-boot.git / commitdiff