summaryrefslogtreecommitdiffstats
path: root/doc/stafd.conf.xml
blob: da0b8424a97636946e8a8e522359b096cc02d532 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
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>