An unofficial Guide to runit on Debian-derived distros

Mercury · Yesterday 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) services managed locally. Services installed by the local admin and/or converted from other init systems (systemd, sysvinit) should exist here. Enabled services should be the targets of symbolic links in /etc/runit/runsvdir/current/ (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/current/ (see above)

/usr/share/runit/sv.src/ 🔗 /usr/share/runit/sv/
Contains stock service definitions provided by packages. Whether these can be considered “installed” is a matter of interpretation. In general, these will never be the targets of symbolic links in /etc/runit/runsvdir/current/. When certain conditions are met, indicating that these services should be enabled, they will be automatically copied to /usr/share/runit/sv.now/ and the symbolic links in /etc/runit/runsvdir/current/ will be created (see the Service Sync section 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 copied to /usr/share/runit/sv.now/ where they are referred to as “runtime copies” and are considered properly installed. By default, they will be enabled by creating symbolic links in /etc/runit/runsvdir/current/ 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 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 installed services.

If the executable program referred to by the service is removed, the service will be automatically disabled at next boot by removing its symbolic link in /etc/runit/runsvdir/current/, however the runtime copy will not be affected and will remain installed for 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 /usr/bin/cpsv to effect the creation of the runtime copies, then enables services.

To override this behavior for a specific service, create or modify the file /usr/share/runit/sv.src/${servicename}/.meta/enable and set its contents to “yes” to have the service automatically enabled, or to any other content (though “no” is recommended) to prevent it from being automatically enabled. It is recommended to make the change in the service definition in sv.src/ as that will be automatically propagated to the runtime copy in sv.now/ at the next boot, whereas a change directly in sv.now/ will only persist if the ${servicename}/.meta/enable file is not present in sv.src/ (and therefore will not overwite the runtime copy)

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.

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 this executable preferentially to cpsv. This method may also be used to point to a script with custom service sync/copy logic.

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).

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: There is a bug in runit-services versions lower than 0.10.1 which may cause sysVinit services to start even when the matching runit service is installed and enabled, which may cause unpredictable or buggy behavior in that service.

Additional info to be added.

Last edited by Mercury (Yesterday 19:40:34)

brocashelm · Yesterday 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.

The officially official Devuan Forum!

#1 Yesterday 19:27:28