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 and supervise services. By convention, a runscript for a service foo is located at /etc/sv/foo/run or at /usr/share/runit/sv.current/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 for a service foo must begin with following line:

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

If a file /.meta/bin is found inside the foo service directory, the path inside the bin file is tested for existence and if not found on the system, the service foo is stopped. The bin file should contain only one line with the full path of the binary that is executed in the runscript.

When invoke-run(8) is run with uid=0, 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 .

If the file /etc/runit/verbose exists, the message invoke-run: starting foo is printed. 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/sv/foo/conf or /etc/default/foo exists, it is interpreted with /bin/sh and all variable assignment are accessible to runscript; in case both files exist only /etc/sv/foo/conf is used.

    If directory /etc/sv/foo/env exists, variables are set according to rules, documented in envdir section of chpst(8) manual.

If both /etc/sv/foo/conf or /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/default/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

USER SERVICES
When a runscript is run with uid >= 1000 and a home directory for that user exists the script is considered a user-service and invoke-run(8) performs the following extra action:

    if an env directory is found either in /etc/sv/runsvdir@username/ or in foo/ service directory, it's used to set variables with chpst's envdir; if both directories are found, both are used; when a variable is set in both dirs, the service's directory takes precedence.

HARDENING WITH XCHPST
When /usr/bin/xchpst exist and a /etc/sv/foo/xchopts file is found, the XCHPST="xchpst--filefoo/xchopts" variable is available to the runscript; the xchopts file syntax is documented in xchpst(8).

The following example uses xchpst when available, otherwise no hardening is applied:
     $ cat /etc/sv/foo/run
    #!/usr/bin/env /lib/runit/invoke-run
    exec 2>&1
    exec ${XCHPST:-} /usr/sbin/foo
the following example uses xchpst when available and runit's chpst as a fallback;
     $ cat /etc/sv/bar/run
    #!/usr/bin/env /lib/runit/invoke-run
    exec 2>&1
    exec exec ${XCHPST:-chpst -ubar} /usr/sbin/bar

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) 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-EXEC
Since version 2.1.2-48 the Debian runit package ships a /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
     $ 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 section. 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 previous runit package is now deprecated and scheduled removal in the near future.

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