<?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 advertise
                            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>
