# INVOKE-RUN - runscript interpreter - man(8) - [phpMan] [_INVOKE-RUN_(8)](https://www.chedong.com/phpMan.php/man/INVOKE-RUN/8/markdown) GNU/Linux System Adminstrator's manual [_INVOKE-RUN_(8)](https://www.chedong.com/phpMan.php/man/INVOKE-RUN/8/markdown) ## 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)](https://www.chedong.com/phpMan.php/man/chpst/8/markdown) 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)](https://www.chedong.com/phpMan.php/man/runsv/8/markdown) 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)](https://www.chedong.com/phpMan.php/man/runsvdir/8/markdown), [**dh_runit**(1)](https://www.chedong.com/phpMan.php/man/dhrunit/1/markdown), [**chpst**(8)](https://www.chedong.com/phpMan.php/man/chpst/8/markdown) Aug 29, 2022 [_INVOKE-RUN_(8)](https://www.chedong.com/phpMan.php/man/INVOKE-RUN/8/markdown)