man > runsv(8)

runsv(8)                               System Manager's Manual                              runsv(8)

NAME
       runsv - starts and monitors a service and optionally an appendant log service

SYNOPSIS
       runsv service

DESCRIPTION
       service must be a directory.

       runsv  switches  to  the directory service and starts ./run.  If ./run exits and ./finish ex‐
       ists, runsv starts ./finish.  If ./finish doesn't exist or  ./finish  exits,  runsv  restarts
       ./run.

       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 de‐
       termined  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 inter‐
       face (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, redirects service/run's  and  ser‐
       vice/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 pipe.

       runsv maintains status information in a binary format (compatible to the daemontools'  super‐
       vise  program)  in service/supervise/status and service/log/supervise/status, and in a human-
       readable format in service/supervise/stat, service/log/supervise/stat, service/supervise/pid,
       service/log/supervise/pid.

CONTROL
       The named pipes service/supervise/control, and (optionally) service/log/supervise/control are
       provided to give commands to runsv.  You can use sv(8) to control the service or  just  write
       one of the following characters to the named pipe:

       u      Up.  If the service is not running, start it.  If the service stops, restart it.

       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.

       o      Once.  If the service is not running, start it.  Do not restart it if it stops.

       p      Pause.  If the service is running, send it a STOP signal.

       c      Continue.  If the service is running, send it a CONT signal.

       h      Hangup.  If the service is running, send it a HUP signal.

       a      Alarm.  If the service is running, send it a ALRM signal.

       i      Interrupt.  If the service is running, send it a INT signal.

       q      Quit.  If the service is running, send it a QUIT signal.

       1      User-defined 1.  If the service is running, send it a USR1 signal.

       2      User-defined 2.  If the service is running, send it a USR2 signal.

       t      Terminate.  If the service is running, send it a TERM signal.

       k      Kill.  If the service is running, send it a KILL signal.

       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, runsv ex‐
              its.  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 service/log/supervise/control.

       Example: to send a TERM signal to the socklog-unix service, either do
         # sv term /etc/service/socklog-unix
        or
         # printf t >/etc/service/socklog-unix/supervise/control

       printf(1) usually blocks if no runsv process is running in the service directory.

CUSTOMIZE CONTROL
       For each control character c except "d" and "x" sent to the control pipe, runsv first  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  u.   On  command d first service/control/t is checked, and then ser‐
       vice/control/d.  On command x first service/control/t is checked, and then service/control/x.
       Specifically:

       If the service is running or paused, control characters "d" and "x" are handled as follows:

       1.     runsv checks whether service/control/t exists and is executable and runs it if yes.

       2.     If service/control/t exits nonzero, or is not executable or doesn't exist, runsv sends
              the service a TERM signal.

       3.     runsv sends the service a CONT signal, disregarding service/control/c even if  it  ex‐
              ists and is executable.

       4.     runsv  checks  whether  service/control/d  (or control/x) exists and is executable and
              runs it if yes. Its exit status is ignored.

       The control of the optional log service cannot be customized.

SIGNALS
       If runsv receives a TERM signal, it acts as if the character x was  written  to  the  control
       pipe.

EXIT CODES
       runsv exits 111 on an error on startup or if another runsv is running in service.

       runsv exits 0 if it was told to exit.

SEE ALSO
       sv(8), chpst(8), svlogd(8), runit(8), runit-init(8), runsvdir(8), runsvchdir(8), utmpset(8)

       http://smarden.org/runit/

AUTHOR
       Gerrit Pape <pape AT smarden.org>

                                                                                            runsv(8)