1STAFD.CONF(5) STAFD.CONF(5)
2
3
4
6 stafd.conf - stafd(8) configuration file
7
9 /etc/stas/stafd.conf
10
12 When stafd(8) starts up, it reads its configuration from stafd.conf.
13
15 stafd.conf is a plain text file divided into sections, with
16 configuration entries in the style key=value. Spaces immediately before
17 or after the = are ignored. Empty lines are ignored as well as lines
18 starting with #, which may be used for commenting.
19
21 [Global] section
22 The following options are available in the [Global] section:
23
24 tron=
25 Trace ON. Takes a boolean argument. If true, enables full code
26 tracing. The trace will be displayed in the system log such as
27 systemd's journal. Defaults to false.
28
29 hdr-digest=
30 Enable Protocol Data Unit (PDU) Header Digest. Takes a boolean
31 argument. NVMe/TCP facilitates an optional PDU Header digest.
32 Digests are calculated using the CRC32C algorithm. If true, Header
33 Digests are inserted in PDUs and checked for errors. Defaults to
34 false.
35
36 data-digest=
37 Enable Protocol Data Unit (PDU) Data Digest. Takes a boolean
38 argument. NVMe/TCP facilitates an optional PDU Data digest. Digests
39 are calculated using the CRC32C algorithm. If true, Data Digests
40 are inserted in PDUs and checked for errors. Defaults to false.
41
42 kato=
43 Keep Alive Timeout (KATO) in seconds. Takes an unsigned integer.
44 This field specifies the timeout value for the Keep Alive feature
45 in seconds. Defaults to 30 seconds for Discovery Controller
46 connections and 120 seconds for I/O Controller connections.
47
48 ip-family=
49 Takes a string argument. With this you can specify whether IPv4,
50 IPv6, or both are supported when connecting to a Controller.
51 Connections will not be attempted to IP addresses (whether
52 discovered or manually configured with controller=) disabled by
53 this option. If an invalid value is entered, then the default (see
54 below) will apply.
55
56 Choices are ipv4, ipv6, or ipv4+ipv6.
57
58 Defaults to ipv4+ipv6.
59
60 queue-size=
61 Takes a value in the range 16...1024.
62
63 Overrides the default number of elements in the I/O queues created
64 by the driver. This option will be ignored for discovery, but will
65 be passed on to the subsequent connect call.
66
67 Note: This parameter is identical to that provided by nvme-cli.
68
69 Defaults to 128.
70
71 reconnect-delay=
72 Takes a value in the range 1 to N seconds.
73
74 Overrides the default delay before reconnect is attempted after a
75 connect loss.
76
77 Note: This parameter is identical to that provided by nvme-cli.
78
79 Defaults to 10. Retry to connect every 10 seconds.
80
81 ctrl-loss-tmo=
82 Takes a value in the range -1, 0, ..., N seconds. -1 means retry
83 forever. 0 means do not retry.
84
85 Overrides the default controller loss timeout period (in seconds).
86
87 Note: This parameter is identical to that provided by nvme-cli.
88
89 Defaults to 600 seconds (10 minutes).
90
91 disable-sqflow=
92 Takes a boolean argument. Disables SQ flow control to omit head
93 doorbell update for submission queues when sending nvme
94 completions.
95
96 Note: This parameter is identical to that provided by nvme-cli.
97
98 Defaults to false.
99
100 ignore-iface=
101 Takes a boolean argument. This option controls how connections with
102 Discovery Controllers (DC) are made.
103
104 DCs are automatically discovered using DNS-SD/mDNS. mDNS provides
105 the DC's IP address and the interface on which the DC was
106 discovered.
107
108 There is no guarantee that there will be a route to reach that DC.
109 However, we can use the socket option SO_BINDTODEVICE to force the
110 connection to be made on a specific interface instead of letting
111 the routing tables decide where to make the connection.
112
113 This option determines whether stafd will use SO_BINDTODEVICE to
114 force connections on an interface or just rely on the routing
115 tables. The default is to use SO_BINDTODEVICE, in other words,
116 stafd does not ignore the interface by default.
117
118 Defaults to false.
119
120 pleo=
121 Port Local Entries Only. Takes a string argument enabled or
122 disabled. This option is sent in the LSP field (Log SPecific) of
123 the Get Discovery Log Page (DLP) command. It is used by stafd to
124 tell Discovery Controllers (DC) whether the response to a Get DLP
125 command should contain all the NVM subsystems or only those
126 reachable by the host on the interface where the Get DLP command
127 was issued by the host.
128
129 This parameter was introduced in TP8010. When pleo=enabled, then
130 the DC shall return records for only NVM subsystem ports that are
131 presented through the same NVM subsystem port that received the Get
132 Log Page command. When pleo=disabled, then the DC may return all
133 the NVM subsystem ports that it holds, even those that can only be
134 reached on NVM subsystem ports that did not receive the Get Log
135 Page command. In other words, the host may not even be able to
136 reach those subsystems.
137
138 Defaults to enabled.
139
140 [Service Discovery] section
141 The following options are available in the [Service Discovery] section:
142
143 zeroconf=
144 Enable zeroconf provisioning using DNS-SD/mDNS. Takes a string
145 argument enabled or disabled.
146
147 When enabled, the default, stafd makes a request with the Avahi
148 daemon to locate Discovery Controllers using DNS-SD/mDNS.
149
150 Discovery Controllers that support zeroconf advertise themselves
151 over mDNS with the service type _nvme-disc._tcp.
152
153 Defaults to true.
154
155 [Discovery controller connection management] section
156 The following options are available in the [Discovery controller
157 connection management] section:
158
159 persistent-connections=
160 Takes a boolean argument. Whether connections to Discovery
161 Controllers (DC) are persistent. When true, connections initiated
162 by stafd will persists even when stafd is stopped. When false,
163 stafd will disconnect from all DCs it is connected to on exit.
164
165 Defaults to false.
166
167 zeroconf-connections-persistence=
168 Takes a unit-less value in seconds, or a time span value such as
169 "72hours" or "5days". A value of 0 means no persistence. In other
170 words, configuration acquired through zeroconf (mDNS service
171 discovery) will be removed immediately when mDNS no longer reports
172 the presence of a Discovery Controller (DC) and connectivity to
173 that DC is lost. A value of -1 means that configuration acquired
174 through zeroconf will persist forever.
175
176 This is used for the case where a DC that was discovered through
177 mDNS service discovery no longer advertises itself through mDNS and
178 can no longer be connected to. For example, the DC had some
179 catastrophic failure (e.g. power surge) and needs to be replaced.
180 In that case, the connection to that DC can never be restored and a
181 replacement DC will be needed. The replacement DC will likely have
182 a different NQN (or IP address). In that scenario, the host won't
183 be able to determine that the old DC is not coming back. It won't
184 know either that a newly discovered DC is really the replacement
185 for the old one. For that reason, the host needs a way to "age"
186 zeroconf-acquired configuration and remove it automatically after a
187 certain amount of time. This is what this parameter is for.
188
189 Defaults to 72hours.
190
191 [Controllers] section
192 The following options are available in the [Controllers] section:
193
194 controller=
195 Controllers are specified with the controller option. This option
196 may be specified more than once to specify more than one
197 controller. The format is one line per Controller composed of a
198 series of fields separated by semi-colons as follows:
199
200 controller=transport=[trtype];traddr=[traddr];trsvcid=[trsvcid];host-traddr=[traddr],host-iface=[iface];nqn=[nqn]
201
202
203 Fields
204 transport=
205 This is a mandatory field that specifies the network fabric
206 being used for a NVMe-over-Fabrics network. Current trtype
207 values understood are:
208
209 Table 1. Transport type
210 ┌───────┬────────────────────────────┐
211 │trtype │ Definition │
212 ├───────┼────────────────────────────┤
213 │rdma │ The network fabric is an │
214 │ │ rdma network (RoCE, iWARP, │
215 │ │ Infiniband, basic rdma, │
216 │ │ etc) │
217 ├───────┼────────────────────────────┤
218 │fc │ The network fabric is a │
219 │ │ Fibre Channel network. │
220 ├───────┼────────────────────────────┤
221 │tcp │ The network fabric is a │
222 │ │ TCP/IP network. │
223 ├───────┼────────────────────────────┤
224 │loop │ Connect to a NVMe over │
225 │ │ Fabrics target on the │
226 │ │ local host │
227 └───────┴────────────────────────────┘
228
229 traddr=
230 This is a mandatory field that specifies the network
231 address of the Controller. For transports using IP
232 addressing (e.g. rdma) this should be an IP-based address
233 (ex. IPv4, IPv6). It could also be a resolvable host name
234 (e.g. localhost).
235
236 trsvcid=
237 This is an optional field that specifies the transport
238 service id. For transports using IP addressing (e.g. rdma,
239 tcp) this field is the port number.
240
241 Depending on the transport type, this field will default to
242 either 8009 or 4420 as follows.
243
244 UDP port 4420 and TCP port 4420 have been assigned by IANA
245 for use by NVMe over Fabrics. NVMe/RoCEv2 controllers use
246 UDP port 4420 by default. NVMe/iWARP controllers use TCP
247 port 4420 by default.
248
249 TCP port 4420 has been assigned for use by NVMe over
250 Fabrics and TCP port 8009 has been assigned by IANA for use
251 by NVMe over Fabrics discovery. TCP port 8009 is the
252 default TCP port for NVMe/TCP discovery controllers. There
253 is no default TCP port for NVMe/TCP I/O controllers, the
254 Transport Service Identifier (TRSVCID) field in the
255 Discovery Log Entry indicates the TCP port to use.
256
257 The TCP ports that may be used for NVMe/TCP I/O controllers
258 include TCP port 4420, and the Dynamic and/or Private TCP
259 ports (i.e., ports in the TCP port number range from 49152
260 to 65535). NVMe/TCP I/O controllers should not use TCP port
261 8009. TCP port 4420 shall not be used for both NVMe/iWARP
262 and NVMe/TCP at the same IP address on the same network.
263
264 Ref: IANA Service names port numbers[1]
265
266 nqn=
267 This field specifies the Controller's NVMe Qualified Name.
268
269 This field is mandatory for I/O Controllers, but is
270 optional for Discovery Controllers (DC). For the latter,
271 the NQN will default to the well-known DC NQN:
272 nqn.2014-08.org.nvmexpress.discovery if left undefined.
273
274 host-traddr=
275 This is an optional field that specifies the network
276 address used on the host to connect to the Controller. For
277 TCP, this sets the source address on the socket.
278
279 host-iface=
280 This is an optional field that specifies the network
281 interface used on the host to connect to the Controller
282 (e.g. IP eth1, enp2s0, enx78e7d1ea46da). This forces the
283 connection to be made on a specific interface instead of
284 letting the system decide.
285
286 dhchap-ctrl-secret=
287 This is an optional field that specifies the NVMe In-band
288 authentication controller secret (i.e. key) for
289 bi-directional authentication; needs to be in ASCII format
290 as specified in NVMe 2.0 section 8.13.5.8 'Secret
291 representation'. Bi-directional authentication will be
292 attempted when present.
293
294 hdr-digest=
295 See definition in [Global] section. This is an optional
296 field used to override the value specified in the [Global]
297 section.
298
299 data-digest=
300 See definition in [Global] section. This is an optional
301 field used to override the value specified in the [Global]
302 section.
303
304 nr-io-queues=
305 See definition in [Global] section. This is an optional
306 field used to override the value specified in the [Global]
307 section.
308
309 nr-write-queues=
310 See definition in [Global] section. This is an optional
311 field used to override the value specified in the [Global]
312 section.
313
314 nr-poll-queues=
315 See definition in [Global] section. This is an optional
316 field used to override the value specified in the [Global]
317 section.
318
319 queue-size=
320 See definition in [Global] section. This is an optional
321 field used to override the value specified in the [Global]
322 section.
323
324 kato=
325 See definition in [Global] section. This is an optional
326 field used to override the value specified in the [Global]
327 section.
328
329 reconnect-delay=
330 See definition in [Global] section. This is an optional
331 field used to override the value specified in the [Global]
332 section.
333
334 ctrl-loss-tmo=
335 See definition in [Global] section. This is an optional
336 field used to override the value specified in the [Global]
337 section.
338
339 disable-sqflow=
340 See definition in [Global] section. This is an optional
341 field used to override the value specified in the [Global]
342 section.
343 Examples:
344
345 controller = transport=tcp;traddr=localhost;trsvcid=8009
346 controller = transport=tcp;traddr=2001:db8::370:7334;host-iface=enp0s8
347 controller = transport=fc;traddr=nn-0x204600a098cbcac6:pn-0x204700a098cbcac6
348
349
350
351 exclude=
352 Controllers that should be excluded can be specified with the
353 exclude= option. Using mDNS to automatically discover and connect
354 to controllers, can result in unintentional connections being made.
355 This keyword allows configuring the controllers that should not be
356 connected to.
357
358 The syntax is the same as for "controller", except that only
359 transport, traddr, trsvcid, nqn, and host-iface apply. Multiple
360 exclude= keywords may appear in the config file to specify more
361 than 1 excluded controller.
362
363 Note 1: A minimal match approach is used to eliminate unwanted
364 controllers. That is, you do not need to specify all the parameters
365 to identify a controller. Just specifying the host-iface, for
366 example, can be used to exclude all controllers on an interface.
367
368 Note 2: exclude= takes precedence over controller. A controller
369 specified by the controller keyword, can be eliminated by the
370 exclude= keyword.
371
372 Examples:
373
374 exclude = transport=tcp;traddr=fe80::2c6e:dee7:857:26bb # Eliminate a specific address
375 exclude = host-iface=enp0s8 # Eliminate everything on this interface
376
377
378
380 stafd(8)
381
383 1. IANA Service names port numbers
384 https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=nvme
385
386
387
388nvme-stas 2.3.1 STAFD.CONF(5)