Gnu Group Learning AcademyGnu Group ↗
FreeBSD Fundamentals · Module 12 of 14

Troubleshooting and recovery

Diagnose boot, service, network, storage and package failures using evidence-first runbooks and safe recovery paths.

Learning objectives

By the end of this module, you should be able to:

  • Structure troubleshooting by failure domain.
  • Use single-user/console recovery concepts appropriately.
  • Make the smallest reversible change first.

Evidence before action

Capture exact error messages, service status, recent logs and relevant configuration. Repeated restarts can erase timing or state evidence.

Recovery paths

Console access, single-user mode, boot environments on ZFS systems, configuration backups and filesystem snapshots provide different rollback options.

Worked examples

See the idea in practice.

Service triage bundle

service sshd status || true
pgrep -laf sshd || true
sockstat -4 -6 | grep ssh || true
tail -n 50 /var/log/auth.log
  • Desired state, process state, socket state and logs should tell a consistent story.
Hands-on lab

Lab — Diagnose persistent service state without losing SSH

Goal: Prove that a daemon can be running while disabled for the next boot, then restore the persistent state safely.

Before you start

  • Disposable VM with SSH available and KVM/console recovery open.
  • Do not stop sshd and do not reboot while sshd_enable is NO.
STEP 1

Capture persistent, process and socket state

sysrc sshd_enable
service sshd status
pgrep -laf sshd
sockstat -4 -6 | grep ssh
STEP 2

Disable only next-boot intent

sysrc sshd_enable="NO"
sysrc sshd_enable
STEP 3

Prove the running daemon is still available

service sshd status
pgrep -laf sshd
sockstat -4 -6 | grep ssh
service -e | grep sshd || true
sysrc sshd_enable
STEP 4

Restore persistent state

sysrc sshd_enable="YES"
sysrc sshd_enable
service -e | grep sshd
service sshd status
sockstat -4 -6 | grep ssh

Verify

  • sshd_enable changes YES → NO → YES while the current daemon continues running.
  • service -e reflects the persistent enablement change, and SSH remains reachable throughout.

Expected outcome

  • The learner can distinguish runtime process/socket state from rc.conf next-boot intent and restores the original safe configuration.

If it fails

  • If SSH is your only management path, use the VM console before changing remote-access state.
  • Do not reboot while sshd_enable is NO during this exercise.
Real-world connection

Many service incidents come from confusing current runtime state with persistent boot configuration; evidence from sysrc, service, pgrep and sockstat resolves that ambiguity.

Avoid these traps

Common mistakes

  • Making multiple unrelated changes before retesting.
  • Deleting state or logs as a first troubleshooting action.
Knowledge check

Can you explain it without looking back?

Open each answer only after you have tried to answer the question yourself.

1What is an evidence-first troubleshooting sequence?

Observe the error, identify the subsystem, collect state/logs, form a hypothesis, make one reversible change, and verify.

2Why can a running service still be disabled?

Runtime process state and persistent boot configuration are separate.

3Why are reversible changes preferred?

They limit blast radius and preserve a known path back to the previous state.

My Learning

Record your progress for this module.

Progress is saved in this browser immediately. When you sign in to My Learning, it can also sync across devices.

Not started

Attempt the core lab and knowledge checks before marking the module complete.