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

Exit codes


Transition details

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 bundle.

Service identity

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:


After it has decided what services it should restart, s6-rc-update will:

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:


The conversion file is a sequence of lines; each line is parsed independently, there's no carrying of information from one line to the next.

A line is lexed into words by the execlineb 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 that service.


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 restart.


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
httpd restart
sqld -> mysqld 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:

This FAQ entry gives a step-by-step explanation on how to proceed.