| 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, exclusions — is configured separately, in stafd.conf(5) and stacd.conf(5).
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.
nvme-stas reads its own file. /etc/nvme/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.
The file 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]
[Host]
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. Give a persona both a hostnqn and a hostid: without an explicit host ID the kernel generates one that changes on every reboot, which breaks persistent reservations.
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.
[Discovery Controller]
[Subsystem]
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.
Note that this default differs from libnvme's, where an unset value behaves as no. A daemon whose purpose is to be told when discovery log pages change cannot default to disconnecting. It is the same choice nvme-discoverd makes.
A Discovery Controller that does not support a persistent connection is parked: stafd disconnects it, keeps its log pages, and re-reads them on a timer, since a disconnected controller cannot report that they changed. How often 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¶
| nvme-stas 3.0 |