Provided by: runit_2.1.2-54ubuntu1_amd64 bug

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/env 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/env 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

       Since version 2.1.2-41 invoke-run support the policy-rc.d hack. When the /usr/sbin/policy-
       rc.d script exists, for each service invoke-run calls '/usr/sbin/policy-rc.d service'  and
       check the return code.  On 101 it sets the wanted status for the service as down and exits
       immediately.  Any other return code is ignored and invoke-run will proceed  with  starting
       the  service.   The  main use case for the policy-rc.d hack is for the Debian Installer to
       prevent services to start in chroot during the installation process; however in  the  past
       the hack was used also by local admins to perform custom actions. Local admin that want to
       use the policy-rc.d layer should be aware that with runit the hack prevents the service to
       start  under  any  condition,  including during the boot sequence.  This is different from
       other init systems like systemd or sysv, where the hack only prevents  services  to  start
       when invoked via maintscripts.

SEE ALSO

       runsvdir(8), dh_runit(1), chpst(8)

                                           Aug 29, 2022                             INVOKE-RUN(8)