invoke-run(8) - man - phpman

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 services. By conven‐
       tion, runscript for a service foo is located at /etc/sv/foo/run

       Debhelper addon dh_runit installs runscript according this convention.

       Runscript can be any executable file. Runscript can use invoke-run interpreter only if it  is
       installed according convention,

       To use invoke-run interpreter, runscript /etc/sv/foo/run for service foo must begin with fol‐
       lowing 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
       init.d  script  /etc/init.d/foo exists, it is invoked with stop argument to gracefully handle
       package upgrade to version, introducing runscript. After that, /bin/sh shell  interpret  rest
       of runscript, with some additional environment set according following rules:

           A NAME=foo variable is exported.

           The  /etc/default/runit  file is interpreted with /bin/sh and all variable assignment are
           accessible to runscript.

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

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, possible 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-36 the Debian runit package ships a /lib/runit/finish-default  file  that
       contains  code that can be shared across different services.  This file can be sourced inside
       the regular finish file of a service, like the following example

        $ cat /etc/sv/foo/finish
        #!/bin/sh
        set -e
        . /lib/runit/finish-default "$@"

       Services that need to put specific code into the finish file should do after  the  line  that
       sources finish-default. For each foo service, finish-default file sources /etc/default/runit,
       export a NAME=foo variable and defines special error codes as described in the previous  sec‐
       tion.   Also,  when  VERBOSE mode is on, EXIT is trapped so that a 'foo stopped' message gets
       printed at the very end of the finish file.

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)




                                            Jan 21, 2019                               INVOKE-RUN(8)