Scroll to navigation

NVME-STAS.CONF(5) NVME-STAS.CONF(5)

NAME

nvme-stas.conf - nvme-stas connectivity configuration file

SYNOPSIS

/etc/nvme/nvme-stas.conf

/etc/nvme/nvme-stas.conf.d/*.conf

DESCRIPTION

This file states which NVMe-oF controllers stafd(8) and stacd(8) should connect to, and with what parameters. Daemon behaviour — tracing, mDNS, fabric zoning — is configured separately, in stafd.conf(5) and stacd.conf(5). Excluding a controller, regardless of how it was included, is independent of this file and is described in nvme-stas(7).

The format is libnvme's, and is parsed by libnvme itself, so nvme-stas, the nvme-cli tools and nvme-discoverd all read one format through one parser. For the design rationale behind the format, see libnvme's CONFIG.md[1] design document.

You may find more than one config file in /etc/nvme/. nvme-stas.conf belongs to nvme-stas. nvme-fabrics.conf belongs to the nvme-cli tools and nvme-discoverd. A host must be able to run nvme-stas and nvme-discoverd side by side, each connecting its own controllers, with neither acting on the other's configuration.

/etc/nvme/nvme-stas.conf is optional. If it does not exist, nvme-stas configures no controllers — that is not an error. Controllers discovered over mDNS, or learned from a Discovery Log Page, need no entry here.

Drop-ins are read from /etc/nvme/nvme-stas.conf.d/*.conf, one host persona per file.

The installed file is commented throughout except for the Discovery Controller keep-alive timeout. The kernel applies its 30 second discovery default only when it recognises the well-known discovery NQN, so a Discovery Controller with its own unique NQN would otherwise get the 5 second I/O default; setting it explicitly gives every Discovery Controller the same keep-alive.

CONFIGURATION FILE FORMAT

A plain text file divided into sections, with entries in the style key=value. Empty lines and lines starting with # are ignored. Keys are named exactly as the equivalent nvme connect options are named.

An empty assignment (key =) is meaningful: it resets a parameter so that the kernel's own default applies, rather than inheriting a value set at an outer level.

SECTIONS

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

Default connection parameters for a whole class of controllers. There is deliberately no type-agnostic section: some parameters want a different default per class — most clearly the keep-alive timeout — so a value that applies to both is simply written in both sections.

[Host]

The host identity the connections in this file are made under: hostnqn, hostid, hostsymname, and the KX-HMAC-CHAP secrets. At most one per file.

Omit the section, or a key, to use the system identity (/etc/nvme/hostnqn and /etc/nvme/hostid). A different identity is a different persona and belongs in its own drop-in file, which must state its hostnqn explicitly, and normally needs its own hostid too: a hostnqn on its own is an incomplete identity, and the connection will fail rather than borrow a hostid from elsewhere. The one exception is a uuid:-form NQN (nqn.2014-08.org.nvmexpress:uuid:<UUID>) — its trailing UUID is already a valid host ID by construction (NVMe Base Specification 4.7, NVMe-oF Boot HostNQN and HostID TP4126), so nvme-stas recovers the host ID from it instead of treating it as missing.

nvme-stas takes a connection's identity whole or not at all. It never pairs a configured host NQN with the system's host ID, which would invent an identity nobody configured — recovering a host ID already encoded in a uuid: host NQN is reading the identity as given, not inventing one.

[Discovery Controller]

A Discovery Controller for stafd to connect. Repeat the section for each one. Its nqn is optional; omitted, it means the well-known discovery NQN (nqn.2014-08.org.nvmexpress.discovery).

[Subsystem]

An I/O subsystem for stacd to connect, named by its nqn. Repeat the section for each one.

Each controller= line is one path to the subsystem; repeating the key expresses multipath. There is no upper bound and no power-of-two rule.

ADDRESSES

Each path is a controller= line whose value is a semicolon-separated list of key=value pairs, using the nvme connect option names:

controller = transport=[trtype];traddr=[traddr];trsvcid=[trsvcid];host-traddr=[traddr];host-iface=[iface]

transport and traddr are required; the rest are optional. The subsystem NQN is not part of the address: it comes from the section. Beyond addressing, any nvme connect option may appear on the line as a per-path override, with the exception of the security parameters.

PERSISTENT DISCOVERY CONNECTIONS

persistent states whether a Discovery Controller's connection is held open. It is accepted on a [Discovery Controller] section, on [Discovery Controller Defaults] and on a controller= line, and only on those: it has no meaning for an I/O controller.

It takes no, auto or force, and defaults to auto — hold the connection open wherever the Discovery Controller reports, through the EPCSD flag of its own discovery log page entry, that it supports one.

A Discovery Controller that does not support a persistent connection is parked: stafd disconnects it, keeps its log pages, and polls them on a timer, since a disconnected controller cannot report that they changed. The polling period is epcsd-poll-interval-minutes of stafd.conf(5).

PRECEDENCE

A parameter is resolved most-specific-first: controller= line, then the endpoint section, then [Host], then the type defaults, then the kernel default.

[Host] sits above the type defaults on purpose: the ladder orders by ownership, not category. A key in [Host] was written for that persona specifically, so it follows that persona's connections.

A drop-in may carry its own copy of either defaults section, scoped to that drop-in's own connections. Nothing leaks to sibling drop-ins or back to the top level, so the result never depends on the order drop-ins are read in.

SECURITY PARAMETERS

kxchap-secret, kxchap-ctrl-secret, tls, tls-key, tls-key-identity, keyring and concat are bound to the host-and-subsystem relationship rather than to a path, so they belong on [Host] or on an endpoint section and are not accepted on a controller= line.

KX-HMAC-CHAP secrets have no keyring-reference form, so they sit in the clear in this file.

VALIDATION

The configuration is validated when it is read. A file that does not validate is rejected and the last known good configuration keeps running, so a fat-fingered edit never tears down working connections. Unknown keys are ignored rather than rejected, so a newer key does not break an older parser.

EXAMPLE

[Discovery Controller Defaults]
keep-alive-tmo = 30
ctrl-loss-tmo  = 600
[I/O Controller Defaults]
ctrl-loss-tmo  = 600
[Host]
hostsymname = lab-host-01
[Discovery Controller]
controller = transport=tcp;traddr=192.168.1.10;trsvcid=8009
[Subsystem]
nqn           = nqn.2024-01.com.example:vol1
ctrl-loss-tmo = 1800
controller    = transport=tcp;traddr=192.168.1.20;trsvcid=4420;host-iface=eth0
controller    = transport=tcp;traddr=192.168.1.21;trsvcid=4420;host-iface=eth1

SEE ALSO

stafd.conf(5), stacd.conf(5), stafd(8), stacd(8)

NOTES

1.
CONFIG.md
nvme-stas 3.1