From 85e2821400dafd4afc4b75da331d2fd2129c5238 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 4 Dec 2017 18:11:24 +0000 Subject: Add s6-rc-format-upgrade --- doc/index.html | 6 ++ doc/s6-rc-format-upgrade.html | 125 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 131 insertions(+) create mode 100644 doc/s6-rc-format-upgrade.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index ee06542..9ce7128 100644 --- a/doc/index.html +++ b/doc/index.html @@ -111,6 +111,12 @@ the previous versions of s6-rc and the current one.

Upgrading from earlier s6-rc database formats

+ +

The s6-rc-format-upgrade program

Programs used internally

s6-rc: the s6-rc-format-upgrade program

+s6-rc
+Software
+skarnet.org +

The s6-rc-format-upgrade program

+ s6-rc-format-upgrade is a program that is normally used +very rarely: when the s6-rc package is upgraded, some +services are currently managed with s6-rc, and the database +format has changed. This program transitions a live directory +using a database with the old s6-rc format (the one being +replaced) so that it uses a database with the new s6-rc format. +

+ The point is to ensure a smooth transition between different +versions of s6-rc without needing a reboot. +

+ s6-rc-format-upgrade is very different from +s6-rc-update and does not +duplicate its functionality: +

s6-rc-update updates a +live directory to use a different compiled database, +compiled from a different source, where services may have +changed, be renamed, etc. But it can only handle databases +with the format that it knows - the format created by the +s6-rc-compile binary that +comes in the same package as s6-rc-update.
s6-rc-format-upgrade is the opposite: it cannot handle +service changes, it can only update a live directory to use +a compiled database corresponding to the same source +as the compiled database the live directory is currently +using. But it will replace an obsolete compiled database with +a compiled database that uses the new format (provided both +compiled databases come from the same source, and have just been +produced by invocation of different versions of +s6-rc-compile), ensuring the +s6-rc installation can live through database format changes.

Interface

+     s6-rc-format-upgrade [ -v verbosity ] [ -l live ] [ -t timeout ] [ -b ] newcompiled
+

newcompiled must be an absolute path.
s6-rc-format-upgrade expects to find a compiled service database +with the new format in compiled
newcompiled must be compiled from +the same source database as the current compiled database currently +being used by live. +
s6-rc-format-upgrade then updates the live directory in live +so it uses newcompiled as its compiled database.
On success, it exits 0.

Options

-v verbosity : be more or less +verbose. Default is 1.
-t timeout : if all +operations have not completed after timeout +milliseconds, complain and exit 1.
-l live : Work with the live state in +the live directory. Default is +/run/s6-rc. The default can be changed at compile time by +giving the --livedir=live option to +./configure.
-b : blocking lock. If live is currently +being used by another program, s6-rc-format-upgrade will wait until that +other program has released its lock on the directory, then proceed. +By default, s6-rc-format-upgrade fails with an error message if the live +directory is currently in use.

Typical usage

+ s6-rc-format-upgrade is only necessary when the database format +changes, which only happens when s6-rc's major version number +(the third number from the right) changes. The correct order of +operations is then the following: +

Make sure your current compiled database is up-to-date +with your source database. If it's not, update it, by invoking +the s6-rc-compile and +s6-rc-update binaries from your +old s6-rc installation, the ones that +understand the old format.
From the same source, compile a new database with the new format, +using the s6-rc-compile binary +from the new s6-rc package.
Update your live directories with this new database, using +s6-rc-format-upgrade.
You can now remove the old databases, and delete the old +s6-rc package.