libnvme-rs

Safe, idiomatic Rust bindings for the Linux libnvme C library — the userspace NVMe management library that backs nvme-cli.

cargo add libnvme

use libnvme::Root;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = Root::scan()?;
    for host in root.hosts() {
        for subsys in host.subsystems() {
            for ctrl in subsys.controllers() {
                println!("{} {}", ctrl.name()?, ctrl.model()?);
                for ns in ctrl.namespaces() {
                    println!("  {} ({} bytes)", ns.name()?, ns.size_bytes());
                }
            }
        }
    }
    Ok(())
}

A more complete nvme list-style example lives at libnvme/examples/list_nvme.rs:

cargo run --example list_nvme -p libnvme

Status

Alpha — API will change. 0.x.y releases will break compatibility on minor-version bumps. Pin to an exact patch version (= 0.6.1) if you depend on this and don't want surprises.

This is Linux-only. libnvme doesn't exist on Windows or macOS.

Requirements

• Linux x86_64 or aarch64
• libnvme ≥ 1.6 (apt install libnvme-dev on Ubuntu 24.04+; equivalent on Fedora/Arch)
• clang and libclang-dev for bindgen at build time
• Rust 1.85+ (rust-version in Cargo.toml)

Workspace layout

What's covered

Enumeration and properties

• Enumerate the handle tree: hosts → subsystems → controllers → namespaces → paths
• Controller properties: name, model, serial, firmware, transport, address, state, plus sysfs fields (numa_node, queue_count, sq_size, phy_slot, subsystem_nqn, traddr / trsvcid / host_traddr / host_iface)
• Namespace properties: name, generic name, NSID, LBA size and count, metadata size, utilization, CSI, total size, UUID, NGUID, EUI-64, model/serial/firmware mirrors
• Subsystem properties: name, NQN, type, plus version-gated model/firmware/iopolicy/application/serial
• Host basic properties (HostID, NQN, etc.)
• Multipath / ANA Path iteration on both Controller::paths and Namespace::paths

Admin commands (read)

• Identify Controller (Controller::identify) — vendor/subsystem IDs, NVMe spec version, FRU GUID, OACS, FRMW, LPA, NPSS, temperature thresholds, HMB sizes, TNVMCAP/UNVMCAP, NN, and more
• Identify Namespace (Namespace::identify) — size/capacity/utilization, NSFEAT, NLBAF, FLBAS, data-protection fields, NVMCAP, NGUID/EUI-64, per-format LbaFormat lookup
• SMART / Health log page (Controller::smart_log) — temperature, available spare, percentage used, data units read/written (u128), host commands, power cycles, power-on hours, unsafe shutdowns, media errors, per-sensor temperatures
• Firmware Slot log page (Controller::fw_slot_log) — active slot, next-activate slot, slot 1..=7 firmware revisions
• Error Information log page (Controller::error_log) — ring-buffer of recent error entries
• Generic Get Log Page (Controller::get_log_page::<T>) — fetch any fixed-size log page by LID
• Get LBA Status (Controller::get_lba_status) — NVMe 1.4+ LBA Status Descriptor query
• Get Property (Controller::get_property) — Fabrics controller register read

Admin commands (destructive)

• Format NVM (Namespace::format() builder) — LBA-format selection, secure erase (None / UserData / Cryptographic), protection-info, metadata settings, timeout
• Sanitize NVM (Controller::sanitize() builder) — BlockErase / Overwrite / CryptoErase, AUSE, pass count, invert, pattern, NVMe 2.0 EMVS (version-gated)
• Device Self-Test (Controller::self_test) — Short / Extended / HostInitiated / Vendor-Specific / Abort
• Firmware Download / Commit (Controller::fw_download, Controller::fw_commit) — whole-buffer image transfer + slot/action selection
• Namespace management (Controller::create_namespace, delete_namespace, attach_namespace, detach_namespace) — full lifecycle on controllers that advertise OACS Namespace Management
• Lockdown (Controller::lockdown) — NVMe 2.0+ interface restriction
• Set Property (Controller::set_property) — Fabrics controller register write

Get/Set Features (NVMe admin features)

• All 32 Set Features and 37 Get Features variants under Controller::features(): arbitration, power management, LBA range, temperature thresholds, error recovery, volatile write cache, number of queues, interrupt coalescing/config, async event, auto-PST, timestamp, HMB, KATO, HCTM, NOPSC, RRL, PLM config/window, host behavior, sanitize, endurance event, host ID, reservation mask/persistence, namespace write protection, IOCS profile

Security

• Security Send / Receive (Controller::security_send, security_receive) — TCG Opal / Pyrite / arbitrary security protocol payloads

Fabrics (NVMe-oF)

• Host management — Root::default_host, Root::lookup_host(hostnqn, hostid), plus free functions generate_hostnqn, generate_hostid, hostnqn_from_file, hostid_from_file
• Connect (Host::connect(Transport, subsysnqn) builder) — TCP / RDMA / FC / Loop, with chainable setters for traddr, trsvcid, host_traddr, host_iface, queue_size, nr_io_queues, keep_alive_tmo, reconnect_delay, ctrl_loss_tmo, hdr_digest, data_digest, tls, persistent, discovery
• Disconnect (Controller::disconnect) — tear down a fabrics connection
• Reset (Controller::reset) — controller reset
• Discovery — Controller::is_discovery_controller, Controller::discovery_log(max_retries) returning a DiscoveryLog with iterable DiscoveryLogEntry
• Authentication — Controller::set_dhchap_host_key, set_dhchap_key, set_tls_key, set_tls_key_identity, set_keyring (version-gated)
• Persistence — Controller::is_persistent, set_persistent

Generic passthru (escape hatch)

• Controller::admin_passthru(args) and Controller::io_passthru(args) — issue any admin- or I/O-class command not yet exposed by a typed helper. Means no missing function blocks a user — drop down to passthru, drop down to libnvme-sys for raw bindings, or open an issue requesting a typed wrapper.

Roadmap

Provider-Specific Quirks

Some drives may have issues that arise due to specific changes issued by their provider. If you feel this is the case with your drive, feel free to open an issue detailing the problem.

Testing

There's a QEMU-based fixture in tests/qemu/ that boots an Ubuntu 24.04 guest with a 1 GiB virtual NVMe controller attached as /dev/nvme0, so destructive operations (Format NVM, namespace create/delete, firmware commit) can be exercised against a real NVMe protocol stack without touching the host's drives. See tests/qemu/README.md for the workflow.

License

Dual-licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.