runsv - starts and monitors a service and optionally an appendant log service
must be a directory.
switches to the directory service
and starts ./run. If ./run
exits and ./finish exists, runsv
starts ./finish. If ./finish doesn't
exist or ./finish exits, runsv
If ./run or ./finish exit immediately, runsv
waits a second before
starting ./finish or restarting ./run.
Two arguments are given to ./finish. The first one is ./run's exit code, or -1
if ./run didn't exit normally. The second one is the least significant byte of
the exit status as determined by waitpid
(2); for instance it is 0 if
./run exited normally, and the signal number if ./run was terminated by a
signal. If runsv
cannot start ./run for some reason, the exit code is
111 and the status is 0.
If the file service
/down exists, runsv
does not start ./run
immediately. The control interface (see below) can be used to start the
service and to give other commands to runsv
If the directory service
/log exists, runsv
creates a pipe,
/run's and service
/finish's standard output to
the pipe, switches to the directory service
/log and starts ./run
script. The standard input of the log service is redirected to read from the
maintains status information in a binary format (compatible to the
program) in service
/log/supervise/status, and in a human-readable format in
The named pipes service
/supervise/control, and (optionally)
/log/supervise/control are provided to give commands to
. You can use sv
(8) to control the service or just write
one of the following characters to the named pipe:
- Up. If the service is not running, start it. If the service
stops, restart it.
- Down. If the service is running, send it a TERM signal, and
then a CONT signal. If ./run exits, start ./finish if it exists. After it
stops, do not restart service.
- Once. If the service is not running, start it. Do not
restart it if it stops.
- Pause. If the service is running, send it a STOP
- Continue. If the service is running, send it a CONT
- Hangup. If the service is running, send it a HUP
- Alarm. If the service is running, send it a ALRM
- Interrupt. If the service is running, send it a INT
- Quit. If the service is running, send it a QUIT
- User-defined 1. If the service is running, send it a USR1
- User-defined 2. If the service is running, send it a USR2
- Terminate. If the service is running, send it a TERM
- Kill. If the service is running, send it a KILL
- Exit. If the service is running, send it a TERM signal, and
then a CONT signal. Do not restart the service. If the service is down,
and no log service exists, runsv exits. If the service is down and
a log service exists, runsv closes the standard input of the log
service, and waits for it to terminate. If the log service is down,
runsv exits. This command is ignored if it is given to
Example: to send a TERM signal to the socklog-unix service, either do
# sv term /etc/service/socklog-unix
# printf t >/etc/service/socklog-unix/supervise/control
(1) usually blocks if no runsv
process is running in the
For each control character c
sent to the control pipe, runsv
checks if service/control/c exists and is executable.
If so, it starts service/control/c and waits for it to
terminate, before interpreting the command. If the program exits with
return code 0, runsv
refrains from sending the service the
corresponding signal. The command o
is always considered as command
. On command d
is checked, and
On command x
is checked, and then service/control/x.
control of the optional log service cannot be customized.
receives a TERM signal, it acts as if the character x was
written to the control pipe.
exits 111 on an error on startup or if another runsv
running in service
exits 0 if it was told to exit.
sv(8), chpst(8), svlogd(8), runit(8), runit-init(8), runsvdir(8), runsvchdir(8),
Gerrit Pape <email@example.com>