# invoke-run(8) - man - 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 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)](https://www.chedong.com/phpMan.php/man/chpst/8/markdown) 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)](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-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)](https://www.chedong.com/phpMan.php/man/runsvdir/8/markdown), **dh**___**[runit**(1)](https://www.chedong.com/phpMan.php/man/runit/1/markdown), [**chpst**(8)](https://www.chedong.com/phpMan.php/man/chpst/8/markdown) Jan 21, 2019 [INVOKE-RUN(8)](https://www.chedong.com/phpMan.php/man/INVOKE-RUN/8/markdown)