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.

           Older  versions  of invoke-run exported a NAME=foo variable and included the /etc/default/runit file;
           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  can  be  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)