FreeBSD 12 – Common Problem 024 – Custom rc.d Service Never Starts at Boot

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Application is down after reboot until started manually.

Environment & Reproduction

Custom script in `/usr/local/etc/rc.d/` works manually but not during startup.

Root Cause Analysis

Missing `PROVIDE/REQUIRE` headers, executable bit, or `*_enable=YES` value.

Quick Triage

Check script metadata and enable flag.

head -n 30 /usr/local/etc/rc.d/myapp
sysrc myapp_enable
service myapp onestatus

Step-by-Step Diagnosis

Validate rcorder position and shell syntax.

rcorder /etc/rc.d/* /usr/local/etc/rc.d/* | grep myapp
sh -n /usr/local/etc/rc.d/myapp
service myapp rcvar

Solution – Primary Fix

Add correct headers, set executable bit, and enable via `sysrc`.

chmod +x /usr/local/etc/rc.d/myapp
sysrc myapp_enable='YES'
service myapp start

Solution – Alternative Approaches

Wrap app with daemon supervisor if startup dependencies are complex.

Verification & Acceptance Criteria

Service starts automatically after reboot and remains healthy.

Rollback Plan

Disable script in `rc.conf` and use manual start while script is corrected.

Prevention & Hardening

Template rc.d scripts and enforce static checks in deployment pipeline.

Related Errors & Cross-Refs

`myapp_enable is not set properly`, missing process after boot, rcorder omissions.

Related tutorial: View the step-by-step tutorial for freebsd-12.

View all freebsd-12 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

`rc.subr(8)`, `rc.conf(5)`, FreeBSD service framework docs.