diff options
Diffstat (limited to 'doc/stafd.conf.xml')
| -rw-r--r-- | doc/stafd.conf.xml | 280 |
1 files changed, 280 insertions, 0 deletions
diff --git a/doc/stafd.conf.xml b/doc/stafd.conf.xml new file mode 100644 index 0000000..da0b842 --- /dev/null +++ b/doc/stafd.conf.xml @@ -0,0 +1,280 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + SPDX-License-Identifier: Apache-2.0 + Copyright (c) 2021, Dell Inc. or its subsidiaries. All rights reserved. +--> +<refentry id="stafd.conf" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>stafd.conf</title> + <productname>nvme-stas</productname> + + <author> + <personname> + <honorific>Mr</honorific> + <firstname>Martin</firstname> + <surname>Belanger</surname> + </personname> + + <affiliation> + <orgname>Dell, Inc.</orgname> + </affiliation> + </author> + </refentryinfo> + + <refmeta> + <refentrytitle>stafd.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>stafd.conf</refname> + + <refpurpose> + <citerefentry project="man-pages"> + <refentrytitle>stafd</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> + configuration file + </refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para> + <filename>/etc/stas/stafd.conf</filename> + </para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + When <citerefentry project="man-pages"><refentrytitle>stafd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> starts up, it reads its + configuration from <filename>stafd.conf</filename>. + </para> + </refsect1> + + <refsect1> + <title>Configuration File Format</title> + <para> + <filename>stafd.conf</filename> is a plain text file divided into + sections, with configuration entries in the style + <replaceable>key</replaceable>=<replaceable>value</replaceable>. + Spaces immediately before or after the <literal>=</literal> are + ignored. Empty lines are ignored as well as lines starting with + <literal>#</literal>, which may be used for commenting. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <refsect2> + <title>[Global] section</title> + <para> + The following options are available in the + <literal>[Global]</literal> section: + </para> + + <variablelist> + <xi:include href="standard-conf.xml" xpointer="tron"/> + <xi:include href="standard-conf.xml" xpointer="hdr-digest"/> + <xi:include href="standard-conf.xml" xpointer="data-digest"/> + <xi:include href="standard-conf.xml" xpointer="kato"/> + <xi:include href="standard-conf.xml" xpointer="ip-family"/> + <xi:include href="standard-conf.xml" xpointer="queue-size"/> + <xi:include href="standard-conf.xml" xpointer="reconnect-delay"/> + <xi:include href="standard-conf.xml" xpointer="ctrl-loss-tmo"/> + <xi:include href="standard-conf.xml" xpointer="disable-sqflow"/> + + <varlistentry> + <term><varname>ignore-iface=</varname></term> + <listitem> + <para> + Takes a boolean argument. This option controls how + connections with Discovery Controllers (DC) are made. + </para> + + <para> + DCs are automatically discovered using DNS-SD/mDNS. + mDNS provides the DC's IP address and the interface + on which the DC was discovered. + </para> + + <para> + There is no guarantee that there will be a route to + reach that DC. However, we can use the socket option + SO_BINDTODEVICE to force the connection to be made + on a specific interface instead of letting the + routing tables decide where to make the connection. + </para> + + <para> + This option determines whether <code>stafd</code> + will use SO_BINDTODEVICE to force connections on an + interface or just rely on the routing tables. The + default is to use SO_BINDTODEVICE, in other words, + <code>stafd</code> does not ignore the interface by + default. + </para> + <para> + Defaults to <parameter>false</parameter>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>pleo=</varname></term> + <listitem> + <para> + Port Local Entries Only. Takes a string argument + <parameter>enabled</parameter> or + <parameter>disabled</parameter>. This option is sent in + the LSP field (Log SPecific) of the Get Discovery Log + Page (DLP) command. It is used by <code>stafd</code> to + tell Discovery Controllers (DC) whether the response to + a Get DLP command should contain all the NVM subsystems + or only those reachable by the host on the interface + where the Get DLP command was issued by the host. + </para> + + <para> + This parameter was introduced in TP8010. When + <varname>pleo=</varname><parameter>enabled</parameter>, + then the DC shall return records for only NVM subsystem + ports that are presented through the same NVM subsystem + port that received the Get Log Page command. When + <varname>pleo=</varname><parameter>disabled</parameter>, + then the DC may return all the NVM subsystem ports + that it holds, even those that can only be reached + on NVM subsystem ports that did not receive the Get + Log Page command. In other words, the host may not + even be able to reach those subsystems. + </para> + + <para> + Defaults to <parameter>enabled</parameter>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2> + <title>[Service Discovery] section</title> + + <para> + The following options are available in the + <literal>[Service Discovery]</literal> section: + </para> + + <variablelist> + <varlistentry> + <term><varname>zeroconf=</varname></term> + + <listitem> + <para> + Enable zeroconf provisioning using DNS-SD/mDNS. + Takes a string argument <parameter>enabled</parameter> or + <parameter>disabled</parameter>. + </para> + <para> + When <parameter>enabled</parameter>, the default, + <code>stafd</code> makes a request with the + Avahi daemon to locate Discovery Controllers using + DNS-SD/mDNS. + </para> + <para> + Discovery Controllers that support zeroconf advertize + themselves over mDNS with the service type + <literal>_nvme-disc._tcp</literal>. + </para> + <para> + Defaults to <parameter>true</parameter>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2> + <title>[Discovery controller connection management] section</title> + + <para> + The following options are available in the + <literal>[Discovery controller connection management]</literal> section: + </para> + + <varlistentry> + <term><varname>persistent-connections=</varname></term> + <listitem> + <para> + Takes a boolean argument. Whether connections to + Discovery Controllers (DC) are persistent. When + true, connections initiated by stafd will persists + even when stafd is stopped. When + <parameter>false</parameter>, <code>stafd</code> + will disconnect from all DCs it is connected to on + exit. + </para> + <para> + Defaults to <parameter>false</parameter>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>zeroconf-connections-persistence=</varname></term> + <listitem> + <para> + Takes a unit-less value in seconds, or a time span value + such as "72hours" or "5days". A value of 0 means no + persistence. In other words, configuration acquired through + zeroconf (mDNS service discovery) will be removed + immediately when mDNS no longer reports the presence of + a Discovery Controller (DC) and connectivity to that DC + is lost. A value of -1 means that configuration acquired + through zeroconf will persist forever. + </para> + + <para> + This is used for the case where a DC that was discovered + through mDNS service discovery no longer advertises + itself through mDNS and can no longer be connected to. + For example, the DC had some catastrophic failure + (e.g. power surge) and needs to be replaced. In that + case, the connection to that DC can never be restored + and a replacement DC will be needed. The replacement + DC will likely have a different NQN (or IP address). + In that scenario, the host won't be able to determine + that the old DC is not coming back. It won't know either + that a newly discovered DC is really the replacement for + the old one. For that reason, the host needs a way to + "age" zeroconf-acquired configuration and remove it + automatically after a certain amount of time. This is + what this parameter is for. + </para> + + <para> + Defaults to <parameter>72hours</parameter>. + </para> + </listitem> + </varlistentry> + </refsect2> + + <xi:include href="standard-conf.xml" xpointer="controller"/> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry> + <refentrytitle>stafd</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> + </para> + </refsect1> +</refentry> |