On Apache
Under GNU General Public License
2025-11-21 16:46 @216.73.216.57 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
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
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
init.d script /etc/init.d/foo exists, it is invoked with stop argument to gracefully han-
dle 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 as-
signment 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 fin-
ish 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 con-
tain 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 ser-
vice 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/de-
fault/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.
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)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2025-11-21 16:46 @216.73.216.57 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)