562 lines
26 KiB
XML
562 lines
26 KiB
XML
<?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>
|