.TH INVOKE-RUN 8 "Aug 29, 2022" "" "GNU/Linux System Adminstrator's manual"
.SH NAME
invoke-run \- runscript interpreter
.SH SYNOPSIS
.B /usr/bin/env /lib/run/invoke-run
.SH DESCRIPTION
The
.B runit
supervision system uses scripts, called
.I runscripts
to start and supervise services. By convention, a runscript for a service
.I foo
is located at
.BI "/etc/sv/" foo "/run"
: runscript can be any executable file.
.PP
Debhelper addon
.I dh_runit
installs the runscript according to this convention.
.PP
To use the
.B invoke-run
interpreter, the runscript
.BI "/etc/sv/" foo "/run"
for a service
.I foo
must begin with following line:
.PP
.IP "" 4
.EX
#!/usr/bin/env /lib/runit/invoke-run
.EE
.PP
If the script
.BI /usr/sbin/policy-rc.d
exists the policy layer is checked (see below).
If the init.d script
.BI /etc/init.d/ foo
exists, is executable and is not a symlink, it is invoked with the
.B stop
argument to gracefully replace the Sysv instance with the runit managed instance . After that,
the runscript is interpreted with
.I /bin/sh
shell and some additional environment variables are set according to the following rules:
.IP "" 4
If file
.BI /etc/default/ foo
exists, it is interpreted with
.I /bin/sh
and all variable assignment are accessible to runscript.
.PP
.IP "" 4
If directory
.BI "/etc/sv/" foo "/env"
exists, variables are set according to rules, documented
in
.I envdir
section of
.BR chpst (8)
manual.
.PP
If both
.BI /etc/default/ foo
file and
.BI "/etc/sv/" foo "/env"
directory define some variable, value from directory takes precedence.
.IP "" 4
Older versions of invoke-run exported a
.BI NAME= foo
variable and included the
.BI /etc/default/runit
file; the shell expansion
.BI ${PWD##*/}
can be used in place of
.BI NAME
inside the run and finish files;
.BI /etc/runit/verbose
and
.BI /etc/runit/debug
flags files can be used in place of variables inside
.BI /etc/runit/default
.PP
.SH SPECIAL ERROR CODE
Looking in the
.I foo
service log it's possible to see messages in the form of
.IP "" 2
invoke-run: ERROR [NNN] in foo: reason for the error
.PP
These messages don't come from runsv itself but from
.B invoke-run,
the run file or the finish file. The purpose of these message
is to detail a permanent failure condition that prevents
.I foo
service from being up.
For each
.I foo
service, defined errors and messages are:
.IP "" 2
.B invoke-run: foo binary not installed
.PP
.IP "" 4
this happens when the package containing
.I foo
binary has been removed, but not purged.
.PP
.IP "" 2
.B invoke-run: ERROR -1 in foo: runscript didn't exit normally
.PP
.IP "" 4
this message comes from the finish file, but the exit code comes from
.BR runsv (8)
and is documented in its manpage.
.PP
.IP "" 2
.B invoke-run: WARNING for foo: disabled by local settings
.PP
.IP "" 4
Some service specific setting prevent
.I foo
from starting; it's likely something in
.BI /etc/default/foo
.PP
.IP "" 2
.B invoke-run: ERROR 162 in foo: configtest or early setup failed
.PP
.IP "" 4
A configuration file of
.I foo
is malformed and the configtest failed;
.I foo
log may contain additional info from the test itself.
Alternatively the runscript has failed to do some setup that is essential to the
.I foo
service.
.PP
.IP "" 2
.B invoke-run: ERROR 170 in foo: a runtime hard dependency is missing
.PP
.IP "" 4
A dependency failed the check and can't be bring up; to know dependencies of
.I foo
service look for "sv start" in "run" script.
.PP
.SH FINISH FILE AND FINISH-DEFAULT
Since version 2.1.2-48 the Debian runit package ships a
.BI /lib/runit/finish-exec
file that contains 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

.EX
 $ cat /etc/sv/foo/finish
#!/bin/sh
set -e

exec /lib/runit/finish-exec "$@"
.EE

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 section. If the file
.BI /etc/runit/verbose
exists, a 'foo stopped' message is printed; if the file
.BI /etc/runit/debug
exists, run's exit code is also printed.
The finish-default shipped by previous runit package is now deprecated and scheduled
removal in the near future.
.SH POLICY-RC.D LAYER
Since version 2.1.2-41
.BI invoke-run
support the
.BI policy-rc.d
hack. When the
.BI /usr/sbin/policy-rc.d
script exists, for each service
.BI invoke-run
calls
.B '/usr/sbin/policy-rc.d service'
and check the return code.
On
.BI 101
it sets the wanted status for the service as down and exits immediately.
Any other return code is ignored and
.BI invoke-run
will proceed with starting the service.
The main use case for the
.BI 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
.BI 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.

.SH SEE ALSO
.BR runsvdir (8),
.BR dh_runit (1),
.BR chpst (8)