# man > runsv(8)

[_runsv_(8)](https://www.chedong.com/phpMan.php/man/runsv/8/markdown)                               System Manager's Manual                              [_runsv_(8)](https://www.chedong.com/phpMan.php/man/runsv/8/markdown)

## 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)](https://www.chedong.com/phpMan.php/man/waitpid/2/markdown); 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)](https://www.chedong.com/phpMan.php/man/sv/8/markdown) 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)](https://www.chedong.com/phpMan.php/man/printf/1/markdown) 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)](https://www.chedong.com/phpMan.php/man/sv/8/markdown), [chpst(8)](https://www.chedong.com/phpMan.php/man/chpst/8/markdown), [svlogd(8)](https://www.chedong.com/phpMan.php/man/svlogd/8/markdown), [runit(8)](https://www.chedong.com/phpMan.php/man/runit/8/markdown), [runit-init(8)](https://www.chedong.com/phpMan.php/man/runit-init/8/markdown), [runsvdir(8)](https://www.chedong.com/phpMan.php/man/runsvdir/8/markdown), [runsvchdir(8)](https://www.chedong.com/phpMan.php/man/runsvchdir/8/markdown), [utmpset(8)](https://www.chedong.com/phpMan.php/man/utmpset/8/markdown)

       <http://smarden.org/runit/>

## AUTHOR
       Gerrit Pape <<pape@smarden.org>>

                                                                                            [_runsv_(8)](https://www.chedong.com/phpMan.php/man/runsv/8/markdown)