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