---
name: "invoke-run"
section: "8"
platform: "linux"
package: "runit"
version: "2.2.0-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/invoke-run"
---

# invoke-run(8)

runscript interpreter

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

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/default/***foo* exists, it is interpreted with */bin/sh* and all variable assignment are accessible to runscript.

-

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

If both **/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**

## 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)](/runsv/8.md) 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)](/runsvdir/8.md), [**dh\_runit**(1)](/dh_runit/1.md), [**chpst**(8)](/chpst/8.md)