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 ] [ -abqhkti12pcyroduDUxO ] 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.
-D : down, and create a ./down file so the service does not restart automatically if the supervisor dies.
-u : up. If the supervised process is down, start it. Automatically restart it when it dies.
-U : up, and remove any ./down file that may exist, in order to make sure the service is automatically restarted even if the supervisor 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.