OpenRC Service Scripts

OpenRC Service Scripts are shell scripts used by the OpenRC init system to manage the lifecycle of services on Unix-like operating systems, particularly those that emphasize simplicity and speed like Alpine Linux. These scripts provide a standardized way to start, stop, restart, and check the status of system services, interfacing directly with the OpenRC framework to ensure proper dependency handling and orderly service management during system boot, shutdown, and runtime.

Structure and Purpose

Each OpenRC service script is typically located in /etc/init.d/ and is a POSIX-compliant shell script that defines a set of functions corresponding to service actions such as start, stop, restart, status, and optionally reload or other custom commands. These scripts work as the interface between the OpenRC init system and the actual daemon or service, handling the setup, execution, and cleanup phases required to manage the service.

The primary purpose of OpenRC Service Scripts is to abstract the operational details of the service, providing a uniform control interface that OpenRC can invoke. This design allows OpenRC to orchestrate service startup and shutdown sequences correctly, respecting dependencies and system state.

Core Components of an OpenRC Service Script

1. Metadata and Header Information

Service scripts often begin with a comment block providing metadata, including the service description, dependencies, and runlevels. OpenRC parses some of this information to determine how and when to start the service.

Example header metadata:

#!/sbin/openrc-run
description="My sample daemon"

depend() {
    need net
    before nginx
    after logger
}

• depend() function declares dependencies, specifying services that must start before or after this service, or services that are needed for this service to run.
• The description field provides a human-readable explanation of the service.

2. Lifecycle Functions

The script defines functions corresponding to service lifecycle operations:

• start(): Contains commands to initialize and launch the service daemon. It typically performs environment setup, runs the daemon in the background, and checks for successful startup.

• stop(): Defines how to gracefully terminate the service, often by sending termination signals or invoking clean shutdown commands.

• restart(): Usually implemented as a combination of stop followed by start, allowing quick service restarts.

• status(): Checks and reports whether the service is currently running, often by inspecting PID files or process lists.

• Optional functions like reload() may be included to allow reloading configuration without full restarts.

Example:

start() {
    ebegin "Starting mydaemon"
    start-stop-daemon --start --exec /usr/sbin/mydaemon -- -c /etc/mydaemon.conf
    eend $?
}

stop() {
    ebegin "Stopping mydaemon"
    start-stop-daemon --stop --exec /usr/sbin/mydaemon
    eend $?
}

ebegin and eend are OpenRC utility functions to provide consistent output formatting and exit status handling.

3. Environment and Configuration

Scripts can source external environment files or configuration variables to allow customization without modifying the script itself. This promotes maintainability and flexibility.

Example:

. /etc/conf.d/mydaemon

The configuration file /etc/conf.d/mydaemon can define variables such as command-line options, user under which the service runs, or other environment settings.

4. Dependency Management

Dependencies declared in depend() influence the order of service startup and shutdown. OpenRC reads these declarations to build a dependency graph, ensuring that services start only after their prerequisites are active and stop before the services they support.

Dependency types include:

• need: Hard dependency; the service will not start without the specified service.
• use: Soft dependency; the service may start without it but will use it if available.
• before and after: Control order relative to other services.
• provide: Declares virtual services that this service fulfills.
• keyword: Tags for optional or conditional dependencies.

Execution Context and Integration

When OpenRC processes service scripts during system initialization or by administrator commands (e.g., rc-service), it invokes the appropriate function (start, stop, etc.) in the context of the service script. The OpenRC framework provides helper functions and environment variables to standardize behavior and output.

OpenRC Service Scripts rely on conventions such as PID files to track daemon processes, log files for output, and environment variables for configuration. These conventions allow OpenRC to monitor and control services reliably.

Service Lifecycle Hooks

OpenRC supports lifecycle hooks within service scripts to allow execution of custom commands at various points in the service lifecycle. These hooks include:

• prestart: Commands run before the main start() function.
• poststart: Commands run immediately after successful start().
• prestop: Commands run before the stop() function.
• poststop: Commands run after the service has stopped.

Hooks enable fine-grained control over service behavior, such as preparing resources before launch or cleaning temporary data after shutdown.

Example:

prestart() {
    echo "Preparing to start service"
}

Best Practices for Writing OpenRC Service Scripts

• Use the provided OpenRC helper functions (ebegin, eend, start-stop-daemon) to ensure consistent behavior.
• Always implement at least start, stop, and status functions.
• Clearly declare dependencies in the depend() function.
• Source external configuration files for flexibility.
• Use lifecycle hooks for setup and teardown tasks.
• Ensure scripts are POSIX-compliant shell scripts for maximum compatibility.
• Avoid long-running or blocking operations inside service scripts; delegate to the daemon itself.

OpenRC Service Scripts form the backbone of service management in OpenRC-based systems, enabling administrators and the system itself to manage services efficiently, reliably, and predictably through a unified interface that respects dependencies and system state.