1 Purpose and role

runsvdir is a small process supervision tool used to watch a directory tree of services and start a dedicated supervisor for each service entry it finds. It belongs to the daemontools and s6-style administration approach, where service state is represented on disk and managed through simple executable scripts. Its main purpose is to help keep long-running programs available with minimal administrative overhead.

Unlike a general-purpose init system, runsvdir focuses on a narrow task: supervising many independent services in a consistent directory layout. This makes it useful in environments that favor transparency, small components, and explicit control over program lifecycles.

1.1 Service supervision basics

Service supervision means observing a process, detecting when it exits, and starting it again if needed. In this model, a supervisor owns the lifecycle of a service, rather than relying on a human administrator to notice failures. The supervisor can also react to control commands, logging setup, and shutdown requests.

The approach is designed for reliability and simplicity. Each service has a clear definition, and the supervising machinery remains separate from the service itself. This separation reduces hidden state and makes service behavior easier to understand.

1.2 Relationship to the service directory model

The service directory model organizes each service in its own filesystem directory. That directory usually contains executable scripts and optional control files describing how the service should be launched and managed. runsvdir scans such a tree and starts one supervisor for each eligible subdirectory.

This model keeps configuration close to the service it controls. Because the information is stored as files and executables, administrators can inspect, copy, or modify services with ordinary Unix tools. The directory structure also allows services to be added or removed without changing a centralized configuration database.

1.3 Typical use cases

runsvdir is commonly used on Unix-like systems that prefer lightweight supervision over large management frameworks. It is well suited to machines running several simple daemons, such as network listeners, logging helpers, or local background workers. It is also useful in embedded systems and minimal server environments.

The tool is especially helpful when services should be restarted automatically after crashes or transient failures. It can also support controlled startup ordering through the presence or absence of service directories, although it does not itself provide advanced dependency management.

2 How runsvdir works

runsvdir continuously watches a chosen directory that contains service subdirectories. When it detects a valid service entry, it launches a separate supervisor process for that service. Those per-service supervisors then handle the actual execution and restart logic for the underlying programs.

The design is intentionally modular. runsvdir manages the set of services, while each service supervisor manages one service instance. This division of labor keeps the system small and predictable.

2.1 Monitoring a service directory

The service tree is treated as the source of truth. runsvdir checks the designated directory and looks for entries that qualify as services. In many setups, each service is represented by a directory containing a runnable command file and optional companion scripts.

If a service directory is added while runsvdir is running, it can be picked up without requiring a full reconfiguration. Likewise, removing or disabling a service directory can stop it from being supervised, depending on the surrounding tooling and conventions in use.

2.2 Spawning per-service supervisors

For each service directory, runsvdir starts a dedicated supervisor, commonly called runsv in the daemontools family. That supervisor is responsible for launching the service command and watching its state. The per-service process isolates failures so that one service does not directly interfere with another.

This one-supervisor-per-service pattern is a defining feature of the ecosystem. It simplifies error handling because each service has a single place where start, stop, and restart decisions are made. It also makes diagnostics easier, since the state of one service can be inspected independently of the rest.

2.3 Automatic restart behavior

If the supervised program exits unexpectedly, the per-service supervisor typically starts it again. This restart loop is central to the supervision model, since it helps services remain available after crashes or other interruptions. The restart policy is usually straightforward rather than highly configurable.

The aim is resilience through repetition. Instead of treating a process exit as a terminal event, the supervisor treats it as a condition to recover from. This makes runsvdir useful for long-running daemons that should stay active unless explicitly stopped.

2.3.1 Handling service exits

When a service process exits, the supervising process records the change and determines whether the service should be relaunched. In normal operation, an unexpected exit is followed by another start attempt. If the exit was requested intentionally, the supervisor may remain idle until instructed to start again.

The service exit itself may be caused by a crash, a configuration problem, or a temporary resource issue. runsvdir does not resolve those problems directly, but it ensures that the service management framework notices them quickly.

2.3.2 Recovery after failure

Recovery usually means automatic restart after a brief pause or according to the supervisor’s internal rules. Because the service definition remains on disk, the restart logic does not depend on external stateful daemons or databases. Once the underlying issue is corrected, the service can resume normal operation through the same supervision path.

This model is particularly effective for simple services that are expected to be self-contained. It provides a basic but dependable recovery mechanism without requiring complex orchestration.

3 Service directory structure

The filesystem layout is central to how runsvdir operates. Services are represented by directories, and those directories contain the executable material the supervisor needs. The structure is intentionally sparse so that the service definition remains easy to inspect and maintain.

A consistent directory layout also makes automation easier. Tools can create, copy, or remove service entries with ordinary file operations, which fits naturally into Unix administration practices.

3.1 Main service tree

The main service tree is the directory that runsvdir watches. It often contains many service subdirectories, each of which describes one managed program. Administrators may choose a dedicated path for enabled services and another location for disabled or staged ones.

The tree acts as a registry of active supervision targets. Because the tree is directory-based, the set of supervised services is visible at a glance. That visibility is one reason the model is valued in minimal system design.

3.2 Per-service subdirectories

Each service subdirectory defines one service. Its contents usually include the launch script and, optionally, scripts for logging and shutdown behavior. The directory itself serves as the unit of management, so enabling or disabling a service can be as simple as placing or removing that directory from the watched tree.

This arrangement supports simple packaging and deployment. A service can be transferred as a self-contained directory, which reduces the need for separate configuration registries or bulky metadata formats.

3.3 Control files and scripts

Service directories often contain small executable files that tell the supervisor how to run and manage the service. These scripts may be plain shell scripts or another executable format accepted by the system. The exact naming conventions vary among implementations, but the purpose of each script is generally clear.

Because the scripts are regular files, administrators can test them independently before placing them under supervision. This keeps failures localized and makes the service definition easier to reason about.

3.3.1 run script

The run script is the primary executable for the service. It starts the actual program that is being supervised, often after setting environment variables or preparing working directories. When the supervisor invokes this script, it becomes the main process for the service.

A well-written run script is usually short and direct. It should do only the necessary setup and then hand control to the target program, avoiding extra complexity that might interfere with supervision.

3.3.2 log script

A log script is used when service output should be handled by a separate logging process. Rather than letting output vanish into the system void, the service can pass its standard streams to a dedicated logger. This supports structured log collection and easier troubleshooting.

In many supervision setups, logging is treated as a peer service. That means the service and its logger can be started and supervised independently while still remaining linked in the directory layout.

3.3.3 finish script

A finish script runs after the service stops, often to clean up temporary state or manage exit-related actions. It can be used to release resources, remove stale files, or record shutdown information. The script provides a controlled place for end-of-life tasks.

Finish scripts are especially useful when a service needs a small amount of cleanup before being restarted. They help preserve orderly transitions between service states.

4 Operational behavior

The operational cycle of runsvdir is straightforward: start the directory watcher, spawn supervisors for valid services, and keep them running as long as they remain configured. The tool does not aim to perform elaborate orchestration. Instead, it focuses on consistent observation and restart behavior.

Its runtime model depends on a small number of clear transitions. Services begin, run, exit, and are restarted or stopped according to supervisor logic and user commands.

4.1 Startup sequence

At startup, runsvdir examines the configured service directory and identifies available service entries. For each one, it launches the appropriate supervisor process. If the directory already contains active services, supervision begins immediately once the watcher is running.

This startup behavior fits well with boot-time activation. A system can bring up a suite of services by starting runsvdir early and letting it populate the rest of the supervision tree.

4.2 Runtime supervision

While running, runsvdir remains focused on the directory contents and the state of child supervisors. The per-service supervisors handle the repetitive tasks of starting and restarting the managed programs. If a service stays healthy, the supervision path is largely quiet and transparent.

When changes occur, the effect is usually local to one service. This localism is a major operational benefit, since it avoids cascading effects across unrelated daemons. Administrators can inspect individual service directories and control them separately.

4.3 Signal handling

As a Unix process, runsvdir can react to signals used for stopping or managing the supervision session. Signals are part of the standard control surface, although the exact behavior may depend on the implementation and surrounding tools. In practice, signal handling provides a simple way to terminate or influence supervision.

4.3.1 Stopping supervision

Stopping supervision means terminating runsvdir and, by extension, preventing further management of the watched service tree. Depending on configuration and external process behavior, this may also lead to the controlled shutdown of the supervised services. The exact result is shaped by the service scripts and supervisor semantics.

Administrators often use this during system shutdown or when reworking the service tree. It provides a clean exit point for the supervision framework.

4.3.2 Reloading or restarting services

Reloading usually refers to making the supervisor recognize changes in the service tree, while restarting refers to cycling one or more services. In a directory-based model, these actions are often accomplished by modifying the relevant service directories or sending control commands to the individual supervisors. The broader watcher then continues monitoring the tree.

Because the system is filesystem-centered, many changes do not require a complex configuration reload. Instead, services can be updated by editing scripts or replacing directories, then allowing the supervisors to respond.

5 Configuration and deployment

Deploying runsvdir typically involves choosing a service directory and arranging the filesystem so that each desired daemon has its own subdirectory. The configuration is intentionally sparse, which keeps deployment straightforward. In many setups, the service tree is created during package installation or system provisioning.

The approach works well in scripted environments, since service directories can be created and manipulated programmatically. This makes it easy to replicate a configuration across multiple hosts with limited tooling.

5.1 Creating a service directory

Creating a service directory usually begins with making a directory for the service and adding the required run script. Optional files for logging or cleanup can be added as needed. Once the directory is placed under the watched tree, runsvdir can detect it and begin supervision.

This workflow encourages incremental setup. An administrator can prepare the directory offline, validate the scripts, and only then enable the service by placing it in the active tree.

5.2 Integrating with init systems

runsvdir can be started by a traditional init system or by another boot-time supervisor. In such arrangements, the init system only needs to launch the directory watcher; the watcher then handles the rest of the service set. This reduces the amount of init-level configuration required for multiple daemons.

The integration model is intentionally light. Rather than replacing the init system entirely, runsvdir complements it by taking over service supervision after the machine begins booting.

5.3 Running under system boot

At boot, runsvdir is often started early enough to bring up essential background services soon after the filesystem is available. Because services are defined as directories, boot-time activation can be highly repeatable. The same service tree can be used across reboots without rewriting configuration state.

This makes the tool attractive for systems that prize deterministic startup. The filesystem layout can be prepared in advance, and the runtime behavior follows directly from that layout.

6 Logging and diagnostics

Logging is an important part of supervised service management, since it helps explain both normal activity and unexpected exits. In runsvdir-based setups, logs are commonly handled by a separate logger process or by a dedicated logging subservice. This separation keeps the main program simple and avoids mixing application logic with output collection.

Diagnostics are usually performed by examining the service directory, the supervisor state, and the generated log files or streams. The layout favors direct inspection rather than hidden centralized telemetry.

6.1 Service logging setup

A service may be paired with a logging component that receives its standard output and standard error. This allows logs to be written to files, rotated, or forwarded in a controlled way. The logging process itself can be supervised just like the main service.

Keeping logging separate can improve reliability. If the application and the logger are distinct processes, a failure in one does not necessarily destroy the structure of the other. It also makes it easier to adjust log handling without changing the application binary.

6.2 Output redirection patterns

Common patterns include writing output to a file, piping it to a logger, or using a dedicated log directory. The chosen method depends on the deployment style and the needs of the service. In minimalist setups, a small log pipeline is often preferred over a large logging stack.

These patterns are straightforward to audit because they are expressed in executable scripts. Administrators can see exactly where service output goes and modify the behavior with standard Unix tools.

6.3 Troubleshooting common issues

Typical problems include missing executable permissions, malformed scripts, incorrect paths, or a service that exits immediately after launch. Because the model is simple, many issues can be found by checking the service directory contents and the relevant logs. A failed service often reveals its problem through repeated restart attempts or clear error messages.

Another common issue is placing a service directory in the wrong location or leaving out a required file. Since supervision depends on the filesystem structure, even small layout mistakes can prevent a service from being recognized.

runsvdir is part of a broader family of Unix supervision utilities. Related tools differ mainly in how they discover services, how they supervise them, and how much policy they embed. Despite those differences, they often share the same general philosophy of small, explicit service control.

Understanding the relatives of runsvdir helps clarify its place in the ecosystem. It is not a standalone orchestration platform, but a directory watcher that delegates actual service control to per-service supervisors.

7.1 runsv

runsv is the per-service supervisor typically launched by runsvdir. Where runsvdir manages the collection of services, runsv manages one service at a time. This makes runsv the immediate controller of start, stop, and restart behavior for the target program.

The two tools are designed to work together. runsvdir scans the tree and launches supervisors, while runsv handles the lifecycle of each individual daemon.

7.2 svscan

svscan is another service directory scanner from the same general tradition. It also watches a directory and starts supervisors for service entries. In many discussions, svscan and runsvdir are compared because they fulfill similar high-level roles within directory-based supervision systems.

The practical differences depend on the implementation family and the conventions surrounding it. Both tools illustrate the same central idea: use a filesystem tree to define services and a small watcher to activate them.

7.3 s6-svscan

s6-svscan is the scanning component in the s6 supervision suite. Like runsvdir, it observes a service directory and starts supervision processes for discovered entries. It belongs to a newer but closely related set of tools that continue the minimalist supervision approach.

The s6 family adds its own conventions and companion utilities, but the core concept remains familiar. Services are still described on disk and managed by small, dedicated processes.

8 Advantages and limitations

runsvdir offers a compact and understandable way to supervise services, especially on systems that value clarity over feature richness. Its directory-based model makes behavior visible and easy to script. At the same time, the same simplicity limits the amount of policy and orchestration it can provide.

The tool is best understood as a building block. It is highly effective when used in a carefully designed service tree, but it is not meant to solve every kind of deployment problem.

8.1 Simplicity and predictability

One of the main advantages of runsvdir is its small conceptual surface area. Administrators can learn the model quickly: place a service directory in the tree, provide a run script, and let supervision begin. That predictability makes it easier to maintain over time.

The modest scope also reduces configuration drift. Because the service definition lives in a directory, it is less likely to become hidden inside a large, opaque management layer.

8.2 Filesystem-based management

Filesystem-based management is highly portable and easy to automate. Ordinary tools can inspect, copy, version, and deploy the service layout. This makes the system friendly to simple shell-based administration and to environments that avoid complex databases or centralized state stores.

The same property supports transparency. An operator can often understand the running system by looking at the directory tree alone, which is a strong advantage for troubleshooting and auditing.

8.3 Constraints of the model

The minimalist design also creates limits. runsvdir does not provide rich dependency resolution, elaborate scheduling, or broad cluster orchestration. It expects the administrator to structure services carefully and to use external tools when more advanced policy is needed.

Its model is strongest for independent daemons with clear start commands and straightforward restart behavior. For larger or more interdependent service landscapes, additional tooling is often required.