You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
Ralph Rönnquist 6392a347ae cleanup 8 months ago
asm cleanup 8 months ago
debian version change 8 months ago
Makefile refactoring for more flexible config 8 months ago
README.adoc example fix 8 months ago
functions refactoring for more flexible config 8 months ago
overlay-boot refactoring for more flexible config 8 months ago
overlay-boot.8.adoc example fix 8 months ago
overlay-go handle missng name 8 months ago
overlay-init refactoring for more flexible config 8 months ago
overlay-postmount refactoring for more flexible config 8 months ago
overlay-premount refactoring for more flexible config 8 months ago
overlay-stop refactoring for more flexible config 8 months ago

README.adoc

overlay-boot(8) Manual Page

NAME

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

/opt/subhost/mta/mta.conf
BASE=.
CABLES= =
START= rsyslog networking 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.