path: root/doc/standard-conf.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>