{
    "content": [
        {
            "type": "text",
            "text": "# invoke-run(8) (man)\n\n**Summary:** invoke-run - runscript interpreter\n\n## See Also\n\n- runsvdir(8)\n- dhrunit(1)\n- chpst(8)\n- INVOKE-RUN(8)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (1 lines) — 1 subsections\n  - /usr/bin/env /lib/run/invoke-run (1 lines)\n- **DESCRIPTION** (33 lines)\n- **SPECIAL ERROR CODE** (33 lines)\n- **FINISH FILE AND FINISH-DEFAULT** (15 lines) — 1 subsections\n  - POLICY-RC.D LAYER (13 lines)\n- **SEE ALSO** (6 lines)\n\n## Full Content\n\n### NAME\n\ninvoke-run - runscript interpreter\n\n### SYNOPSIS\n\n#### /usr/bin/env /lib/run/invoke-run\n\n### DESCRIPTION\n\nThe  runit  supervision  system uses scripts, called runscripts to start services. By conven‐\ntion, runscript for a service foo is located at /etc/sv/foo/run\n\nDebhelper addon dhrunit installs runscript according this convention.\n\nRunscript can be any executable file. Runscript can use invoke-run interpreter only if it  is\ninstalled according convention,\n\nTo use invoke-run interpreter, runscript /etc/sv/foo/run for service foo must begin with fol‐\nlowing 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\ninit.d  script  /etc/init.d/foo exists, it is invoked with stop argument to gracefully handle\npackage upgrade to version, introducing runscript. After that, /bin/sh shell  interpret  rest\nof runscript, with some additional environment set according following rules:\n\nA NAME=foo variable is exported.\n\nThe  /etc/default/runit  file is interpreted with /bin/sh and all variable assignment are\naccessible to runscript.\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/conf 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/conf directory define some variable, value from\ndirectory takes precedence.\n\n### SPECIAL ERROR CODE\n\nLooking 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, possible 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\n### FINISH FILE AND FINISH-DEFAULT\n\nSince version 2.1.2-36 the Debian runit package ships a /lib/runit/finish-default  file  that\ncontains  code that can be shared across different services.  This file can be sourced inside\nthe regular finish file of a service, like the following example\n\n$ cat /etc/sv/foo/finish\n#!/bin/sh\nset -e\n. /lib/runit/finish-default \"$@\"\n\nServices that need to put specific code into the finish file should do after  the  line  that\nsources finish-default. For each foo service, finish-default file sources /etc/default/runit,\nexport a NAME=foo variable and defines special error codes as described in the previous  sec‐\ntion.   Also,  when  VERBOSE mode is on, EXIT is trapped so that a 'foo stopped' message gets\nprinted at the very end of the finish file.\n\n#### POLICY-RC.D LAYER\n\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### SEE ALSO\n\nrunsvdir(8), dhrunit(1), chpst(8)\n\n\n\n\nJan 21, 2019                               INVOKE-RUN(8)\n\n"
        }
    ],
    "structuredContent": {
        "command": "invoke-run",
        "section": "8",
        "mode": "man",
        "summary": "invoke-run - runscript interpreter",
        "synopsis": "",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "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"
            }
        ],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "/usr/bin/env /lib/run/invoke-run",
                        "lines": 1
                    }
                ]
            },
            {
                "name": "DESCRIPTION",
                "lines": 33,
                "subsections": []
            },
            {
                "name": "SPECIAL ERROR CODE",
                "lines": 33,
                "subsections": []
            },
            {
                "name": "FINISH FILE AND FINISH-DEFAULT",
                "lines": 15,
                "subsections": [
                    {
                        "name": "POLICY-RC.D LAYER",
                        "lines": 13
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 6,
                "subsections": []
            }
        ]
    }
}