Ubuntu Manpage: invoke-run - runscript interpreter

Provided by: runit_2.1.2-48ubuntu1_amd64

NAME

       invoke-run - runscript interpreter

SYNOPSIS

       /usr/bin/env /lib/run/invoke-run

DESCRIPTION

The runit supervision system uses scripts, called runscripts to start and supervise
services. By convention, a runscript for a service foo is located at /etc/sv/foo/run :
runscript can be any executable file.

Debhelper addon dh_runit installs the runscript according to this convention.

To use the invoke-run interpreter, the runscript /etc/sv/foo/run for a service foo must
begin with following line:

#!/usr/bin/env /lib/runit/invoke-run

If the script /usr/sbin/policy-rc.d exists the policy layer is checked (see below). If
the init.d script /etc/init.d/foo exists, is executable and is not a symlink, it is
invoked with the stop argument to gracefully replace the Sysv instance with the runit
managed instance . After that, the runscript is interpreted with /bin/sh shell and some
additional environment variables are set according to the following rules:

If file /etc/default/foo exists, it is interpreted with /bin/sh and all variable
assignment are accessible to runscript.

If directory /etc/sv/foo/conf exists, variables are set according to rules, documented
in envdir section of chpst(8) manual.

If both /etc/default/foo file and /etc/sv/foo/conf directory define some variable, value
from directory takes precedence.

A NAME=foo variable is exported; the /etc/default/runit file is interpreted with
/bin/sh and all variable assignment are accessible to runscript. NAME and
/etc/runit/default are deprecated and will be removed in the near future. The shell
expansion ${PWD##*/} can be used in place of NAME inside the run and finish files;
/etc/runit/verbose and /etc/runit/debug flags files are used in place of variables
inside /etc/runit/default

SPECIAL ERROR CODE

       Looking in the foo service log it's possible to see messages in the form of

         invoke-run: ERROR [NNN] in foo: reason for the error

       These messages don't come from runsv itself but from  invoke-run,  the  run  file  or  the
       finish  file. The purpose of these message is to detail a permanent failure condition that
       prevents foo service from being up.  For each foo service,  defined  errors  and  messages
       are:

         invoke-run: foo binary not installed

           this happens when the package containing foo binary has been removed, but not purged.

         invoke-run: ERROR -1 in foo: runscript didn't exit normally

           this  message comes from the finish file, but the exit code comes from runsv(8) and is
           documented in its manpage.

         invoke-run: WARNING for foo: disabled by local settings

           Some service specific setting prevent foo from  starting;  it's  likely  something  in
           /etc/default/foo

         invoke-run: ERROR 162 in foo: configtest or early setup failed

           A  configuration  file  of  foo  is  malformed  and the configtest failed; foo log may
           contain additional info from the test itself.  Alternatively the runscript has  failed
           to do some setup that is essential to the foo service.

         invoke-run: ERROR 170 in foo: a runtime hard dependency is missing

           A  dependency  failed  the  check  and  can't be bring up; to know dependencies of foo
           service look for "sv start" in "run" script.

FINISH FILE AND FINISH-DEFAULT

       Since version 2.1.2-48 the Debian runit package ships a /lib/runit/finish-exec  file  that
       contains  code  that  can be shared across different services.  This file can be symlinked
       inside the service directory, or can be exec'd like in the following example

        $ cat /etc/sv/foo/finish
       #!/bin/sh
       set -e

       exec /lib/runit/finish-exec "$@"

       Services that need to put specific code into the finish file should  do  before  the  line
       that  exec  finish-exec.  Finish-exec  defines  special  error  codes  as described in the
       previous section. If the file  /etc/runit/verbose  exists,  a  'foo  stopped'  message  is
       printed;  if  the  file  /etc/runit/debug  exists,  run's  exit code is also printed.  The
       finish-default shipped by previous runit package is now deprecated and  scheduled  removal
       in the near future.

POLICY-RC.D LAYER