FreeBSD devctl Operations: Inspect and Change Device State Safely

devctl(8) changes the state of devices in FreeBSD’s kernel device hierarchy. It can request operations such as attach, detach, enable, disable, suspend, resume, driver selection, rescan, and bus-specific reset. That makes it useful for controlled device troubleshooting, but also means a command can interrupt a disk, network adapter, console, or child bus. Treat it as a state-changing kernel control tool, not as a harmless inventory command.

devctl is related to, but not the same as, devd(8). devctl requests or reports device-control operations. devd consumes event notifications and can run configured actions. A rule that logs a device event does not prove that an explicit detach is safe, and a successful devctl request does not prove a service above the device recovered.

Establish device identity and dependency scope

Start with read-only device-tree and event evidence:

devinfo -rv
dmesg | tail -100

devinfo -rv shows the kernel’s device tree and resources, while dmesg preserves the kernel’s reported attach and detach messages. Keep the exact FreeBSD release in the incident record because available commands and bus support can vary. Identify the target by its device name and parent bus, then corroborate it with model, serial, attachment messages, interface or disk state, and the workload using it. If you need live event monitoring, follow the release’s devctl(4) or devd(8) documentation rather than assuming a subcommand exists in every devctl(8) version.

Build the dependency tree before considering a control operation. Detaching a USB controller can remove several children. Detaching a PCI parent can affect a storage controller and every disk behind it. Suspending a device may require children to suspend first. A name in devinfo is not an isolated process that can be safely stopped.

For storage, inspect mounts, swap, ZFS pools, GEOM classes, and open descriptors. For networking, identify whether the target interface carries SSH, routing, jail traffic, or storage replication. For a console or keyboard, ensure another access method exists. If you cannot map the dependency tree, do not proceed with a state change.

Understand the verbs and their consequences

The manual defines individual operations against one device. attach asks the parent bus to attach a device; detach asks the driver to detach it; disable prevents normal use; enable enables it; suspend and resume alter power or operational state; rescan asks a bus to rediscover devices; and set or clear changes driver association. delete removes device state and reset uses a bus-specific reset method where implemented.

These verbs are not interchangeable. A rescan is not the same as forcing a detach and attach cycle. reset may affect descendants on a bus, and the manual documents bus-specific behavior and limitations. -f options bypass some checks; do not use them as a routine response to an operation failing. A refusal may indicate an active consumer or unsafe dependency, not a transient nuisance.

Read the complete installed devctl(8) entry for the exact command before use. In particular, check device argument forms, which buses implement reset, whether the operation is supported by the driver, and what a successful exit status means. A shell exit code confirms a request was accepted or completed according to the utility contract; it does not assert that the device is healthy.

Plan a device reprobe like a maintenance change:

Save the current device tree, logs, workload state, parent bus, and consumers.
Confirm alternate access, backups, and application-level failover.
Review the exact driver and bus support for the intended operation.
Change only one device at a time and record the output.
Re-read devinfo, dmesg, and subsystem state, then run an application check.

Prefer documented service-level actions before touching kernel devices. If a network stack is misconfigured, correcting the interface or route may be safer than resetting the NIC. If storage I/O is stalled, inspect CAM or NVMe diagnostics, GEOM dependencies, and pool health before detaching anything. A control operation is appropriate only when the failure is at the device state layer and the recovery path is understood.

Use a noncritical test device in a maintenance environment to learn the event and driver behavior. Do not rehearse a destructive detach on the only root disk, the only management NIC, or the sole console. On a remote production system, require out-of-band console access and a rollback plan that does not depend on the device being changed.

Failure modes and recovery

An attach can fail because the driver is unavailable, the device is disabled, a resource is occupied, firmware is missing, or the bus does not support the requested transition. Repeatedly retrying can produce noisy logs without changing the underlying condition. Capture the first error and inspect driver/module state, parent bus, resources, and firmware package requirements.

A detach can succeed while leaving an application degraded. A disk may disappear from a pool, a NIC may drop routes, or a USB serial device may vanish from a management workflow. Recovery requires checking both the device tree and the consumer. For storage, do not import or label a provider until its identity and pool state are clear. For networking, verify link, address, route, resolver, and reachability from the expected client path.

The manual documents limitations around devices that are explicitly detached or suspended and subsequent bus reset or system resume. A later reset or resume can cause a device to reattach or resume despite prior manual state. Do not treat an earlier detach as a persistent administrative disable. Re-check current device state after suspend/resume, bus reset, hotplug, and reboot.

If an operation returns an error, do not escalate directly to -f. Preserve the error, inspect open consumers and parent-child relationships, and determine whether the driver has a safe recovery path. A force option can remove a protection that exists specifically to prevent use-after-detach or data loss.

Keep devd automation separate

Use devd when the requirement is event-driven policy, such as logging a device arrival or starting a narrowly scoped helper. Keep the rule declarative and idempotent. Test it against the exact event properties available on the supported release and ensure repeated add/remove events do not trigger duplicate work.

Use devctl for an operator-requested state operation after reviewing impact. Do not build an automatic devd loop that repeatedly resets or reattaches a failing device. That can amplify a transient fault, race the driver, and make the system harder to recover. Any action script should log the event, apply strict matching, rate-limit itself, and return without blocking the event service.

For troubleshooting, capture devd logs separately from devctl results. An event can occur without an administrator invoking devctl, and an explicit state command can produce additional events. Correlating timestamps, device names, parent paths, and process IDs helps distinguish automatic hotplug behavior from a manual operation.

Production acceptance checklist

Before approving a device-state change, answer these questions in the change record: What exact device and parent are targeted? Which children and consumers depend on it? Which documented driver operation will run? What does the release-specific manual say about its effect? What redundant path or out-of-band console exists? Which read-only checks establish the before state? What measurable application check establishes recovery?

After the action, confirm the device appears once in the expected tree, the right driver is attached, resource assignments are sane, and kernel messages contain no new probe or detach errors. Validate the owning subsystem: submit a network request, perform a non-destructive storage read, or exercise the attached peripheral through its supported interface. Do not infer success solely from a green device node.

If the event cannot be repeated safely or there is no recovery path, stop before executing the control operation. Schedule a maintenance window, prepare out-of-band access, and test on equivalent hardware first. devctl gives administrators a precise control surface; operational safety still depends on understanding the tree and the workload above it.

Related:

Sources: