X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;ds=sidebyside;f=overlay-boot.8.adoc;h=e97a8e4676cad9d8da15cc23f55f5469923e9ce0;hb=51abada33ae4c5733285832669f5cb4609fa7773;hp=172a228ac31277eeeab3fb6462d08f684aee383a;hpb=2fe3f08e0c23ff50a6203c947d7cdf11e5ceac6c;p=rrq%2Foverlay-boot.git diff --git a/overlay-boot.8.adoc b/overlay-boot.8.adoc index 172a228..e97a8e4 100644 --- a/overlay-boot.8.adoc +++ b/overlay-boot.8.adoc @@ -24,7 +24,7 @@ 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 +A subhost is started by identifying 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 @@ -34,7 +34,7 @@ odd computer. The subhost execution environment may be "entered" to perform adminstrative tasks with *overlay-go*, and it is later stopped with -*overlay-stop*. +*overlay-stop*. OPTIONS ------- @@ -71,7 +71,7 @@ section on Networking below for more details. INIT:: -This variable is a command line to run, with envirnment variable +This variable is a command line to run, with environment 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+. @@ -100,17 +100,21 @@ as UPPER. *POSTMOUNT*:: -This variable is a command line to run, with envirnment variable +This variable is a command line to run, with environment 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+ ++overlay-postmount+. Note that this command is executed within the +mount namespace of the subhost, and still with the main host as root +filesystem. *PREMOUNT*:: -This variable is a command line to run, with envirnment variable +This variable is a command line to run, with environment 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+ ++overlay-premount+ Note that this command is executed within the +mount namespace of the subhost, and still with the main host as root +filesystem. *UPPER*:: @@ -123,8 +127,8 @@ 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. +setup as an overlay. It Is rather set up either as a bind mount if UPPER is +different from LIVE, or just taken as a pre-mounted LIVE filesystem. *WORK*:: @@ -151,16 +155,16 @@ defult gets mounted on an overlay mount as a +tmpfs+ of 50M. Use 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. +*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. +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 @@ -177,9 +181,11 @@ EXAMPLES ./opt/subhost/mta/mta.conf **** +---- BASE=. CABLES= = -START= rsyslog newtorking ssh postfix +START= rsyslog networking ssh saslauthd postfix dovecot +---- **** The above example assumes a directory +/opt/subhost/mta+ that contains @@ -192,5 +198,26 @@ 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. +./opt/subhost/tiny/tiny.conf +**** +---- +BASE=. +CABLES= = +START= none +LOWER=!mkdir -p base work root live ; echo base +WORK= work +UPPER= root +LIVE= live +---- +**** + +The +tiny+ subhost would be for overlaying a separate +debootstrap+ +root filesystem, without any services (since +START+ is empty). This +gets started with a +dummy_service+ to hold the overlay for access via ++overlay-go+. The +dummy_service+ sets up and listens on a pipe at ++/run/dummy_service+, and exits when anything is written to that. +SEE ALSO +-------- +*overlay-stop*, *overlay-go*