S6-RC-FORMAT-UPGRADE(8)

NAME
s6-rc-format-upgrade - transitions a live directory using a database with the old s6-rc format so that it uses a database with the new s6-rc format

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

DESCRIPTION
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(8), 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(8) and does not duplicate its functionality:

•   s6-rc-update(8) 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(8) binary that comes in the same package as s6-rc-update(8).

•   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(8)), ensuring the s6-rc installation can live through database format changes.

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.

  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:

1.  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(8) and s6-rc-update(8) binaries from your old s6-rc installation, the ones that understand the old format.

2.  From the same source, compile a new database with the new format, using the s6-rc-compile(8) binary from the new s6-rc package.

3.  Update your live directories with this new database, using s6-rc-format-upgrade.

4.  You can now remove the old databases, and delete the old s6-rc package.

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.

SEE ALSO
s6-rc-faq(7), s6-rc-overview(7), s6-rc-why(7), s6-rc(8), s6-rc-bundle(8), s6-rc-compile(8), s6-rc-db(8), s6-rc-dryrun(8), s6-rc-fdholder-filler(8), s6-rc-init(8), s6-rc-oneshot-run(8), s6-rc-update(8)

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-rc/s6-rc-format-upgrade.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)