Local Startup and Shutdown Hooks

Local Startup and Shutdown Hooks refer to user-defined scripts or commands that are executed automatically during the system's initialization (startup) and termination (shutdown) phases on Alpine Linux systems using OpenRC as the service manager. These hooks allow administrators and users to customize and extend the behavior of the system by running specific tasks at critical points in the boot and shutdown sequences.

Definition and Purpose

Local Startup and Shutdown Hooks are mechanisms implemented through scripts placed in designated directories or referenced by service scripts managed by OpenRC. Their primary purpose is to perform necessary preparatory or cleanup actions locally on the system. For example, they can be used to mount filesystems, initialize hardware, start custom services, flush caches, unmount filesystems cleanly, or save system state before powering off.

These hooks operate outside the lifecycle of individual OpenRC services but integrate closely with the overall system's boot and halt process, ensuring that custom commands execute at precise moments without altering core service definitions.

Placement and Execution Flow

On Alpine Linux with OpenRC, the local startup and shutdown hooks are typically implemented via scripts located in:

• /etc/local.d/ — This directory contains user-defined scripts that run late in the boot process (after all services have started) and early in the shutdown process (before services are stopped). Scripts placed here must have executable permissions and usually end with .start for startup behavior and .stop for shutdown behavior.

• /etc/conf.d/local — This is a configuration file that can specify environment variables or commands related to local startup/shutdown actions.

During system startup, OpenRC executes scripts in /etc/local.d/ with the .start suffix after the standard system services have been initialized. Conversely, during shutdown, it executes scripts with the .stop suffix before stopping services and unmounting filesystems.

Script Naming and Permissions

Scripts in /etc/local.d/ must follow a strict naming convention to be recognized by OpenRC’s local service handler:

• Files ending with .start are executed during system startup.
• Files ending with .stop are executed during system shutdown.

Scripts must be executable (chmod +x) to be run by OpenRC.

Example:

/etc/local.d/mycustomscript.start
/etc/local.d/mycustomscript.stop

The .start script runs after all standard services have started, ensuring the system is fully operational. The .stop script runs during shutdown, allowing for cleanup actions before the system halts.

Integration with OpenRC

The local startup and shutdown hooks are managed by the local OpenRC service. This service is included in the default runlevel and is responsible for invoking the scripts inside /etc/local.d/.

• Starting the local service during boot triggers execution of all .start scripts.
• Stopping the local service during shutdown triggers execution of all .stop scripts.

The service itself can be controlled using standard OpenRC commands:

rc-service local start
rc-service local stop

This integration ensures that local hooks fit neatly into the OpenRC dependency graph, and their execution order aligns with the rest of the system services.

Typical Use Cases

• Initializing hardware devices or peripherals that require custom commands not covered by default services.
• Starting user-defined background processes or daemons that do not have dedicated OpenRC service scripts.
• Setting up environment variables or network configurations that need to be applied after all core services start.
• Flushing logs or caches and performing cleanup tasks to ensure data integrity during shutdown.
• Unmounting special filesystems or network shares cleanly before system poweroff or reboot.
• Running custom notifications or alerts during startup or shutdown.

Writing Effective Local Hook Scripts

To ensure robustness and maintainability, local startup and shutdown scripts should adhere to best practices:

• Scripts should be POSIX-compliant shell scripts to guarantee compatibility.
• Include proper error checking and logging to track execution success or failure.
• Avoid long-running or blocking operations that could delay the boot or shutdown process excessively.
• Use environment variables set by OpenRC or define custom ones in /etc/conf.d/local if needed.
• Ensure idempotency, so repeated executions do not cause unintended side effects.
• Make scripts executable and test them independently before relying on them in production.

Example of a simple local startup script /etc/local.d/myscript.start:

#!/bin/sh
# Example local startup hook

echo "Starting custom initialization..." >> /var/log/local_hooks.log
# Custom command to initialize a device or service
/usr/bin/mycustomcommand --init

Corresponding shutdown script /etc/local.d/myscript.stop:

#!/bin/sh
# Example local shutdown hook

echo "Running cleanup before shutdown..." >> /var/log/local_hooks.log
# Custom cleanup command
/usr/bin/mycustomcommand --cleanup

Ordering and Timing Considerations

Because local hooks run after all OpenRC services start (for .start scripts) and before they stop (for .stop scripts), they are suitable for actions that depend on other services being fully operational or require a clean system environment before shutdown.

If more precise control over execution order is needed, creating dedicated OpenRC service scripts rather than using local hooks is recommended, as OpenRC service scripts offer dependency declarations and finer control over starting and stopping sequences.

Summary of Mechanism

Local Startup and Shutdown Hooks provide a flexible, straightforward way to run user-defined commands during system boot and shutdown, complementing the OpenRC service framework on Alpine Linux. They enable customization without modifying core services, supporting system administrators in tailoring system behavior to specific needs.