Learn Void Linux - runit: Init & Service Management

#Introduction

In episode 2 we met runit as PID 1. Episode 5 dissects it fully: how runit works, how services are defined and enabled, and which commands are used to control them. After this episode, you'll be skilled at managing services in Void — a skill used in almost every subsequent episode.

runit's way of thinking is very different from systemd. A service isn't a unit file with many options, but rather a directory containing scripts. This concept feels odd at first, but it's exactly what makes runit transparent: you can read precisely what a service runs.

Let's start from the boot flow through to the practice of managing services.

#Init Flow and Process Supervision

#From PID 1 to runsv

At boot, the kernel runs runit as the first process. runit then launches runsvdir, which scans the /var/service/ directory. For each entry, runsvdir spawns a runsv — a per-service supervisor responsible for starting, monitoring, and restarting the service when needed:

PID 1 (runit)
  -> runsvdir
       -> runsv (service A)
       -> runsv (service B)
       -> runsv (service C)

If a service crashes, runsv automatically starts it again. This is service supervision that's always active — one of the main reasons you use runit.

#The /var/service and /etc/sv Directories

Services are enabled via a symlink from /etc/sv/<service> to /var/service/<service>. /var/service is the directory scanned by runsvdir, while /etc/sv is the store of available services:

ls -l /var/service/
ls /etc/sv/

The output of ls -l /var/service/ shows symlinks like sshdd -> /etc/sv/sshd and dhcpcd. All active services are here.

#Service Structure and the sv Command

#Anatomy of a Service Directory

Each service contains a run script, and may also have finish, down, log, and variables in conf. A minimal example of a run script:

#!/bin/sh
exec /usr/sbin/sshd -D

The exec line in the run script replaces the shell with the sshd process — this ensures runsv supervises the correct process. The script must be executable; check its permissions:

ls -l /etc/sv/sshd/run

If the script isn't executable, the service won't run.

#The sv Command for Controlling Services

The main service management command is sv:

sv status sshd
sv up sshd
sv down sshd
sv restart sshd

sv status sshd shows run: sshd: (pid 123). If a service dies due to a failure, the status will show down: sshd: 3 seconds, normally up.

#Permanently Disabling a Service

To prevent a service from starting again, mark the service directory with a down file:

sudo touch /etc/sv/sshd/down
sudo sv down sshd

The presence of a down file in /etc/sv/sshd/ makes runsv hold that service. Removing the down file and running sv up will enable it again.

#Enabling and Modifying Services

#Enabling a New Service

To enable a service from /etc/sv/, just create a symlink:

sudo ln -s /etc/sv/cronie /var/service/

The ln -s /etc/sv/cronie /var/service/ command makes runsvdir detect the new service immediately, without any reload or restart. To remove a service from active use, simply remove the symlink.

#Modifying Service Configuration

Some services load variables from a conf file. Change its contents, then restart:

sudo vim /etc/sv/some-service/conf
sudo sv restart some-service

A good habit: after changing a run script or conf, always sv restart and verify with sv status and the service log.

#Reading Service Logs

Services with a log subdirectory redirect their output to svlogd. Logs can be read directly:

tail -f /var/log/sshd/current

The tail -f /var/log/sshd/current command shows the sshd log live. This log directory structure is one of the things users new to journald need to get used to.

#Common Errors and Their Solutions

#Service Not Running

When a service isn't running, check three things in order: the status with sv status, the symlink's presence in /var/service/, and the log. This combination almost always finds the root cause:

sv status sshd
ls -l /var/service/ | grep sshd
tail -n 20 /var/log/sshd/current

#Two-Service Conflict

If two services compete for the same resource — for example two web servers on port 80 — they will crash in turn. The solution is to shut one of them down, not rely on runsv to resolve it.

#Conclusion

Episode 5 equipped you with the ability to manage runit services: understanding the hierarchy from runit to runsvdir and then runsv, the service structure in /etc/sv/, enabling services via symlinks in /var/service/, and controlling them with sv and the down file.

Key takeaways:

• runit is PID 1, spawning runsvdir and then one runsv per service.
• A service is a directory in /etc/sv/ containing a run script.
• Services are enabled via a symlink in /var/service/.
• sv status, sv up, sv down, and sv restart are your day-to-day controls.
• A down file marks a service so it doesn't start automatically.
• Service logs are read via the log directory in /var/log/.

In the next episode, episode 6, we will compare glibc vs musl — the differences between the two libcs Void offers, their pros and cons, the implications for repositories and applications, and when you should choose each.