nvme-fabrics.conf(5)

# nvme-fabrics.conf(5) Manual Page

## NAME

nvme-fabrics.conf - NVMe-oF connection configuration file format

## SYNOPSIS

    /usr/local/etc/nvme/nvme-fabrics.conf
    /usr/local/etc/nvme/nvme-fabrics.conf.d/*.conf

## DESCRIPTION

An INI-format file describing which NVMe over Fabrics (NVMe-oF) controllers a host should connect to, and with what parameters. It is read by nvme connect-all, nvme discover and nvme connect, by the nvme-discoverd daemon, and (through the Python bindings) by nvme-stas.

A configuration is a main file plus an optional drop-in directory, the same foo.conf + foo.conf.d/ pattern systemd uses. Both parts are read independently, and either may be absent; an absent configuration is not an error; it simply yields no connections.

--config FILE (on connect-all/discover/connect) names the main file; its drop-in directory is always FILE.d/. Omitting --config uses the default path above.

## SECTIONS

Each section is one or more key = value lines. An empty value (key =) resets the key to the kernel default, overriding whatever an outer scope set (see RESETTING A KEY below). Unknown keys are ignored. Boolean values accept 1/yes/y/true/t/on and 0/no/n/false/f/off (case-insensitive).

[Host]

  Optional, at most one per file. The identity used by every connection in that file: hostnqn, hostid, hostsymname, plus any SECURITY key below. A file with no [Host] connects as the system default identity (/usr/local/etc/nvme/hostnqn / hostid). A drop-in that defines [Host] must set hostnqn explicitly.

[Discovery Controller Defaults], [I/O Controller Defaults]

  Optional, at most one of each per file. Default TUNABLE values for connections of that class, drawn from below. A drop-in’s copy overlays the top-level file’s, for that drop-in’s own connections only.

[Discovery Controller]

  One Discovery Controller to connect to. Repeatable. nqn = defaults to the well-known discovery NQN if omitted.

[Subsystem]

  One I/O subsystem to connect to, named by nqn =. Repeatable.

Both endpoint sections accept any TUNABLE or SECURITY key as a per-section override, plus one or more controller = lines (below).

## CONTROLLER LINES

Each controller = line under a [Discovery Controller] or [Subsystem] section is one path to that endpoint; repeating the key expresses multipath (native NVMe multipath groups all paths sharing a subsysnqn). The value is a ;-separated key=value list:

    controller = transport=tcp;traddr=10.0.0.9;trsvcid=4420;host-iface=eth0

transport and traddr are required; trsvcid, host-traddr and host-iface are optional. Any TUNABLE key may also appear on the line as a per-path override — SECURITY keys may not, since they are bound to the (host, subsystem) pair, not to a single path.

## KEYS

TUNABLE (type default, [Host], endpoint section, or controller = line):

    nr-io-queues, nr-write-queues, nr-poll-queues, queue-size,
    keep-alive-tmo, reconnect-delay, ctrl-loss-tmo, fast-io-fail-tmo,
    tos, duplicate-connect, disable-sqflow, hdr-digest, data-digest

SECURITY ([Host] or endpoint section only, never a controller = line):

    tls, tls-key, tls-key-identity, keyring, concat, kxchap-secret,
    kxchap-ctrl-secret

IDENTITY ([Host] only):

    hostnqn, hostid, hostsymname

Every key here is the same name as its nvme connect long option (hyphenated). See nvme-connect(1) for what each one means.

## RESETTING A KEY

An empty assignment (key =) resets that key to the kernel default, undoing whatever an outer scope (a *Defaults section or [Host]) set. This differs from simply not writing the key, which instead inherits through the cascade below.

## PRECEDENCE

A key resolves most-specific first:

    controller = line > endpoint section > [Host] > type defaults > kernel default

The type-defaults level is chosen by the connection’s class: a Discovery Controller draws from [Discovery Controller Defaults], an I/O Controller from [I/O Controller Defaults].

## EXAMPLE

    # /usr/local/etc/nvme/nvme-fabrics.conf

    [Discovery Controller Defaults]
    keep-alive-tmo = 30

    [I/O Controller Defaults]
    keep-alive-tmo = 5

    [Host]
    hostsymname = lab-host-01

    [Discovery Controller]
    controller = transport=tcp;traddr=192.168.1.10;trsvcid=8009

    [Subsystem]
    nqn        = nqn.2024-01.com.example:data.vol1
    controller = transport=tcp;traddr=192.168.1.20;trsvcid=4420
    controller = transport=tcp;traddr=192.168.1.21;trsvcid=4420

See /usr/local/etc/nvme/nvme-fabrics.conf.sample for a longer, commented example.

## SEE ALSO

nvme-connect-all(1) nvme-discover(1) nvme-connect(1) nvme-config-convert(1) https://github.com/linux-nvme/nvme-cli/blob/master/libnvme/design/CONFIG.md

## NVME

Part of the nvme-user suite