man > invoke-run(8)

INVOKE-RUN(8)                  GNU/Linux System Adminstrator's manual                  INVOKE-RUN(8)

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 assign‐
           ment 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/de‐
           fault/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 con‐
       tains 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  sec‐
       tion.  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 pre‐
       vious 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)