summaryrefslogtreecommitdiffstats
path: root/doc/standard-conf.xml
diff options
context:
space:
mode:
authorBenjamin Drung <bdrung@debian.org>2023-06-10 08:55:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2023-06-10 09:21:49 +0000
commit88837172f69eabc408ae3945d82e0270b8e07440 (patch)
treed6b7fa06694f45d25f54f6ea9ded93c981e51f6f /doc/standard-conf.xml
parentInitial commit. (diff)
downloadnvme-stas-88837172f69eabc408ae3945d82e0270b8e07440.tar.xz
nvme-stas-88837172f69eabc408ae3945d82e0270b8e07440.zip
Adding upstream version 2.2.1.upstream/2.2.1
Signed-off-by: Benjamin Drung <bdrung@debian.org>
Diffstat (limited to 'doc/standard-conf.xml')
-rw-r--r--doc/standard-conf.xml562
1 files changed, 562 insertions, 0 deletions
diff --git a/doc/standard-conf.xml b/doc/standard-conf.xml
new file mode 100644
index 0000000..50d4fe5
--- /dev/null
+++ b/doc/standard-conf.xml
@@ -0,0 +1,562 @@
+<?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>