An unofficial Guide to runit on Debian-derived distros (version 2)

Mercury · Yesterday 21:23:18

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 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 to enable them. (See the section “Service Sync” below)

Service Sync

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 these runtime copies. (See the section “Service Auto-enable” below).

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. In general, every service definition in ⋯/sv.src/ should contain this file. If the service definition does not contain this file, or -- more likely -- 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.

The sync operation will apply even to services that are already installed, so an updated service definition in ⋯/sv.src/ will automatically propagate to ⋯/sv.now/.

Conceptually, this process checks if any service executables actually present on the system have corresponding runit service definitions available and so can be supervised/controlled by runit. If they do, the service definition is copied from the ⋯/sv.src/ library and installed (or updated, as the case may be) as a proper runit service in ⋯/sv.now/.

If the service definition in /usr/share/runit/sv.src/ is removed, there will be no effect on already-installed services in ⋯/sv.now/. If the executable program referred to by the service ⋯/.meta/bin file is removed, the runtime copy in ⋯/sv.now/ will not be affected and will remain installed for potential future use. However, the service will be automatically disabled at next boot by removing its symbolic link in ⋯/default/.

This process is triggered 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 which manages the installation of applicable services (that is the selective copy from ⋯/sv.src/ to ⋯/sv.now/).

To disable the service sync entirely, create a symbolic link /etc/runit/atomic.upgrade to target /usr/bin/true. trigger_sv will call atomic.upgrade preferentially over cpsv. By making this a no-op, the entire syncThis 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.

Service Auto-enable

This important behavior lacks official documentation.

At each boot, any services located in /etc/sv/ or in /usr/share/runit/sv.now/ are automatically enabled, unless they have been explicitly disabled by the local admin.

The services in those directories are placed under runit supervision/control by creating symbolic links in /etc/runit/runsvdir/default/ targeting them. (⋯/default/ is the directory containing enabled services and is actively and continuously monitored by runit during normal operation).

If the same service name exists in both /etc/sv/ and ⋯/sv.now/, the one in /etc/sv/ will be preferred as the target. This allows the local admin to override package-provided services with locally customized versions.

If the executable program referred to by the service ⋯/.meta/bin file (if one exists) is removed, the service will be automatically disabled at next boot by removing its symbolic link in ⋯/default/. (Conceptually this is a clean-up operation.)

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 also calls cpsv or atomic.upgrade as described in the section “Service Sync” above.)

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.

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 purpose is to maintain a reasonably functional system by using sysVinit services for which runit variants are not available or 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_sysv_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 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 (Yesterday 21:28:54)

Mercury · Yesterday 21:27:00

Reposted with updates because it's impossible for me to edit the previous version of this topic.

Error reports and contributions are welcome.

ralph.ronnquist · Yesterday 22:06:17

dev1galaxy.org is a "discussion forum", not a "blog site" ot "wiki".

golinux · Yesterday 23:00:21

The "Guide" is within the category of "Documentation". Do we need to eliminate that option?

greenjeans · Today 00:37:03

The description of "Documentation" says "How-tos and Tips & Tricks contributed by Devuan users".

I'd say it's a VERY valuable resource and this runit guide is extremely helpful. Thank you @Mercury.

The officially official Devuan Forum!

#1 Yesterday 21:23:18