Collect OpenBSD Diagnostic Evidence

Synopsis #

Useful OpenBSD diagnostics identify the failing layer, preserve the first error, and include enough system context to reproduce the problem. A complete dump of /etc, /var/log, or a user profile usually adds secrets without clarifying the failure. This guide explains what to collect for troubleshooting, support requests, and bug reports.

Collect evidence as soon as practical after the failure. Rebooting, restarting a daemon, loading a new PF ruleset, or updating packages can erase the state that explains the problem.

Start with a Reproduction Record #

Write down:

  • the intended result;
  • the exact command or event;
  • the first error and exit status;
  • whether the problem is repeatable;
  • the last known working state;
  • changes made before the failure;
  • the recovery actions already attempted.

Do not paraphrase the first error when exact text is available. Record timestamps with the applicable timezone so log entries can be correlated.

Record Release and Hardware Context #

Collect the release, architecture, kernel messages, and concise hardware properties:

uname -a
  # Record the running release, architecture, and kernel identity
sysctl hw.machine hw.model hw.ncpu hw.ncpuonline hw.physmem
  # Record stable hardware properties
dmesg
  # Record the complete kernel message buffer

The complete dmesg is important for driver attachment, firmware, interrupt, storage, and resume problems. Do not reduce it to one matching line in the final evidence set.

For PCI and USB device problems, use the base-system inventory tools:

doas pcidump -v
  # Identify PCI devices and attached drivers
usbdevs -v
  # Identify USB devices and interfaces

Review serial numbers and other identifiers before publishing command output.

Collect Resource and Process Evidence #

Capture a short interval instead of a single busy-system snapshot:

vmstat 5 12
  # Record CPU, memory, paging, interrupt, and disk activity
ps aux
  # Record process state and resource use
df -h
  # Record filesystem capacity
df -i
  # Record inode consumption

Use systat(1) interactively to select the relevant view. A resource symptom must be correlated with the process, filesystem, device, or traffic that consumes it.

Collect Service and Log Evidence #

List failed enabled daemons and inspect the affected service:

doas rcctl ls failed
  # Identify enabled daemons that are not running
doas rcctl check exampled
  # Check the affected daemon, replacing the placeholder
doas tail -n 100 /var/log/daemon
  # Review recent daemon messages
doas tail -n 100 /var/log/messages
  # Review recent system messages

exampled is a placeholder. Use the actual daemon name and its documented configuration test before restarting it. Preserve the relevant time window from /var/log/authlog, /var/log/maillog, or another configured log only when it relates to the failure.

Do not publish authentication logs without removing account names, source addresses, key fingerprints, and other identifying data as appropriate.

Collect Network Evidence by Layer #

Record interface state, routes, counters, sockets, PF rules, and states:

ifconfig
  # Record addresses, link state, media, and interface errors
route -n show
  # Record routes without DNS lookups
netstat -in
  # Record interface packet and error counters
netstat -na
  # Record listening and connected sockets without name lookups
doas pfctl -vvsr
  # Record active rules and counters
doas pfctl -ss
  # Record active PF states when relevant

PF output, routes, and interface configuration can disclose internal topology. Share the smallest redacted subset that preserves the failed path. Packet captures can contain credentials and application data; use restrictive filters and protect capture files.

Troubleshoot PF, NAT, and Routing provides the full layer-by-layer procedure.

Collect Storage Evidence without Mutating Disks #

Use read-only commands first:

sysctl hw.disknames
  # Map kernel disk names to stable identifiers
mount
  # Record mounted filesystems and options
df -h
  # Record filesystem capacity
doas disklabel sd0
  # Inspect the selected disklabel after verifying the device

Replace sd0 only after identifying the correct disk. Do not run fsck, newfs, bioctl creation commands, or disklabel edits merely to gather evidence. Manage Storage and the recovery guides explain when to take filesystems offline and how to identify disks before changing them.

Record Package and Update State #

Capture installed package identity and outstanding base patches:

pkg_info
  # Record exact installed package versions
doas syspatch -c
  # List available base-system binary patches

Package lists can reveal application roles. Include only relevant entries in a public report when a complete inventory is unnecessary.

Prepare an OpenBSD Problem Report #

sendbug(1) creates the OpenBSD problem-report template and includes required system context. Read the current manual and the official reporting guidance before submission.

Before sending any report:

  • reproduce on a supported release or a current snapshot when the project requests it;
  • include a complete dmesg;
  • identify local patches and non-default configuration;
  • attach the smallest reproducible test case;
  • remove passwords, private keys, tokens, cookies, message content, and unrelated personal data;
  • state whether the report concerns base OpenBSD or a third-party package.

Package problems may belong to the port maintainer or ports mailing list rather than the base-system bug tracker. The installed package README can specify the maintained debugging path.

Report a bug