An unofficial Guide to runit on Debian-derived distros

Mercury · 2026-02-10 19:27:28

About this guide

This guide is intended to describe the behavior, use, and configuration of the runit init system on Debian-descended Linux distributions, including Devuan and its derivatives. It exists because important parts of the official runit documentation are misleadingly incomplete or outright wrong as applied to the version of runit packaged for Debian and its descendants.

This guide is a best-effort, based on hobbyist-level analysis. It may, and probably does, contain material errors. This guide is current as of January 2026, and applies to runit version 2.2.0 and runit-services version 0.10.1 as available in the Debian package repositories. This guide comes with no warranty whatsoever. Copying of this content, in part or in whole, with or without modification, is permitted and encouraged, and no attribution is required. This guide is licensed under the WTFPL version 2 or any later version

Directories

Runit service files are stored as follows. ( 🔗︎ indicates a symbolic link)

/etc/service/ 🔗︎ /etc/runit/runsvdir/current/ 🔗︎ /etc/runit/runsvdir/default/
Contains the currently active (enabled) services. Runit will react immediately to the creation or removal of items here. In a typical installation, most items in this directory will be symbolic links to /usr/share/runit/sv.now/ or to /etc/sv/, but links to services located elsewhere are also possible and will function as long as the service is properly defined at the target

/etc/sv/
Contains installed (but not necessarily enabled) local services. Services installed and managed by the local admin and/or manually converted from other init systems (systemd, sysVinit) should exist here. Enabled services should be the targets of symbolic links in /etc/runit/runsvdir/default/ (see above)

/usr/share/runit/sv.current/ 🔗︎ /usr/share/runit/sv.now/
Contains installed (but not necessarily enabled) stock services, that is, those installed by packages and managed automatically. Services existing here are “runtime copies” pulled from /usr/share/runit/sv.src/ (see below) when certain conditions are met to make them available for use. Enabled services should be the targets of symbolic links in /etc/runit/runsvdir/default/ (see above)

/usr/share/runit/sv.src/ 🔗︎ /usr/share/runit/sv/
Contains stock service definitions provided by packages. This directory is an extensive library of items only some of which apply to the current OS configuration. In general, these will never be the targets of symbolic links in /etc/runit/runsvdir/default/. When certain conditions are met, indicating that specific services should be enabled, they will be automatically copied to /usr/share/runit/sv.now/ and the symbolic links in /etc/runit/runsvdir/default/ will be created ro enable them (see the section “Service Sync” below)

Service Sync & Service Auto-enable

This important behavior lacks official documentation. At boot time, a service sync occurs.

Services available in /usr/share/runit/sv.src/ are checked, and if they are applicable to the currently configured OS, they will be synced via a copy operation to /usr/share/runit/sv.now/ where they are known as “runtime copies” and are considered properly installed. By default, they will then be automatically enabled by creating symbolic links in /etc/runit/runsvdir/default/ targeting the runtime copies.

Services are considered applicable if they include a /usr/share/runit/sv.src/${servicename}/.meta/bin file containing the name of an executable program present on the current OS configuration. If the service definition does not contain this file, or if the executable program referenced by it does not exist, then the service is presumed to be inapplicable and a runtime copy will not be created.

If the service definition in /usr/share/runit/sv.src/ is removed, there will be no effect on already-installed services.

If the executable program referred to by the service ⋯/.meta/bin file is removed, the service will be automatically disabled at next boot by removing its symbolic link in ⋯/default/, however the runtime copy in ⋯/sv.now/ will not be affected and will remain installed for potential future use.

This process is controlled by the helper script /usr/lib/runit/trigger_sv, which is called directly from runit level 2 (/etc/runit/2) at each boot. trigger_sv further calls cpsv to sync services (selectively copy from ⋯/sv.src/ to ⋯/sv.now/), then automatically enables services by creating links in ⋯/default/.

To override auto-enable behavior for a specific service, create a symbolic link in ⋯/default/, matching the name of the service with the addition of a leading dot, and remove the regular service link if it exists. For example, to disable the cron service, create the symbolic link /etc/runit/runsvdir/default/.cron 🔗︎ /usr/share/runit/sv.now/cron and delete the symbolic link /etc/runit/runsvdir/default/cron 🔗︎ . These actions can be performed in one command using the update-service utility. See the section “Disabling and Enabling Services” below for more details.

There is no intended configurable way to override auto-enable behavior globally for all services, and there is no intended configurable way to prevent the runtime copies from being created. However, the following methods will work:

To disable all service sync and auto-enable behavior at boot time, edit /etc/runit/2 and comment out the call to /usr/lib/runit/trigger_sv. Note that trigger_sv may still be automatically called as a dpkg postinst trigger during apt operations.

To disable the service sync only, but keep the auto-enable behavior, create a symbolic link /etc/runit/atomic.upgrade to target /usr/bin/true. trigger_sv will call atomic.upgrade preferentially over cpsv. This method may also be used to link to a script with custom service sync/copy logic that works with a curated list of services or performs more complex operations. Note that atomic.upgrade must target an executable file to be effective.

SysVinit Emulation

This important behavior lacks official documentation.

Runit will automatically start sysVinit services enabled at runlevel 2 (those in /etc/rc2.d/), if a runit service with the same name is not installed. The emulation logic checks for installed runit services in /usr/share/runit/sv.current and /etc/sv/ and enabled services in /etc/service/ to determine if a runit service with a matching name exists.

If both a sysVinit and runit service with the same name exist, the sysVinit service will not be started, regardless of whether the runit service is currently enabled. This means that if the user installs a runit service and disables it, the logic presumes that the user wants the service disabled altogether, and the sysVinit alternative is not desired. If the runit service is enabled, it will be used preferentially over its sysVinit variant.

This process is controlled by the helper script /lib/runit/run_sv_scripts, which is called directly from runit level 2 (/etc/runit/2) at each boot.

The following files can be used to override the default behavior described above. The files do not require any content. Only their existence is checked by the script logic.

/etc/runit/no.emulate.sysv
This file will disable sysVinit emulation completely.

/etc/runit/override-sysv.d/${servicename}.block
This file, matching the name of the service with the addition of a .block extension, will disable the emulation of that specific sysVinit service in all cases, even if a matching runit service does not exist.

/etc/runit/override-sysv.d/${servicename}.sysv
This file, matching the name of the service with the addition of a .sysv extension, will enable the emulation of that specific sysVinit service in all cases, even if a matching runit service (whether disabled or enabled) exists.

Note: A bug in runit-services versions 0.10.0 and earlier may cause a sysVinit service to start even when the matching runit service is installed and enabled, and even when a .block file is present for that service, which may cause unpredictable or buggy behavior. This has been observed to occur with login managers such as slim, causing login loops. This is caused by faulty script logic in dbus.dep-fixer, included in the runit-services package. This bug was corrected in runit-services version 0.10.1.

Disabling and Enabling Services

Official runit documentation states that simply deleting the service's symbolic link within /etc/runit/runsvdir/default/ will disable the service. However, because of the auto-enable behavior described in the “Service Sync & Service Auto-enable” section, this change will not persist across reboots for any services located in /etc/sv/ or in /usr/share/runit/sv.now/ (which together typically comprise almost all runit services). Deleting the link in ⋯/default/ in that case will disable the service only for the current session, and the service will be automatically re-enabled at next boot.

This does not apply to services located outside those two standard directories.

The auto-enable behavior will be inhibited by the presence of a symbolic link in ⋯/default/ matching the name of the service with the addition of a leading dot. For example, /etc/runit/runsvdir/default/.cron 🔗︎ will disable the cron service, and this effect will persist across reboots. Note that this file must be a valid symbolic link, and its target must be a directory to have the proper effect. Typically, the link targets the directory of the disabled service, but this is not strictly necessary, and linking to an empty dummy directory may be used to pre-emptively disable (or “blacklist”) a service before it is installed.

Runit will not start any service only linked by a dotfile in ⋯/default/, but if (for whatever reason) both a dotfile and regular symbolic link for a particular service exist there, then that service will start. Such a situation is typically the result of an error and may be regarded as a misconfiguration.

In general, directly adding, removing, or modifying the links in /etc/runit/runsvdir/default/ is not recommended. Debian-packaged runit provides the update-service command-line utility to manage services. This utility will manage symbolic links in ⋯/default/ and make other changes to persist service status.

Quick reference:

To enable/disable a service:
update-service --add service-directory
update-service --remove service-directory
These commands will, respectively, add and remove a service from runit supervision. This is accomplished by the creation and deletion of the appropriate symbolic links in /etc/runit/runsvdir/default/, as described above.

To set default service state:
update-service --auto service-directory
update-service --noauto service-directory
These commands will set the service to, respectively, started (“up”) and stopped (“down”) at system boot. By default any installed services are automatically started at boot time unless they have been marked not to be. This is accomplished by placing a down file within the service directory. The existence of this file indicates to runit that the service should not be auto-started at boot.

In any of the above commands, service-directory may be the full path to the service or only the basename (final part of the path; typically equal to the name of the service). In the latter case, the directories /etc/sv/ and /usr/share/runit/sv.now/ are searched, in that order, for the service, and the command is applied to the first one found.

See the manual page for more information.

Tips and Tricks

• To increase runit logging verbosity, create the file /etc/runit/verbose. This file does not require any content. Only its existence is checked. Runit logs its boot-time output to /var/log/boot.

• To list all enabled runit services and their paths, use this command:
for svc in $(update-service --list); do update-service --list $svc; done
There is currently no way to get this output from a single invocation of update-service, so the for-loop is necessary.

[More content to be added]

Last edited by Mercury (Today 04:40:24)

brocashelm · 2026-02-10 20:29:27

Thanks for this. Runit service implementation in Debian-based distros is still severely lacking compared to other distros such as Void or Artix. Devuan's implementation simply adds a coat of paint over the already existing SysVinit services.

Lorenzo · 2026-02-14 16:23:34

Hi Mercury,

thanks for the guide! as it was said in other posts I haven't found yet the time to write a comprehensive guide/documentation to runit, for several reason:
time constrains of course, but also parts of the runit debian integration are still under development and I prefer to finish before writing a guide (it will be obsolete soon otherwise).
I try to keep manpages up to date though, so I suggest reading

man invoke-run
man update-service
man cpsv

Also I try to keep README files in runit and runit-servics packages up to date

/usr/share/doc/runit/README-*
/usr/share/doc/runit-services/README.gz

If not installed by default (not sure), I suggest to install apt-listchanges package
to read the NEWS during the upgrade (I do write NEWS when there are important changes)

that said let me add few comments on top of your guide:

/etc/sv/
Contains installed (but not necessarily enabled) local services. Services installed and managed by the local admin and/or manually converted from other init systems (systemd, sysVinit) should exist here. Enabled services should be the targets of symbolic links in /etc/runit/runsvdir/default/ (see above)

this is correct and is the desired end state, however there are still packages (getty-run, openssh-server, acpid, tor, irqbalance and few others)
that are using the legacy layout and install the service directory directly in /etc/sv/ (without metafiles, the legacy runit-helper is used instead of trigger_sv): I still have to organize the transition.

This important behavior lacks official documentation. At boot time, a service sync occurs.

be aware that, as the name may suggest, trigger_sv run as a dpkg trigger at the end of each apt operation (install/remove/upgrade), so the sync happens at runtime; then a sync was added to stage 2 to ensure that the first time you boot runit after an init-switch (sysvinit --> runit-init) the state of services is synched with defaults.
At runtime the trigger loop takes care of enable/disable services, but it also runs the second ("upgrade") loop that make sure that running services are restarted (or reloaded) when their binary is upgraded.
The upgrade loop is very important for security: if the running instance is not upgraded it may still be affected by CVEs while the package changelog claims the issue is fixed..

There is no intended configurable way to override this behavior globally for all services, and there is no intended configurable way to prevent the runtime copies from being created. However, the following methods will work:
To disable all service sync and auto-enable behavior, edit /etc/runit/2 and comment out the call to /usr/lib/runit/trigger_sv. Be aware that a future update of runit is likely to erase this change and it will have to be re-applied.

/etc/runit/2 is a conffile so dpkg will ask at upgrade if you want to keep your version or want to use the package version, no automatic overwrite will happen: but this wont stop the runtime dpkg trigger invocation.

If you want to override something (including metafiles) inside a service directory that is in /usr/share/runit/sv.current , the intended way is
create a copy in /etc/sv/ and maintain it by yourself (it won't be automatically overwirtten at upgrades, and there is no dpkg prompt so you have to import bugfixes by yourself).

(better if runit >= 2.2.0-7 is used for this)
As example for cron, you can do
(make sure there is no /etc/sv/cron dir first)

#cpsv p cron

than you can remove any symlink and replace it with a real file that includes your changes
to inspect the diff later you can do

#cpsv d cron

if you want to override *all* services dir in /usr/share/runit/sv.current then writing copies in /etc/sv/ is no longer practical: the metafiles interface and cpsv are designed to allow to roll your local/private collection in place of services provided by packages, but I haven't tested this myself yet and the operation is dangerous if done at runtime (if a directory disappear from runsvdir directory, the service is stopped, so guess what can happen if you switch the target of symlinks in /usr/share/runit/ the wrong way..) so I won't document it here for now.

Best,
Lorenzo

Mercury · Today 17:34:12

Hi @Lorenzo,

I made updates to the guide over the last week or so. It remains a work-in-progress but I think I corrected the most obvious problems. If you spot anything else that's wrong, please reply here or email me. That goes for anyone else reading this.

Some more context: The emphasis in this guide is on the workings of runit as it is visible to a regular user, who installs the typical Debian suite of runit packages, or selects runit as their init system during Devuan setup. In other words, the user who installs packaged runit and expects it to "just work" — as it (mostly) does, to its credit. The aim is to give the user an understanding of what runit does during normal operations; to answer "What's it doing now?" and to provide a solid base from which to start troubleshooting if things seem to be going wrong.

A lot of documentation out there veers off into topics that I don't think are beneficial for the new or casual user. In fact, they may bury the key bits, which are treated as an afterthought or presumed to just be known. Writing your own services or converting sysV scripts, installing user services, switching runsvdirs, etc. are advanced actions that the user can undertake if they have some expertise or a peculiar goal in mind. Meanwhile, understanding sysVinit emulation* and being able to firmly remove an unwanted service are things that are more likely for the typical user to encounter.

*What if the user thinks "Hmm, I use runit now and everything is fine, so let me just purge all these 'useless' old SysV scripts"?

I am, for sure, biased in this and fully admit that, and a lot of this guide was motivated by my own experiences and frustrations. What seems important to a developer is often not the same thing that's important to the user. I've been on both sides of that.

Last edited by Mercury (Today 17:35:18)

The officially official Devuan Forum!

#1 2026-02-10 19:27:28