| 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]
[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, 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]
[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.
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¶
NOTES¶
- 1.
- CONFIG.md
| nvme-stas 3.1 |