FreeBSD nvmecontrol Operations: Inventory Namespaces and Read Health Logs

FreeBSD exposes NVMe controllers and their namespaces through more than one driver path. The controller is commonly named nvme0, while storage namespaces can appear through the CAM-backed nda driver or through nvd. The exact device node depends on the configured driver and release. This distinction matters because a controller name used by nvmecontrol is not necessarily the disk node used by gpart, filesystems, ZFS, or a backup plan.

nvmecontrol is the FreeBSD utility for querying and managing NVM Express devices. Its read-only inventory, identify, and log-page commands can establish what the controller reports before an operator touches partitions or storage services. This guide stays on inspection and controlled testing. Namespace creation or deletion, format, reset, and firmware operations can interrupt access or destroy data; they require a separate maintenance plan and the exact controller vendor’s compatibility guidance.

Map the device stack before testing

Begin with the release and the utility’s inventory. Preserve the output with timestamps and do not infer a namespace node from the controller number:

freebsd-version -kru
nvmecontrol devlist
dmesg | grep -i nvme
geom disk list
gpart show -p

The devlist command reports controller and namespace device information as exposed by FreeBSD. Kernel messages help establish which driver attached. geom disk list and gpart show help map the host’s providers and partition scheme, but they do not replace NVMe identify data. Correlate the operating-system node with the drive’s serial number, model, namespace identifier, enclosure slot, and any stable GEOM label before a maintenance action.

FreeBSD can expose NVMe storage as CAM devices named ndaN or as nvdN, depending on the driver path and system configuration. A physical controller such as nvme0 can host one or more namespaces, and a namespace becomes a storage device only when active and attached through a driver. A disk called nda0 is not itself the NVMe controller identifier expected by every nvmecontrol subcommand. Read the command’s argument description and use the identifier shown by devlist.

Avoid relying on a device number that can change after hardware, firmware, boot order, or driver configuration changes. For scripts and runbooks, verify the serial/model and the current mapping immediately before operations. If inventory shows a namespace missing, capture the device tree and kernel log before rebooting, detaching, or resetting anything.

Read controller and namespace identity

Use identify to query controller data and namespace data separately. The exact options are defined by nvmecontrol(8); a typical controller and namespace inspection looks like this:

nvmecontrol identify nvme0
nvmecontrol identify -x nvme0ns1
nvmecontrol ns active nvme0
nvmecontrol ns allocated nvme0
nvmecontrol ns attached -n 1 nvme0

Use names and namespace identifiers exactly as reported by the local utility. The manual’s identify command can query a controller or namespace; -n selects a namespace identifier when needed, and zero can request controller identify data for a controller name. Hexadecimal output is useful for preserving raw fields but requires protocol-level interpretation; do not decode vendor-reserved bytes by guesswork.

Active, allocated, and attached namespaces are different views of controller state. A namespace may be allocated but not active, or not attached to the controller serving the host. The driver may create or remove device nodes dynamically as namespaces are activated or detached. Compare the utility’s state with kernel attach messages and actual /dev nodes. A missing partition table on a visible namespace differs from a namespace that the OS never attached.

Do not use namespace management commands on a production device just to test syntax. Creation, deletion, attachment, and detachment change controller state and may invalidate paths used by mounted filesystems, swap, pools, or applications. If an approved change requires one, identify all consumers first, check backups and redundancy, confirm controller support and namespace limits, and follow the vendor’s procedure.

Inspect standard log pages and health indicators

The NVMe specification defines standard log pages such as the Error Information Log, SMART/Health Information Log, and Firmware Slot Log. FreeBSD’s utility decodes supported pages; page 2 is the standard health and SMART information page:

nvmecontrol logpage -p 1 nvme0
nvmecontrol logpage -p 2 nvme0
nvmecontrol logpage -p 3 nvme0

Preserve the controller and namespace context, time, and full output. Some log data is controller-scoped and some namespace-scoped; use the device identifier required by the installed manual. A vendor-specific page may reuse an identifier with vendor-specific meaning. Do not compare raw page numbers across vendors without checking the supported page list and controller documentation.

Health fields need context. Temperature, available spare, percentage used, media errors, and data-unit counters have protocol-defined meanings, but thresholds and operational impact depend on the device and workload. A single healthy summary does not guarantee that the drive will not fail. A nonzero error-log count is not automatically proof of a media failure; correlate it with decoded status, kernel errors, SMART history, link resets, power events, workload, and redundancy status.

If smartmontools is installed, smartctl can provide another interface to supported NVMe health data. Preserve its version and command options and compare the underlying fields rather than assuming two tools use identical labels or units. Do not treat the SMART output as a substitute for an application-level integrity check, ZFS scrub, UFS validation, or verified backup.

Use performance tests only as a controlled experiment

nvmecontrol perftest can generate reads or writes for a specified duration and thread count. It is not a harmless inventory command: write mode creates I/O, and either mode can affect production latency or device temperature. The manual’s examples are syntax references, not recommendations for production load.

Before a test, establish the namespace, data-consistency requirements, workload owner, baseline latency, queue depth, CPU activity, thermal conditions, and maintenance window. Use the device and mode supported by the exact release manual. A benchmark that writes to a mounted namespace can corrupt a filesystem or database if its target semantics are misunderstood. Never aim a raw write test at an active production block device without a reviewed tool-specific plan and an isolated target.

For workload validation, prefer a disposable empty test namespace or a dedicated test device with no mounted data. Record block size, direction, thread count, duration, device temperature, result units, OS release, kernel, controller firmware, and power state. Repeat with the same configuration and compare against an agreed baseline. A peak throughput number alone does not establish tail latency, sustained performance, endurance, or application behavior.

Separate read-only diagnostics from maintenance operations

The nvmecontrol manual also documents operations such as controller reset, firmware download or activation, format, and namespace changes. These are not ordinary diagnostics. A reset can temporarily remove namespaces from the system. A firmware activation may need a reset and can alter behavior across all namespaces. A format can erase user data and change metadata or protection settings. Do not include such operations in an automated “health check.”

If a vendor directs a firmware update, verify the exact model and current firmware, image authenticity and compatibility, supported activation slot, power continuity, multipath/failover plan, backup state, and recovery method. Capture pre-change identify and health logs. Obtain approval from the storage owner and schedule the interruption. Follow the vendor and FreeBSD manuals for that device; a valid file path is not evidence that an image is safe for the drive.

Before any reset or namespace operation, identify mounted filesystems, swap, ZFS vdevs, GEOM consumers, database files, and attached jails or VMs. Confirm that redundancy is healthy and that all affected paths have been accounted for. If the host is remote, retain an alternate management path and physical or out-of-band recovery. Do not forcibly detach the device to clear a busy error.

Triage common symptoms by layer

Controller is present but the disk node is absent. Check namespace active/attached state, driver messages, module or kernel configuration, and the mapping shown by devlist. Do not partition the controller character device.

Disk node exists but gpart shows no partitions. Confirm that the correct namespace and expected partition scheme were selected. A blank table, raw namespace, unsupported metadata, or wrong device mapping can produce the same surface symptom. Do not run gpart create until the owner confirms the device is intentionally empty.

Error log grows or kernel reports timeouts. Capture health logs, device identity, dmesg, and storage topology. Correlate with thermal or power events, PCIe link stability, firmware, enclosure, and workload. Preserve counters before reboot or reset because a recovery action can change the evidence.

SMART and host counters disagree. Compare sampling times, controller/namespace scope, units, and tool version. Health pages can be cumulative; counters from different sources may not reset together. A discrepancy is a reason to preserve output and consult the vendor, not to clear logs.

Acceptance and evidence

An accepted NVMe inventory records controller serial/model/firmware, namespace IDs and capacity, FreeBSD driver path, operating-system node, GEOM identity, pool or filesystem consumer, and standard health-log output. A health review also documents what fields were compared, thresholds used, sample time, and who owns the replacement decision. If a performance test is required, preserve its configuration and use an isolated target.

The strongest operational report says what the host observed and what it could not prove. FreeBSD logs and identify data can show what the controller exposed to the OS; they cannot independently certify NAND health, a vendor firmware defect, or the integrity of application data. Pair host diagnostics with vendor telemetry, filesystem or pool checks, application validation, and a tested recovery path before concluding that storage is healthy.

Related:

Sources: