<?xml version="1.0"?>
<!DOCTYPE refsection PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
SPDX-License-Identifier: Apache-2.0
Copyright (c) 2021, Dell Inc. or its subsidiaries. All rights reserved.
-->
<root>
<variablelist>
<varlistentry id='tron'>
<term><varname>tron=</varname></term>
<listitem id='tron-text'>
<para>
Trace ON. Takes a boolean argument. If <parameter>true</parameter>,
enables full code tracing. The trace will be displayed in
the system log such as systemd's journal. Defaults to
<parameter>false</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry id='hdr-digest'>
<term><varname>hdr-digest=</varname></term>
<listitem id='hdr-digest-text'>
<para>
Enable Protocol Data Unit (PDU) Header Digest. Takes a
boolean argument. NVMe/TCP facilitates an optional PDU
Header digest. Digests are calculated using the CRC32C
algorithm. If <parameter>true</parameter>, Header Digests
are inserted in PDUs and checked for errors. Defaults to
<parameter>false</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry id='data-digest'>
<term><varname>data-digest=</varname></term>
<listitem id='data-digest-text'>
<para>
Enable Protocol Data Unit (PDU) Data Digest. Takes a
boolean argument. NVMe/TCP facilitates an optional PDU
Data digest. Digests are calculated using the CRC32C
algorithm. If <parameter>true</parameter>, Data Digests
are inserted in PDUs and checked for errors. Defaults to
<parameter>false</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry id='kato'>
<term><varname>kato=</varname></term>
<listitem id='kato-text'>
<para>
Keep Alive Timeout (KATO) in seconds. Takes an unsigned
integer. This field specifies the timeout value for the Keep
Alive feature in seconds. Defaults to 30 seconds for
Discovery Controller connections and 120 seconds for I/O
Controller connections.
</para>
</listitem>
</varlistentry>
<varlistentry id='ip-family'>
<term><varname>ip-family=</varname></term>
<listitem id='ip-family-text'>
<para>
Takes a string argument. With this you can specify
whether IPv4, IPv6, or both are supported when
connecting to a Controller. Connections will not be
attempted to IP addresses (whether discovered or
manually configured with <varname>controller=</varname>)
disabled by this option. If an invalid value
is entered, then the default (see below) will apply.
</para>
<para>
Choices are <parameter>ipv4</parameter>, <parameter>ipv6</parameter>, or <parameter>ipv4+ipv6</parameter>.
</para>
<para>
Defaults to <parameter>ipv4+ipv6</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry id='queue-size'>
<term><varname>queue-size=</varname></term>
<listitem id='queue-size-text'>
<para>
Takes a value in the range 16...1024.
</para>
<para>
Overrides the default number of elements in the I/O queues
created by the driver. This option will be ignored for
discovery, but will be passed on to the subsequent connect
call.
</para>
<para>Note: This parameter is identical to that provided by nvme-cli.</para>
<para>
Defaults to <parameter>128</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry id='reconnect-delay'>
<term><varname>reconnect-delay=</varname></term>
<listitem id='reconnect-delay-text'>
<para>
Takes a value in the range 1 to N seconds.
</para>
<para>
Overrides the default delay before reconnect is attempted
after a connect loss.
</para>
<para>Note: This parameter is identical to that provided by nvme-cli.</para>
<para>
Defaults to <parameter>10</parameter>. Retry to connect every 10 seconds.
</para>
</listitem>
</varlistentry>
<varlistentry id='ctrl-loss-tmo'>
<term><varname>ctrl-loss-tmo=</varname></term>
<listitem id='ctrl-loss-tmo-text'>
<para>
Takes a value in the range -1, 0, ..., N seconds. -1 means
retry forever. 0 means do not retry.
</para>
<para>
Overrides the default controller loss timeout period (in seconds).
</para>
<para>Note: This parameter is identical to that provided by nvme-cli.</para>
<para>
Defaults to <parameter>600</parameter> seconds (10 minutes).
</para>
</listitem>
</varlistentry>
<varlistentry id='disable-sqflow'>
<term><varname>disable-sqflow=</varname></term>
<listitem id='disable-sqflow-text'>
<para>
Takes a boolean argument. Disables SQ flow control to omit
head doorbell update for submission queues when sending nvme
completions.
</para>
<para>Note: This parameter is identical to that provided by nvme-cli.</para>
<para>
Defaults to <parameter>false</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
<refsect2 id='controller'>
<title>[Controllers] section</title>
<para>The following options are available in the
<literal>[Controllers]</literal> section:</para>
<varlistentry>
<term><varname>controller=</varname></term>
<listitem id='controller-text'>
<para>
Controllers are specified with the <varname>controller</varname>
option. This option may be specified more than once to specify
more than one controller. The format is one line per Controller
composed of a series of fields separated by semi-colons as follows:
</para>
<programlisting>controller=transport=[trtype];traddr=[traddr];trsvcid=[trsvcid];host-traddr=[traddr],host-iface=[iface];nqn=[nqn]
</programlisting>
<refsect3>
<title>Fields</title>
<variablelist>
<varlistentry id='transport'>
<term><varname>transport=</varname></term>
<listitem id='transport-text'>
<para>
This is a mandatory field that specifies the
network fabric being used for a
NVMe-over-Fabrics network. Current
<parameter>trtype</parameter> values understood
are:
</para>
<table id='transport-types'>
<title>Transport type</title>
<tgroup cols="2">
<thead>
<row>
<entry>trtype</entry>
<entry>Definition</entry>
</row>
</thead>
<tbody>
<row>
<entry>rdma</entry>
<entry>
The network fabric is an rdma network (RoCE, iWARP, Infiniband, basic rdma, etc)
</entry>
</row>
<row>
<entry>fc</entry>
<entry>
The network fabric is a Fibre Channel network.
</entry>
</row>
<row>
<entry>tcp</entry>
<entry>
The network fabric is a TCP/IP network.
</entry>
</row>
<row>
<entry>loop</entry>
<entry>
Connect to a NVMe over Fabrics target on the local host
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry id='tradd'>
<term>
<varname>traddr=</varname>
</term>
<listitem>
<para>
This is a mandatory field that specifies the
network address of the Controller. For
transports using IP addressing (e.g. rdma)
this should be an IP-based address (ex.
IPv4, IPv6). It could also be a resolvable
host name (e.g. localhost).
</para>
</listitem>
</varlistentry>
<varlistentry id='trsvcid'>
<term>
<varname>trsvcid=</varname>
</term>
<listitem>
<para>
This is an optional field that specifies the
transport service id. For transports using
IP addressing (e.g. rdma, tcp) this field is
the port number.
</para>
<para>
Depending on the transport type, this field
will default to either 8009 or 4420 as
follows.
</para>
<para>
UDP port 4420 and TCP port 4420 have been
assigned by IANA for use by NVMe over
Fabrics. NVMe/RoCEv2 controllers use UDP
port 4420 by default. NVMe/iWARP controllers
use TCP port 4420 by default.
</para>
<para>
TCP port 4420 has been assigned for use by
NVMe over Fabrics and TCP port 8009 has been
assigned by IANA for use by NVMe over
Fabrics discovery. TCP port 8009 is the
default TCP port for NVMe/TCP discovery
controllers. There is no default TCP port
for NVMe/TCP I/O controllers, the Transport
Service Identifier (TRSVCID) field in the
Discovery Log Entry indicates the TCP port
to use.
</para>
<para>
The TCP ports that may be used for NVMe/TCP
I/O controllers include TCP port 4420, and
the Dynamic and/or Private TCP ports (i.e.,
ports in the TCP port number range from
49152 to 65535). NVMe/TCP I/O controllers
should not use TCP port 8009. TCP port 4420
shall not be used for both NVMe/iWARP and
NVMe/TCP at the same IP address on the same
network.
</para>
<para>
Ref:
<ulink
url="https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=nvme">
IANA Service names port numbers
</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry id='nqn'>
<term><varname>nqn=</varname></term>
<listitem>
<para>
This field specifies the Controller's NVMe
Qualified Name.
</para>
<para>
This field is mandatory for I/O Controllers, but is optional for
Discovery Controllers (DC). For the latter, the NQN will default
to the well-known DC NQN: <literal>nqn.2014-08.org.nvmexpress.discovery</literal>
if left undefined.
</para>
</listitem>
</varlistentry>
<varlistentry id='host-traddr'>
<term><varname>host-traddr=</varname></term>
<listitem>
<para>
This is an optional field that specifies the
network address used on the host to connect
to the Controller. For TCP, this sets the
source address on the socket.
</para>
</listitem>
</varlistentry>
<varlistentry id='host-iface'>
<term><varname>host-iface=</varname></term>
<listitem>
<para>
This is an optional field that specifies the
network interface used on the host to
connect to the Controller (e.g. IP eth1,
enp2s0, enx78e7d1ea46da). This forces the
connection to be made on a specific
interface instead of letting the system
decide.
</para>
</listitem>
</varlistentry>
<varlistentry id='dhchap-ctrl-secret'>
<term><varname>dhchap-ctrl-secret=</varname></term>
<listitem>
<para>
This is an optional field that specifies the
NVMe In-band authentication controller secret
(i.e. key) for bi-directional authentication;
needs to be in ASCII format as specified in
NVMe 2.0 section 8.13.5.8 'Secret representation'.
Bi-directional authentication will be attempted
when present.
</para>
</listitem>
</varlistentry>
<varlistentry id='hdr-digest-override'>
<term><varname>hdr-digest=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
<varlistentry id='data-digest-override'>
<term><varname>data-digest=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
<varlistentry id='nr-io-queues-override'>
<term><varname>nr-io-queues=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
<varlistentry id='nr-write-queues-override'>
<term><varname>nr-write-queues=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
<varlistentry id='nr-poll-queues-override'>
<term><varname>nr-poll-queues=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
<varlistentry id='queue-size-override'>
<term><varname>queue-size=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
<varlistentry id='kato-override'>
<term><varname>kato=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
<varlistentry id='reconnect-delay-override'>
<term><varname>reconnect-delay=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
<varlistentry id='ctrl-loss-tmo-override'>
<term><varname>ctrl-loss-tmo=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
<varlistentry id='disable-sqflow-override'>
<term><varname>disable-sqflow=</varname></term>
<listitem>
<para>
See definition in [Global] section. This is
an optional field used to override the value
specified in the [Global] section.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
<para>
Examples:
<programlisting>controller = transport=tcp;traddr=localhost;trsvcid=8009
controller = transport=tcp;traddr=2001:db8::370:7334;host-iface=enp0s8
controller = transport=fc;traddr=nn-0x204600a098cbcac6:pn-0x204700a098cbcac6
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>exclude=</varname></term>
<listitem id='exclude-text'>
<para>
Controllers that should be excluded can be specified with the
<varname>exclude=</varname> option. Using mDNS to
automatically discover and connect to controllers, can result
in unintentional connections being made. This keyword allows
configuring the controllers that should not be connected to.
</para>
<para>
The syntax is the same as for "controller", except that only
<parameter>transport</parameter>, <parameter>traddr</parameter>,
<parameter>trsvcid</parameter>, <parameter>nqn</parameter>, and
<parameter>host-iface</parameter> apply. Multiple
<varname>exclude=</varname> keywords may appear in the config
file to specify more than 1 excluded controller.
</para>
<para>
Note 1: A minimal match approach is used to eliminate unwanted
controllers. That is, you do not need to specify all the
parameters to identify a controller. Just specifying the
<parameter>host-iface</parameter>, for example, can be used to
exclude all controllers on an interface.
</para>
<para>
Note 2: <varname>exclude=</varname> takes precedence over
<varname>controller</varname>. A controller specified by the
<varname>controller</varname> keyword, can be eliminated by
the <varname>exclude=</varname> keyword.
</para>
<para>
Examples:
<programlisting>exclude = transport=tcp;traddr=fe80::2c6e:dee7:857:26bb # Eliminate a specific address
exclude = host-iface=enp0s8 # Eliminate everything on this interface
</programlisting>
</para>
</listitem>
</varlistentry>
</refsect2>
</root>