{ "mode": "man", "parameter": "invoke-run", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/invoke-run/8/json", "generated": "2026-10-04T13:55:12Z", "synopsis": "", "sections": { "NAME": { "content": "invoke-run - runscript interpreter\n", "subsections": [] }, "SYNOPSIS": { "content": "", "subsections": [ { "name": "/usr/bin/env /lib/run/invoke-run", "content": "" } ] }, "DESCRIPTION": { "content": "The runit supervision system uses scripts, called runscripts to start and supervise services.\nBy convention, a runscript for a service foo is located at /etc/sv/foo/run : runscript can be\nany executable file.\n\nDebhelper addon dhrunit installs the runscript according to this convention.\n\nTo use the invoke-run interpreter, the runscript /etc/sv/foo/run for a service foo must begin\nwith following line:\n\n\n#!/usr/bin/env /lib/runit/invoke-run\n\nIf the script /usr/sbin/policy-rc.d exists the policy layer is checked (see below). If the\ninit.d script /etc/init.d/foo exists, is executable and is not a symlink, it is invoked with\nthe stop argument to gracefully replace the Sysv instance with the runit managed instance .\nAfter that, the runscript is interpreted with /bin/sh shell and some additional environment\nvariables are set according to the following rules:\n\nIf file /etc/default/foo exists, it is interpreted with /bin/sh and all variable assign‐\nment are accessible to runscript.\n\nIf directory /etc/sv/foo/env exists, variables are set according to rules, documented in\nenvdir section of chpst(8) manual.\n\nIf both /etc/default/foo file and /etc/sv/foo/env directory define some variable, value from\ndirectory takes precedence.\n\nOlder versions of invoke-run exported a NAME=foo variable and included the /etc/de‐\nfault/runit file; the shell expansion ${PWD##*/} can be used in place of NAME inside the\nrun and finish files; /etc/runit/verbose and /etc/runit/debug flags files can be used in\nplace of variables inside /etc/runit/default\n", "subsections": [] }, "SPECIAL ERROR CODE": { "content": "Looking in the foo service log it's possible to see messages in the form of\n\ninvoke-run: ERROR [NNN] in foo: reason for the error\n\nThese messages don't come from runsv itself but from invoke-run, the run file or the finish\nfile. The purpose of these message is to detail a permanent failure condition that prevents\nfoo service from being up. For each foo service, defined errors and messages are:\n\ninvoke-run: foo binary not installed\n\nthis happens when the package containing foo binary has been removed, but not purged.\n\ninvoke-run: ERROR -1 in foo: runscript didn't exit normally\n\nthis message comes from the finish file, but the exit code comes from runsv(8) and is\ndocumented in its manpage.\n\ninvoke-run: WARNING for foo: disabled by local settings\n\nSome service specific setting prevent foo from starting; it's likely something in\n/etc/default/foo\n\ninvoke-run: ERROR 162 in foo: configtest or early setup failed\n\nA configuration file of foo is malformed and the configtest failed; foo log may contain\nadditional info from the test itself. Alternatively the runscript has failed to do some\nsetup that is essential to the foo service.\n\ninvoke-run: ERROR 170 in foo: a runtime hard dependency is missing\n\nA dependency failed the check and can't be bring up; to know dependencies of foo service\nlook for \"sv start\" in \"run\" script.\n", "subsections": [] }, "FINISH FILE AND FINISH-DEFAULT": { "content": "Since version 2.1.2-48 the Debian runit package ships a /lib/runit/finish-exec file that con‐\ntains code that can be shared across different services. This file can be symlinked inside\nthe service directory, or can be exec'd like in the following example\n\n$ cat /etc/sv/foo/finish\n#!/bin/sh\nset -e\n\nexec /lib/runit/finish-exec \"$@\"\n\nServices that need to put specific code into the finish file should do before the line that\nexec finish-exec. Finish-exec defines special error codes as described in the previous sec‐\ntion. If the file /etc/runit/verbose exists, a 'foo stopped' message is printed; if the file\n/etc/runit/debug exists, run's exit code is also printed. The finish-default shipped by pre‐\nvious runit package is now deprecated and scheduled removal in the near future.\n\nPOLICY-RC.D LAYER\nSince version 2.1.2-41 invoke-run support the policy-rc.d hack. When the /usr/sbin/policy-\nrc.d script exists, for each service invoke-run calls '/usr/sbin/policy-rc.d service' and\ncheck the return code. On 101 it sets the wanted status for the service as down and exits\nimmediately. Any other return code is ignored and invoke-run will proceed with starting the\nservice. The main use case for the policy-rc.d hack is for the Debian Installer to prevent\nservices to start in chroot during the installation process; however in the past the hack was\nused also by local admins to perform custom actions. Local admin that want to use the policy-\nrc.d layer should be aware that with runit the hack prevents the service to start under any\ncondition, including during the boot sequence. This is different from other init systems\nlike systemd or sysv, where the hack only prevents services to start when invoked via\nmaintscripts.\n\n", "subsections": [] }, "SEE ALSO": { "content": "runsvdir(8), dhrunit(1), chpst(8)\n\n\nAug 29, 2022 INVOKE-RUN(8)", "subsections": [] } }, "summary": "invoke-run - runscript interpreter", "flags": [], "examples": [], "see_also": [ { "name": "runsvdir", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/runsvdir/8/json" }, { "name": "dhrunit", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/dhrunit/1/json" }, { "name": "chpst", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/chpst/8/json" }, { "name": "INVOKE-RUN", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/INVOKE-RUN/8/json" } ] }