runsvchdir
Change the active runit service directory
TLDR
Switch runsvdir directories
SYNOPSIS
runsvchdir <service-directory>
PARAMETERS
service-directory
The path to the new directory that runsvdir should supervise. This directory must contain subdirectories, each representing a service to be supervised by runsvdir.
DESCRIPTION
runsvchdir is a utility from the runit service supervision suite. Its primary function is to instruct a running runsvdir process to change the directory from which it supervises services. runsvdir normally supervises all subdirectories within a specified service-directory.
By executing runsvchdir <new-directory>, it modifies a symbolic link (usually named . or _current) in the runsvdir's base service directory, pointing it to <new-directory>. Subsequently, it sends a SIGHUP signal to the runsvdir process, prompting it to re-read its configuration and start/stop services based on the new active directory. This allows for dynamic switching of entire service sets without restarting the runsvdir supervisor itself, which is crucial for maintaining system uptime and managing different application environments.
CAVEATS
runsvdir must be running and configured to use the runsvchdir mechanism (e.g., by supervising a . symlink or similar convention).
Permissions: The user running runsvchdir needs appropriate write permissions to the runsvdir's base service directory (where the symlink resides) and read/execute permissions for the new-service-directory.
Services in the old directory will be stopped, and services in the new directory will be started (or their status updated) by runsvdir. This can cause momentary service interruptions during the switch.
The runsvdir process typically runs as root, so runsvchdir often needs to be run with elevated privileges or via a mechanism that allows it to send signals and modify the symlink.
HOW IT WORKS
runsvchdir typically updates a symbolic link (often named . or _current) within the runsvdir's root service directory to point to the <service-directory> specified. It then sends a SIGHUP signal to the runsvdir process, instructing it to re-read its configuration and adjust its supervision based on the new target of the symlink. This clever use of symlinks and signals enables efficient, on-the-fly service group switching.
COMMON USE CASES
runsvchdir is particularly useful for:
Switching between different development, staging, or production service environments.
Enabling or disabling large sets of services quickly and atomically.
Performing A/B testing of service configurations or application versions.
Facilitating blue/green deployments by shifting traffic from one service group to another.
HISTORY
runit was created by Gerrit Pape as a lightweight, reliable, and portable init and service supervision system, often seen as an alternative to System V init, systemd, and supervisord. runsvchdir is an integral part of runit's design for dynamic service management without requiring restarts of the main supervisor. Its development focuses on simplicity and robustness, adhering to the Unix philosophy of doing one thing well.