From 817c920272ad2aa4b56940120e329b9cf1582779 Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Sun, 28 May 2023 08:58:12 +1000 Subject: [PATCH] Documentation update to use asciidoctor for manpage generation. Also added detail about VLAN networking setup. --- Makefile | 2 +- debian/control | 2 +- overlay-boot.8.adoc | 40 ++++++++++++++++++++++++++++------------ 3 files changed, 30 insertions(+), 14 deletions(-) diff --git a/Makefile b/Makefile index bc4f1cc..022b9ff 100644 --- a/Makefile +++ b/Makefile @@ -39,7 +39,7 @@ $(ETCDIR)/subhosts.conf: subhosts.conf | $(ETCDIR)/ # Generic rule: a local .8 file depends on the same .8.adoc file, if any $(MAN8FILES): %: %.adoc - a2x -d manpage -f manpage $^ + asciidoctor -b manpage $^ # Generic rule: an installed MAN8FILE file depends on a local the # same, and that the installation directory exists diff --git a/debian/control b/debian/control index 98f5ba8..dbbb374 100644 --- a/debian/control +++ b/debian/control @@ -3,7 +3,7 @@ Section: misc Priority: optional Maintainer: Ralph Ronnquist Build-Depends: debhelper-compat (= 13), - asciidoc, docbook-xml, libxslt1-dev, xsltproc, docbook-xsl, + asciidoctor, docbook-xml, libxslt1-dev, xsltproc, docbook-xsl, musl-tools Standards-Version: 4.6.0 Homepage: https://borta.rrq.id.au/git?p=ralph/overlay-boot.git diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc index c7c3508..dee7b10 100644 --- a/overlay-boot.8.adoc +++ b/overlay-boot.8.adoc @@ -19,21 +19,24 @@ DESCRIPTION administration scripts for containerizing services with minimal ado. The script starts a "subhost" whose root filesystem is an overlay on the main host filesystem, and with separate mount, network and pid -namespaces. In effect an administrative sandboxing that is -prepopulated with a copy of the overlaid filesystem. +namespaces. In effect the default use case is merely an administrative +sandboxing that is pre-populated with a copy of the overlaid +filesystem. -The subhost is defined by means of a configuration file, __conf__, +Each subhost is defined by means of a configuration file, __conf__, that is a simple text file with small collection of "variables" telling how the subhost is set up. *overlay-boot* spawns a subprocess that performs the boot-up of the "subhost" as an init script that ends with a pid 1 +reaper+ that simply "reaps" any terminated child processes. -The administrator may "enter" the subhost execution environment to -perform adminstrative tasks by means of *overlay-go*, which starts an -interactive shell within the subhost namespaces. Usually this is only -used initially for configuring the subhost's network and set up an -_sshd_ service for subsequent access. +An administrator may "enter" the subhost execution environment to +perform adminstrative tasks by means of *overlay-go*, which uses ++chroot+ to start an interactive shell within the subhost namespaces. +Such a shell however is not a child of the subhost +pid 1+ and it +would normally only be used initially for configuring the subhost's +network, and set up network based services, such as _sshd_, for +subsequent access. Subhost execution is stopped with *overlay-stop*. @@ -71,8 +74,8 @@ contains the configuration file and the three mount points "root", 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 optionally a MAC address to the right. See the -section on Networking below for more details. +name to the left and optionally a MAC address or VLAN tag to the +right. See the section on Networking below for more details. INIT:: @@ -184,8 +187,8 @@ by the same number. As mentioned above, +CABLES+ is a space separated list of cable specifiers, each consisting of an optional bridge interface name, an -optional MAC adddress and with a required equal sign ("=") between -them. +optional MAC adddress or VLAN tag and with a required equal sign ("=") +between them. The bridge interface name, when given, will be given control of the host end cable interface. When the bridge interface name is omitted @@ -196,6 +199,19 @@ The MAC address, if given, is used for the subhost end cable interface, which otherise gets its MAC address from the kernel, possibly a different one upon each start. +A VLAN tag has the format ".N" where N is a number between 1 and 4095. +This modifies the cable function to set up a VLAN host interface on +the prior host interface, and skip subhost side setup. E.g. if the +prior host interface is +example1+ and the tag is +.302+ then the VLAN +interface would be +example1.302+. The host side setup uses _ifup $IF_ +and thus, the host needs to have a supporting configuration entry in ++/etc/network/interfaces+ for the VLAN interface. + +Note that it may be a good practice to keep a local +interfaces+ file +as sibling to the subhost configuration file on the host and use a +_source_ statement to include this into the system networking +configuration. + EXAMPLES -------- -- 2.39.2