RTFM · Troubleshooting
Service startup failures
OpenRC services refuse to start, die instantly, or hang the boot sequence: status, logs, dependencies and recovery.
Ask OpenRC precisely
rc-service <svc> status
rc-status # current runlevel state
rc-update show # what is scheduled at boot
rc-service <svc> start # attempt with output visiblePhantom started/stopped states
Stale pidfiles from unclean shutdown produce phantom 'started'. Confirm process truth before clearing state.
pgrep -af <daemon-name>
cat /run/<svc>.pid 2>/dev/null
rc-service <svc> zap # clear stale state carefullyzap forces OpenRC to forget state. Only do it after confirming the process truly is not running — zap on a live daemon invites double-start chaos.
Dependency ordering failures
Service needs network, syslog or database not yet up. Read the dependency declarations, then bring dependencies up explicitly to reveal which one stalled.
grep -A8 '^depend()' /etc/init.d/<svc>Config errors masquerading as binary errors
Many daemons exit quietly on bad config with output only visible on a foreground run. Run the actual binary briefly; config mistakes surface immediately.
<binary> --foreground --debug 2>&1 | head -40 # then Ctrl-CProve it works: service survives reboot
an rc-update enable cycle plus machine reboot yields an auto-started healthy service, not merely one hand-started today.
Did we miss something?
If this page left something unanswered, found an error, or there is another subject you would like documented, tell us. Saphira’s documentation grows from real problems people need to solve.
Send feedback or request a new section →
Prefer not to do it yourself?
Everything needed to do the work yourself is documented here and remains free — we charge for human time, not for withholding knowledge. Sometimes the missing resource is simply time. The same people who build Saphira can provide paid professional help with implementation, migration, troubleshooting and administration.