diff options
Diffstat (limited to 'doc/standard-conf.xml')
| -rw-r--r-- | doc/standard-conf.xml | 562 |
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> |