xenial (8) runsv.8.gz

Provided by: runit_2.1.2-3ubuntu1_amd64 bug

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 exists, 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 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, redirects service/run's  and  service/finish's
       standard  output  to  the  pipe,  switches  to  the directory service/log and starts ./run (and ./finish)
       exactly as described above for the  service  directory.   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' supervise 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 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 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 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  service/control/d.   On  command  x  first  service/control/t  is
       checked, and then service/control/x.  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@smarden.org>

                                                                                                        runsv(8)