DH_RUNIT(1)

📦

version 2.16.7ubuntu2 · 7 versions

2.16.7ubuntu2 · ubuntu stonking (latest)
2.16.4ubuntu1 · ubuntu questing
2.10.3ubuntu3 · ubuntu jammy
2.15.2 · debian bookworm
2.16.2ubuntu1 · ubuntu noble
2.16.6ubuntu1 · ubuntu resolute
2.16.4 · debian trixie

💖 DH_RUNIT(1) — the girlies' guide to runit runscripts 💖

okay so. hi bestie 🫶 you're looking at the manual page for DH_RUNIT, section 1 of the user-contributed Perl docs, and honestly? it's giving service supervision but make it cute. let's get into it ✨

✨ NAME ✨

dh_runit — install/enable runit runscripts. that's it, that's the whole vibe 💅

🌸 SYNOPSIS 🌸

dh_runit [debhelper options] [path options] ...

🦋 DESCRIPTION 🦋

dh_runit is a debhelper program, and its whole job — its main character energy — is installing and enabling runit runscripts. If there's a file named debian/package.runit sitting there, bestie, dh_runit will make sure the right stuff happens based on what's inside it. no cap. 💅

so here's the lore for runit: every unit of supervision (or, in normal-people words, every program) gets its own directory under /etc/sv, and that directory has to contain at least a run executable file. every unit that's enabled shows up as a symbolic link under /etc/services — and plot twist, /etc/services is itself a symbolic link pointing at /etc/runit/runsvdir/default — and that symlink points to some directory under /etc/sv. it's links all the way down, iykyk 🎀

dh_runit reads its arguments from the command line and from debian/package.runit, in pairs — first item is the path to a file or directory, second item is a set of options. it's a two-piece, periodt.

if that first argument names a file, it's treated as a run script that gets installed at /etc/sv/*/run as an executable file. ✨
if that first argument names a directory, the whole directory gets copied over to /etc/sv. as a treat. 🫶

options are comma separated, like mount options. and bestie, if it's an unrecognized option, that's an error — we do not freestyle here. the following options are recognized 👑

✨ the recognized options ✨

disable — installs the runscript but does not enable it by default. meaning: the corresponding service will not be started. the system administrator can enable it later by hand, or with update-service(8). lowkey chill of you.
name=preferred-name — by default, the name of the directory under /etc/sv for a given runscript is just the basename of the path argument that names it. this option lets you override that default with a directory name you picked on purpose. aesthetic choice, iconic 💅
logscript — installs a standard log/run script that invokes svlogd(8) with the rights of the dedicated user. ⚠️ but heads up: if you specify this option and the path argument names a directory that already contains a /log/run script, that produces an error. no duplicates, we don't do that here.
onupgrade=string — this one controls the debhelper action performed during the upgrade of the service, when runit is PID 1. it takes one of the following strings as its argument:
- restart — restart the service in postinstall, after all files of the package are unpacked and the upgrade is complete. this is the same as dh_installinit or dh_installsystemd '--restart-after-upgrade'. this is the implicit default if the onupgrade option is not set. 👑
- stop — stop the service in prerm and start again in postinst. useful if the daemon gets confused by the package being upgraded while it's still running. 😭 this is the same as dh_installinit or dh_installsystemd '--no-restart-after-upgrade'. by design, stop is not compatible with the bin option.
- nostop — do not stop service on upgrade. side-effect: it also doesn't restart the service as a part of the upgrade. use this when the service does not support being restarted while it's running. display managers (xdm, slim, ...) are examples of non-restartable services. when this option is set, the invoke-run interpreter, provided by the runit package, will refrain from automatically replacing the sysvinit-managed instance of the service with a runit-managed instance (replacement requires manual intervention or a system restart 🫠). this is the same as dh_installinit or dh_installsystemd '--no-stop-on-upgrade'.
- reload — similar to nostop, but the service configuration is reloaded (HUP) during the upgrade. might be useful in cases (like dbus) where the service does not support restarting on upgrade and where reloading the config instead of restarting makes sense. when this option is set, the invoke-run interpreter, provided by the runit package, will refrain from automatically replacing the sysvinit-managed instance of the service with a runit-managed instance (replacement requires manual intervention or a system restart).

also important, bestie: the onupgrade option does not control whether the service will be started after the first install of the package. by default the service is always started if it's enabled (and stopped before removal). if you don't want the service started after the first install, use the disable option instead. the upgrade action usually happens in postinst, but if the bin option is used, the action is performed at the end of the upgrade process, with a noawait trigger on runit's package side. 🎀

noscripts — with this option, dh-runit will not add its snippets to maintscripts. so actions like enable or disable, start, stop, restart and purge the service need manual editing of maintainer scripts. DIY queen 👑
usr — with this option, dh-runit will install the service directory under /usr/share/runit/sv/ instead of the default /etc/sv/. it must be used together with the bin option, or dh-runit will exit with an error. 🚨 this option is experimental, is mainly intended for a catch-all runscript package, and may produce a buggy package (that fails the piuparts purge test). you've been warned, don't come for me 💀
finish — installs a standard finish file with the service; if there's already a finish file inside the service directory, this option does nothing. no notes.
bin=/full/path/to/bin — you should provide the full path to the binary that is exec'd in the runscript. when this option is used, additional metafiles are written inside the service directory so that postinstall and prerm actions that are usually performed inside maintainer scripts are performed with a trigger on runit package side. when this option is used, only the postrm snippet that handles purge action is written, while postinst and prerm snippets are skipped. additionally, all instances (if any) of '##bin##' in the runscript are automatically replaced with the path provided with this option — this is done so that the path of the bin can be maintained only in the control file. 🪄 this option is experimental. (and remember: stop can't hang with it, from way up there 👆)
presubj — include a presubj file for reportbug into the generated package. this file contains a note that suggests including runit maintainers into the copy of bug reports related to runit integration. 💌 if the package already includes its own presubj file, that file takes precedence over the runit presubj file. this may make life easier for a package maintainer who uses another init system. so thoughtful 🥺
defaults — if you don't need other options, just specify this one. simple as. ✨
since — since dh-runit 2.8.15 this option is no longer needed and is deprecated. it's retained only for backward compatibility with packages that still use it (see #942323). it's scheduled for removal with the 3.0 release. ⏳
noreplace — since dh-runit 2.9.0 this option is deprecated and it's retained only for backward compatibility, and it's scheduled for removal with the 3.0 release. you can use onupgrade=nostop instead. glow-up advice 💅
nofinish — this option is deprecated, does nothing, and it's scheduled for removal with the 3.0 release. it's giving ghost of options past 👻

🌈 SUBSTITUTION VARIABLES 🌈

packages using dh_runit do not depend on runit, but they should include the runit:Breaks variable in their Breaks field in debian/control, to ensure that no breakages are caused by a too-old version of the runit package. protect the vibe check 🫶

🍓 EXAMPLES 🍓

this section contains several example package.runit snippets. slay:

# In this case, a file is installed as a 'run' script. The directory
# name under /etc/sv is derived from the file's basename (/etc/sv/script).
path/to/file/to/be/installed/as/run/script defaults

# Similar, but installs a directory as a whole. It is the package's
# responsibility to ensure this directory contains everything required.
path/to/directory defaults

# Similar, but without creating a symlink under /etc/service.
path/to/directory disable

# Explicitly specifying a name to use for the directory under /etc/sv.
# A standard log/run script will be created.
path/to/directory name=my-preferred-name,logscript

and that's the tea, bestie 🍵✨ you're now fully fluent in dh_runit, fr fr. this page came from the user-contributed Perl documentation — built with perl v5.40.1, dated 2026-07-09 — and yes, it literally says DH_RUNIT(1) down at the bottom, in case the algorithm needed a reminder. go forth and supervise, queen 👑💖

📦 where this page comes from

ubuntu stonking: dh-runit 2.16.7ubuntu2 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms