Adding upstream version 2.2.1.upstream/2.2.1

Signed-off-by: Benjamin Drung <bdrung@debian.org>

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>