invoke-rc.d(8)

📦
version 1.69 · 4 versions
, in ubuntu resolute, ubuntu stonking

💅 invoke-rc.d — a Gen Z field guide 💅

okay so this is the invoke-rc.d page from the Debian GNU/Linux manual section 8 (that's the "admin commands" section, iykyk). buckle up bestie, because this little script runner is lowkey the main character of Debian's service management and you're gonna learn every single thing about it 🫶

✨ SYNOPSIS ✨

invoke-rc.d [--quiet] [--force] [--try-anyway] [--disclose-deny]
[--query] [--no-fallback] name action [init script parameters...]

invoke-rc.d [--help]

🌸 DESCRIPTION 🌸

so invoke-rc.d is basically a generic interface (a lil middle-man, a vibe coordinator, if you will) that executes System V style init script actions — you know, /etc/init.d/name — while obeying runlevel constraints and any local policies your sysadmin has set up. it does not just rawdog the script. it checks first. very responsible. 💅

literally all access to init scripts done by Debian packages' maintainer scripts should go through invoke-rc.d. all of it. no exceptions. that's the rule, periodt.

this manpage documents only the usage and behavior of invoke-rc.d. for a whole discussion of the System V style init script arrangements, please see init(8). and if you want even more info on invoke-rc.d, it lives in the section on runlevels and init.d scripts of the Debian Policy Manual. slay 📚

🎀 INIT SCRIPT ACTIONS 🎀

the standard actions are: start, stop, force-stop, restart, try-restart, reload, force-reload, and status. those are the canon ones, the iconique ones ✨

other actions are accepted, but they can cause problems to policy-rc.d (peep the INIT SCRIPT POLICY section below) — so warnings get generated if the policy layer is active. it's giving "we'll allow it but we're judging you a little" 🙈

please note that not all init scripts will implement all the actions listed above, and that the policy layer may override an action to another action(s), or even deny it entirely. so like. manage your expectations bestie 😭

any extra parameters will be passed to the init script(s) being executed. they go straight through, no notes.

if an action must be carried out regardless of any local policies, use the --force switch. (but read the warning below first. i'm serious. 👀)

💖 OPTIONS 💖

  • --help — displays usage help. the classic. the goat.
  • --quiet — quiet mode, no error messages are generated. shhh 🤫
  • --force — tries to run the init script regardless of policy and init script subsystem errors. use of this option in Debian maintainer scripts is severely discouraged. like, severely. don't do it. i'm begging 🙏
  • --try-anyway — tries to run the init script if a non-fatal error is detected. a lil "eh, let's see what happens" energy.
  • --disclose-deny — returns status code 101 instead of status code 0 if the init script action is denied by the policy layer. being honest about being told no 💀
  • --query — returns one of the status codes 100-106. does not run the init script, and implies --disclose-deny and --no-fallback. purely vibes-checking, no action taken.
  • --no-fallback — ignores any fallback action requests by the policy layer. > warning: this is usually a very bad idea for any actions other than start. like genuinely. do not.
  • --skip-systemd-native — exits before doing anything if a systemd environment is detected and the requested service is a native systemd unit. this is useful for maintainer scripts that want to defer systemd actions to deb-systemd-invoke(1p). teamwork makes the dream work 🫶

🦋 STATUS CODES 🦋

should an init script be executed, invoke-rc.d always returns the status code returned by the init script. init scripts should not return status codes in the 100+ range (which is reserved in Debian and by the LSB). so don't. 🔥

the status codes returned by invoke-rc.d proper are:

  • 0 — Success. either the init script was run and returned exit status 0 (note that a fallback action may have been run instead of the one given in the command line), or it was not run because of runlevel/local policy constrains and --disclose-deny is not in effect.
  • 1 - 99 — reserved for init.d script, usually indicates a failure. 😭
  • 100 — init script ID (name) unknown. this means the init script was not registered successfully through update-rc.d or that the init script does not exist. she's not on the guest list.
  • 101 — action not allowed. the requested action will not be performed because of runlevel or local policy constraints. denied, bestie 💅
  • 102 — subsystem error. init script (or policy layer) subsystem malfunction. also, forced init script execution due to --try-anyway or --force failed. 💀
  • 103 — syntax error.
  • 104 — action allowed. init script would be run, but --query is in effect. so close, yet so far.
  • 105 — behavior uncertain. it cannot be determined if action should be carried out or not, and --query is in effect. the vibe check was inconclusive 🙈
  • 106 — fallback action requested. the policy layer denied the requested action, and supplied an allowed fallback action to be used instead. the plot twist ✨

🌈 INIT SCRIPT POLICY 🌈

invoke-rc.d introduces the concept of a policy layer — a whole extra check-y bestie used to verify if an init script should be run or not, or if something else should be done instead. this layer has various uses, the most immediate ones being:

  • avoiding that package upgrades start daemons out-of-runlevel 👑
  • and that a package starts or stops daemons while inside a chroot jail. (jail. literally. no cap.)

the policy layer has the following abilities:

  • deny or approve the execution of an action;
  • request that another action (called a fallback) is to be taken, instead of the action requested in invoke-rc.d's command line;
  • or request multiple actions to be tried in order, until one of them succeeds (a multiple fallback). 🔥

invoke-rc.d itself only pays attention to the current runlevel — it will block any attempts to start a service in a runlevel in which the service is disabled. other policies are implemented with the use of the policy-rc.d helper, and are only available if /usr/sbin/policy-rc.d is installed in the system. no helper, no extra policies. simple as that.

🍓 FILES 🍓

  • /etc/init.d/* — System V init scripts.
  • /usr/sbin/policy-rc.d — init script policy layer helper (not required). optional icon.
  • /etc/rc?.d/* — System V runlevel configuration.

⭐ NOTES ⭐

invoke-rc.d special cases the status action, and returns exit status 4 instead of exit status 0 when it is denied. that's it. that's the note. 😌

💀 BUGS 💀

see <http://bugs.debian.org/sysv-rc> and <http://bugs.debian.org/init-system-helpers>. go report the bugs, bestie, they want to hear from you 🫶

🔥 SEE ALSO 🔥

  • Debian Policy manual
  • /etc/init.d/skeleton
  • update-rc.d(8)
  • init(8)
  • /usr/share/doc/init-system-helpers/README.policy-rc.d.gz

👑 AUTHOR 👑

Henrique de Moraes Holschuh

License: GNU General Public License v2 or Later (GPLv2+) 📜

2001 Henrique de Moraes Holschuh

and that's the whole page babes 💖 this was version-1-March-2001 energy — written by Henrique de Moraes Holschuh, dated 1 March 2001, filed under invoke-rc.d(8) in the fine Debian GNU/Linux manual. go forth and never call an init script directly ever again, mwah 😘💅

📦 where this page comes from