phpMan > info > 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 ex-
       its  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  immedi-
       ately.  The control interface (see below) can be used to start the ser-
       vice 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  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' supervise  program)  in  service/supervise/status  and
       service/log/supervise/status,  and  in  a human-readable format in ser-
       vice/supervise/stat, service/log/supervise/stat, service/supervise/pid,
       service/log/supervise/pid.

CONTROL
       The   named  pipes  service/supervise/control,  and  (optionally)  ser-
       vice/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  ex-
              ists.  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  sig-
              nal.

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

       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 in-
              put 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 ser-
       vice/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 AT smarden.org>

                                                                      runsv(8)