226 lines
4.8 KiB
Groff
226 lines
4.8 KiB
Groff
|
.TH runsv 8
|
||
|
|
.SH NAME
|
||
|
|
runsv \- starts and monitors a service and optionally an appendant log
|
||
|
|
service
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.B runsv
|
||
|
|
.I service
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.I service
|
||
|
|
must be a directory.
|
||
|
|
.P
|
||
|
|
.B runsv
|
||
|
|
switches to the directory
|
||
|
|
.I service
|
||
|
|
and starts ./run.
|
||
|
|
If ./run exits and ./finish exists,
|
||
|
|
.B runsv
|
||
|
|
starts ./finish.
|
||
|
|
If ./finish doesn't exist or ./finish exits,
|
||
|
|
.B runsv
|
||
|
|
restarts ./run.
|
||
|
|
.P
|
||
|
|
If ./run or ./finish exit immediately,
|
||
|
|
.B runsv
|
||
|
|
waits a second before starting ./finish or restarting ./run.
|
||
|
|
.P
|
||
|
|
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
|
||
|
|
.BR waitpid (2);
|
||
|
|
for instance it is 0 if ./run exited normally, and the signal number
|
||
|
|
if ./run was terminated by a signal.
|
||
|
|
If
|
||
|
|
.B runsv
|
||
|
|
cannot start ./run for some reason, the exit code is 111 and the status is 0.
|
||
|
|
.P
|
||
|
|
If the file
|
||
|
|
.IR service /down
|
||
|
|
exists,
|
||
|
|
.B runsv
|
||
|
|
does not start ./run immediately.
|
||
|
|
The control interface (see below) can be used to start the service and to
|
||
|
|
give other commands to
|
||
|
|
.BR runsv .
|
||
|
|
.P
|
||
|
|
If the directory
|
||
|
|
.IR service /log
|
||
|
|
exists,
|
||
|
|
.B runsv
|
||
|
|
creates a pipe, redirects
|
||
|
|
.IR service /run's
|
||
|
|
and
|
||
|
|
.IR service /finish's
|
||
|
|
standard output to the pipe, switches to the directory
|
||
|
|
.IR service /log
|
||
|
|
and starts ./run (and ./finish) exactly as described above for the
|
||
|
|
.I service
|
||
|
|
directory.
|
||
|
|
The standard input of the log service is redirected to read from the pipe.
|
||
|
|
.P
|
||
|
|
.B runsv
|
||
|
|
maintains status information in a binary format (compatible to the
|
||
|
|
daemontools'
|
||
|
|
.B supervise
|
||
|
|
program) in
|
||
|
|
.IR service /supervise/status
|
||
|
|
and
|
||
|
|
.IR service /log/supervise/status,
|
||
|
|
and in a human-readable format in
|
||
|
|
.IR service /supervise/stat,
|
||
|
|
.IR service /log/supervise/stat,
|
||
|
|
.IR service /supervise/pid,
|
||
|
|
.IR service /log/supervise/pid.
|
||
|
|
.SH CONTROL
|
||
|
|
The named pipes
|
||
|
|
.IR service /supervise/control,
|
||
|
|
and (optionally)
|
||
|
|
.IR service /log/supervise/control
|
||
|
|
are provided to give commands to
|
||
|
|
.BR runsv .
|
||
|
|
You can use
|
||
|
|
.BR sv (8)
|
||
|
|
to control the service or just write one of the following characters to
|
||
|
|
the named pipe:
|
||
|
|
.TP
|
||
|
|
.B u
|
||
|
|
Up.
|
||
|
|
If the service is not running, start it.
|
||
|
|
If the service stops, restart it.
|
||
|
|
.TP
|
||
|
|
.B d
|
||
|
|
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.
|
||
|
|
.TP
|
||
|
|
.B o
|
||
|
|
Once.
|
||
|
|
If the service is not running, start it.
|
||
|
|
Do not restart it if it stops.
|
||
|
|
.TP
|
||
|
|
.B p
|
||
|
|
Pause.
|
||
|
|
If the service is running, send it a STOP signal.
|
||
|
|
.TP
|
||
|
|
.B c
|
||
|
|
Continue.
|
||
|
|
If the service is running, send it a CONT signal.
|
||
|
|
.TP
|
||
|
|
.B h
|
||
|
|
Hangup.
|
||
|
|
If the service is running, send it a HUP signal.
|
||
|
|
.TP
|
||
|
|
.B a
|
||
|
|
Alarm.
|
||
|
|
If the service is running, send it a ALRM signal.
|
||
|
|
.TP
|
||
|
|
.B i
|
||
|
|
Interrupt.
|
||
|
|
If the service is running, send it a INT signal.
|
||
|
|
.TP
|
||
|
|
.B q
|
||
|
|
Quit.
|
||
|
|
If the service is running, send it a QUIT signal.
|
||
|
|
.TP
|
||
|
|
.B 1
|
||
|
|
User-defined 1.
|
||
|
|
If the service is running, send it a USR1 signal.
|
||
|
|
.TP
|
||
|
|
.B 2
|
||
|
|
User-defined 2.
|
||
|
|
If the service is running, send it a USR2 signal.
|
||
|
|
.TP
|
||
|
|
.B t
|
||
|
|
Terminate.
|
||
|
|
If the service is running, send it a TERM signal.
|
||
|
|
.TP
|
||
|
|
.B k
|
||
|
|
Kill.
|
||
|
|
If the service is running, send it a KILL signal.
|
||
|
|
.TP
|
||
|
|
.B x
|
||
|
|
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,
|
||
|
|
.B runsv
|
||
|
|
exits.
|
||
|
|
If the service is down and a log service exists,
|
||
|
|
.B runsv
|
||
|
|
closes the standard input of the log service, and waits for it to terminate.
|
||
|
|
If the log service is down,
|
||
|
|
.B runsv
|
||
|
|
exits.
|
||
|
|
This command is ignored if it is given to
|
||
|
|
.IR service /log/supervise/control.
|
||
|
|
.P
|
||
|
|
Example: to send a TERM signal to the socklog-unix service, either do
|
||
|
|
# sv term /service/socklog-unix
|
||
|
|
or
|
||
|
|
# printf t >/service/socklog-unix/supervise/control
|
||
|
|
.P
|
||
|
|
.BR printf (1)
|
||
|
|
usually blocks if no
|
||
|
|
.B runsv
|
||
|
|
process is running in the service directory.
|
||
|
|
.SH CUSTOMIZE CONTROL
|
||
|
|
For each control character
|
||
|
|
.I c
|
||
|
|
sent to the control pipe,
|
||
|
|
.B runsv
|
||
|
|
first checks if
|
||
|
|
.I service\fR/control/\fIc
|
||
|
|
exists and is executable.
|
||
|
|
If so, it starts
|
||
|
|
.I service\fR/control/\fIc
|
||
|
|
and waits for it to terminate, before interpreting the command.
|
||
|
|
If the program exits with return code 0,
|
||
|
|
.B runsv
|
||
|
|
refrains from sending the service the corresponding signal.
|
||
|
|
The command
|
||
|
|
.I o
|
||
|
|
is always considered as command
|
||
|
|
.IR u .
|
||
|
|
On command
|
||
|
|
.I d
|
||
|
|
first
|
||
|
|
.I service\fR/control/t
|
||
|
|
is checked, and then
|
||
|
|
.I service\fR/control/d.
|
||
|
|
On command
|
||
|
|
.I x
|
||
|
|
first
|
||
|
|
.I service\fR/control/t
|
||
|
|
is checked, and then
|
||
|
|
.I service\fR/control/x.
|
||
|
|
The control of the optional log service cannot be customized.
|
||
|
|
.SH SIGNALS
|
||
|
|
If
|
||
|
|
.B runsv
|
||
|
|
receives a TERM signal, it acts as if the character x was written to the
|
||
|
|
control pipe.
|
||
|
|
.SH EXIT CODES
|
||
|
|
.B runsv
|
||
|
|
exits 111 on an error on startup or if another
|
||
|
|
.B runsv
|
||
|
|
is running in
|
||
|
|
.IR service .
|
||
|
|
.P
|
||
|
|
.B runsv
|
||
|
|
exits 0 if it was told to exit.
|
||
|
|
.SH SEE ALSO
|
||
|
|
sv(8),
|
||
|
|
chpst(8),
|
||
|
|
svlogd(8),
|
||
|
|
runit(8),
|
||
|
|
runit-init(8),
|
||
|
|
runsvdir(8),
|
||
|
|
runsvchdir(8),
|
||
|
|
utmpset(8)
|
||
|
|
.P
|
||
|
|
http://smarden.org/runit/
|
||
|
|
.SH AUTHOR
|
||
|
|
Gerrit Pape <pape@smarden.org>
|