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.