Begin with evidence #
Before changing configuration, record the installed and running release, the complete error, and the service state. A useful initial record often includes:
$ freebsd-version -kru
$ uname -a
# service service-name status
Replace service-name with the rc service being investigated. Then inspect that service’s log and manual page. Avoid applying a tunable or compatibility workaround until the failing component has been identified.
Choose the failing layer #
Updates, packages, and boot #
- Recover an interrupted freebsd-update run resumes or rolls back from recorded state.
- Resolve a package repository or ABI mismatch checks architecture, release, branch, and repository policy.
- Recover with a ZFS boot environment selects or activates a known boot environment.
- Diagnose the FreeBSD boot path separates firmware, loader, kernel, root-filesystem, and service failures.
Network and service exposure #
- Diagnose DNS, routing, and firewall paths proves resolution, route, packet, firewall, and listening-service layers in order.
- Diagnose network mbuf exhaustion
requires measured exhaustion before considering
kern.ipc.nmbclusters. - Bind a service to a low port compares MAC policy, redirection, and service privilege boundaries.
Desktop and devices #
- Diagnose audio output or input separates detection, default device, mixer, permissions, and applications.
- Diagnose webcamd, cuse, and a webcam traces attachment through the application-facing device.
- Fix USB device permissions narrowly avoids opening every device node.
The Linux binary compatibility guide includes the initial diagnostic path for Linux binaries that do not start.