DOKK / manpages / debian 11 / runit / invoke-run.8.en
INVOKE-RUN(8) GNU/Linux System Adminstrator's manual INVOKE-RUN(8)

invoke-run - runscript interpreter

/usr/bin/env /lib/run/invoke-run

The runit supervision system uses scripts, called runscripts to start services. By convention, 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 following line:

#!/usr/bin/env /lib/runit/invoke-run

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

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.

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

runsvdir(8), dh_runit(1), chpst(8)

January 21, 2019