The s6-rc-update program
s6-rc-update is an online service database switcher:
it will replace your compiled service database with another
one, and adjust the live state accordingly. This allows you to
change your set of services without having to reboot.
Live upgrading a service database is not easy, and no
fully automated system can get it right in all cases.
s6-rc-update will do its best on its own, but it lets the user
give it instructions to handle
difficult cases; and rather than implement doubtful
heuristics, it will fail with an error message in
situations it cannot solve.
s6-rc-update [ -n ] [ -v verbosity ] [ -t timeout ] [ -l live ] [ -f convfile ] [ -b ] newdb
- s6-rc-update analyzes the current live state, the current compiled service
database, and the compiled service database contained at newdb
(which must be an absolute path).
- Additionally, it can process an optional conversion file containing
- It computes the necessary service transitions to safely update the live
- It shuts down the necessary services.
- It updates the live directory so that newdb becomes the
live compiled service database.
- It starts up the necessary services.
- 0: success
- 1: failure to perform some state transitions, but the database was switched to newdb
- 2: timed out, but the database was switched to newdb
- 3: unknown service name in the conversion file
- 4: invalid service database
- 5: wrong service type in the conversion file
- 6: duplicate service in the conversion file
- 9: failure to perform some state transitions, and the database was not switched
- 10: timed out, and the database was not switched
- 100: wrong usage
- 111: system call failed
- 126: cannot exec into s6-rc for the final "up" transition (error other than ENOENT)
- 127: cannot exec into s6-rc for the final "up" transition (executable not found)
- -n : dry run. s6-rc-update will compute the service
transitions, and print the s6-rc command lines
it would execute to perform those transitions. It will not actually
run them or modify the live database.
- -v verbosity : be more or less
verbose. Default is 1: warning and error messages will be printed to
stderr. 0 silences warnings. 2 adds a bit more information about
what s6-rc-update is doing. 3 or more is heavy debug output.
- -t timeout : if s6-rc-update cannot
perform its job within timeout milliseconds, it will exit.
The default is 0, meaning infinite (no timeout). Be aware that timing
out and exiting may leave the live database in an inconsistent state,
so use of this option is not recommended.
- -l live : look for the
live state in live. It must be an absolute path.
Default is /run/s6-rc.
The default can be changed at compile-time by giving the
--livedir=live option to ./configure.
- -f convfile : use the conversion
file located at convfile. Default is /dev/null,
meaning no special instructions.
- -b : blocking lock. If the database is currently
being used by another program, s6-rc-update will wait until that
other program has released its lock on the database, then proceed.
By default, s6-rc-update fails with an error message if the database
is currently in use.
s6-rc-update's job is to ensure consistency of the live state across
a change of compiled service databases. To do so, it must make sure
that the services that are up at the time of its invocation are still
up after its invocation; but service definitions in the new compiled
may be different from those in the old one - in particular, dependencies
may change, or a service can change types: a oneshot can become
a longrun and vice-versa, and an atomic service can even become a
s6-rc-update examines atomic services, as defined in the old compiled,
that are up at invocation time, and computes what is necessary for the
"same" services, as defined in the new compiled, to be up. Barring
instructions from the conversion file, the service is "the same" if it has the
same name in the new compiled, no matter its type.
So, if there is an up oneshot named sshd in the old compiled,
and there is a longrun named sshd in the new compiled, then
s6-rc-update will decide that the new sshd longrun will replace
the old sshd oneshot. If the new compiled defines a sshd
bundle instead, then s6-rc-update will decide that the old sshd
oneshot will be replaced with the contents of the sshd bundle.
s6-rc-update tries to avoid needlessly restarting services. For instance,
running it with a new compiled that is an exact copy of
the old compiled should not cause any restarts. s6-rc-update will flag a
service to be restarted in the following cases:
- The service has disappeared in the new compiled. In this case, the
old service will simply be stopped.
- The service has changed types: a oneshot becomes a longrun, a longrun
becomes a oneshot, or an atomic service becomes a bundle. In this case, the
old service will be stopped, then the new service will be started.
- The service has a dependency to a service that must restart, or to an
old service that must stop, or to a new service that did not previously
exist or that was previously down.
- There is an instruction to restart the service in the conversion file.
After it has decided what services it should restart, s6-rc-update will:
- Invoke s6-rc to stop old services.
- Update the live directory with the data from the new compiled.
This is the critical part; s6-rc-update should not be interrupted at this point.
It does its best to avoid risking leaving behind an inconsistent state,
but a 100% atomicity guarantee is impossible to achieve.
- Adjust pipe names for the existing pipelines, if needed.
- Exec into s6-rc to start new services.
The conversion file
The conversion file is used to give s6-rc-update instructions when the
change of databases is not entirely straightforward. Currently, it
supports the following features:
- changing the name of a service
- forcing a restart on a service
The conversion file is a sequence of lines; each line is parsed
independently, there's no carrying of information from one line to
A line is lexed into words by the
lexer, which means that words are normally separated by whitespace, but
can be quoted, that # comments are recognized, etc.
The first word in a line must be the name of an "old" atomic service, i.e.
an atomic service contained in the current live database. The remaining
words in the line are instructions telling s6-rc-update how to convert
If the second word in the line is ->, then the third word in the
line must be the new name of the service in the new database: s6-rc-update
will then rename it. It is possible
to rename an atomic service to another atomic service or a bundle, but no
matter whether a service is renamed or not, changing its type will force a
If the word following either the old name, or a renaming instruction, is the
word restart, then the service will forced to restart.
Consider the following conversion file:
# Simple conversion file
mount-var -> mount-rwfs
sqld -> mysqld restart
- It will rename mount-var to mount-rwfs, not restarting it
if mount-var in the old database and mount-rwfs in the new
database have the same type and do not depend on services that would force a
- It will restart httpd
- It will rename sqld to mysqld and make it restart.
Safely managing and updating compiled databases
The sequence of operations needed to update a database from source to live
can be a little tricky. It involves:
- Compiling the new database without overwriting the live one
- Calling s6-rc-update to safely replace the live database
- Making sure the new database will be correctly used at boot time
FAQ entry gives a step-by-step explanation on how to proceed.
- The live argument to the -l option, if present, should
be the same argument that was given to the
s6-rc-init invocation when the system was
booted. In other words: it should be the name of the symbolic link pointing
to the real directory containing the live information, not the name of the
- If a longrun service is renamed from oldname to newname,
but not restarted, the
process in charge of it will still show up in the process list as
s6-supervise oldname. This is purely cosmetic and
will have no impact on the service; nevertheless, if you wish to avoid that,
simply force a restart on every longrun you rename.
- After a s6-rc-update invocation, the old compiled service database
is left unchanged where it was, and the new compiled
service database is used in-place. If the machine is rebooted, the
s6-rc-init invocation will still boot on the
old compiled unless more work is performed. It is recommended to keep a
current symbolic link to the current compiled, to always
s6-rc-init on current, and to
make current a link to the new compiled right after a s6-rc-update
- s6-rc-update is the only way to "free" the old compiled database
for displacement or deletion. A live compiled database must not be
tampered with. After a s6-rc-update invocation, the old database isn't
live anymore and can be moved or deleted; instead, newdb is