s6: the s6-svc program
Keywords: s6 command s6-svc supervise command service

s6
Software
skarnet.org

# The s6-svc program

s6-svc sends commands to a running s6-supervise process. In other words, it's used to control a supervised process; among other benefits, it allows an administrator to send signals to daemons without knowing their PIDs, and without using horrible hacks such as .pid files.

## Interface

         s6-svc [ -wu | -wU | -wd | -wD | -wr | -wR ] [ -T timeout ] [ -abqhkti12pcyoduxOr ] servicedir

s6-svc sends the given series of commands to the s6-supervise process monitoring the servicedir directory, then exits 0. It exits 111 if it cannot send a command, or 100 if no s6-supervise process is running on servicedir.

## Options

- `-a` : send a SIGALRM to the supervised process
- `-b` : send a SIGABRT to the supervised process
- `-q` : send a SIGQUIT to the supervised process
- `-h` : send a SIGHUP to the supervised process
- `-k` : send a SIGKILL to the supervised process
- `-t` : send a SIGTERM to the supervised process
- `-i` : send a SIGINT to the supervised process
- `-1` : send a SIGUSR1 to the supervised process
- `-2` : send a SIGUSR2 to the supervised process
- `-p` : send a SIGSTOP to the supervised process
- `-c` : send a SIGCONT to the supervised process
- `-y` : send a SIGWINCH to the supervised process
- `-o` : once. Equivalent to "-uO".
- `-d` : down. If the supervised process is up, send it a SIGTERM (by default) then a SIGCONT (to make sure even stopped processes receive the signal aimed to kill them) and do not restart it. The SIGTERM default can be changed by editing the `./down-signal` file in the service directory.
- `-u` : up. If the supervised process is down, start it. Automatically restart it when it dies.
- `-x` : exit. When the service is asked to be down and the supervised process dies, s6-supervise will exit too. This command should normally never be used on a working system. Note that if this command is sent and a `./finish` script exists for the service, the last `./finish` invocation before s6-supervise exits will run with its stdin and stdout redirected to `/dev/null`.
- `-O` : mark the service to run once at most. iow: do not restart the supervised process when it dies. If it is down when the command is received, do not even start it.
- `-r` : If the service is up, restart it, by sending it a signal to kill it and letting s6-supervise start it again. By default, the signal is a SIGTERM; this can be configured via the `./down-signal` file in the service directory.
- `-T timeout` : if the `-wstate` option has been given, `-T` specifies a timeout (in milliseconds) after which s6-svc will exit 1 with an error message if the service still hasn't reached the desired state. By default, the timeout is 0, which means that s6-svc will block indefinitely.
- `-wd` : s6-svc will not exit until the service is down, i.e. until the `run` process has died.
- `-wD` : s6-svc will not exit until the service is down and ready to be brought up, i.e. a possible `finish` script has exited.
- `-wu` : s6-svc will not exit until the service is up, i.e. there is a process running the `run` executable.
- `-wU` : s6-svc will not exit until the service is up and ready as notified by the daemon itself. If the service directory does not contain a `notification-fd` file to tell s6-supervise to accept readiness notification, s6-svc will print a warning and act as if the `-wu` option had been given instead.
- `-wr` : s6-svc will not exit until the service has been started or restarted.
- `-wR` : s6-svc will not exit until the service has been started or restarted and has notified readiness.

## Usage examples

     s6-svc -h /service/httpd

Send a SIGHUP to the process represented by the `/service/httpd` service directory. Traditionally, this makes web servers reload their configuration file.

     s6-svc -r /service/sshd

Kill (and automatically restart, if the wanted state of the service is up) the process represented by the `/service/sshd` service directory - typically the sshd server.

     s6-svc -wD -d /service/ftpd

Take down the ftpd server and block until the process is down and the finish script has completed.

     s6-svc -wU -T 5000 -u /service/ftpd

Bring up the ftpd server and block until it has sent notification that it is ready. Exit 1 if it is still not ready after 5 seconds.

     s6-svc -wR -t /service/ftpd

Send a SIGTERM to the ftpd server; wait for s6-supervise to restart it, and block until it has notified that it is ready to serve again. See the NOTES section below for a caveat.

     s6-svc -a /service/httpd/log

Send a SIGALRM to the logger process for the httpd server. If this logger process is s6-log, this triggers a log rotation.

## Internals

- s6-svc writes control commands into the `servicedir/supervise/control` FIFO. An s6-supervise process running on servicedir will be listening to this FIFO, and will read and interpret those commands.
- When invoked with one of the `-w` options, s6-svc executes into s6-svlisten1, which will listen to service state changes and spawn another s6-svc instance (without the `-w` option) that will send the commands to the service. Any error message written during the waiting period will mention it is being written by s6-svlisten1; this is normal.

## Notes

- The `-t` and `-r` options make s6-supervise send a signal to the service if it is up; but if the service is currently down, they do nothing, and in particular they do not instruct s6-supervise to bring the service up. Consequently, `s6-svc -rwr servicedir` may wait forever for the service to be up, if it is currently wanted down. To avoid that, make sure your service is wanted up by using `s6-svc -ruwr servicedir` instead.