Adding upstream version 2.2.1.upstream/2.2.1

Signed-off-by: Benjamin Drung <bdrung@debian.org>

1 files changed, 237 insertions, 0 deletions

diff --git a/doc/stafd.xml b/doc/stafd.xml
new file mode 100644
index 0000000..10e454e
--- /dev/null
+++ b/doc/stafd.xml
@@ -0,0 +1,237 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY daemon "stafd">
+<!ENTITY deamondesc "STorage Appliance Finder">
+<!ENTITY control "stafctl">
+]>
+
+<!--
+    SPDX-License-Identifier: Apache-2.0
+    Copyright (c) 2021, Dell Inc. or its subsidiaries.  All rights reserved.
+-->
+
+<refentry id="&daemon;" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <refentryinfo>
+        <title>&daemon;</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>&daemon;</refentrytitle>
+        <manvolnum>8</manvolnum>
+    </refmeta>
+
+    <refnamediv>
+        <refname>&daemon;</refname>
+        <refpurpose>&deamondesc;</refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv>
+        <cmdsynopsis>
+            <command>&daemon;</command>
+            <arg choice="opt" rep="repeat">OPTIONS</arg>
+        </cmdsynopsis>
+    </refsynopsisdiv>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+            <command>&daemon;</command>
+            is a system daemon that can be used to automatically locate and
+            connect to NVMe-oF Discovery Controllers using mDNS service discovery.
+            It can also be manually configured with
+            <citerefentry>
+                <refentrytitle>&daemon;.conf</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry>
+            to connect to Discovery Controllers that cannot be located using
+            mDNS.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Options</title>
+        <para>The following options are understood:</para>
+
+        <variablelist>
+            <xi:include href="standard-options.xml" xpointer="help"/>
+            <xi:include href="standard-options.xml" xpointer="version"/>
+        </variablelist>
+
+        <varlistentry>
+            <term><option>-fFILE</option></term>
+            <term><option>--conf-file=FILE</option></term>
+            <listitem>
+                <para>
+                    Specify a different configuration file than
+                    <citerefentry>
+                        <refentrytitle>&daemon;.conf</refentrytitle>
+                        <manvolnum>5</manvolnum>
+                    </citerefentry>
+                    (default: <filename>/etc/stas/&daemon;.conf</filename>).
+                </para>
+            </listitem>
+        </varlistentry>
+
+        <varlistentry>
+            <term><option>-s</option></term>
+            <term><option>--syslog</option></term>
+            <listitem>
+                <para>
+                    Send messages to syslog instead of stdout. Use this when
+                    running &daemon; as a daemon. (default: <literal>false</literal>).
+                </para>
+            </listitem>
+        </varlistentry>
+
+        <varlistentry>
+            <term><option>--tron</option></term>
+            <listitem>
+                <para>Trace ON. (default: <literal>false</literal>)</para>
+            </listitem>
+        </varlistentry>
+
+        <varlistentry>
+            <term><option>--idl=FILE</option></term>
+            <listitem>
+                <para>Print D-Bus IDL to FILE and exit.</para>
+            </listitem>
+        </varlistentry>
+    </refsect1>
+
+    <refsect1>
+        <title>Exit status</title>
+        <para>
+            On success, 0 is returned, a non-zero failure code otherwise.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Daemonization</title>
+        <para>
+            &daemon; is managed by <code>systemd</code>. The following
+            operations are supported:
+        </para>
+
+        <table frame='all'>
+            <tgroup cols="2" align='left' colsep='1' rowsep='1'>
+                <thead>
+                    <row>
+                        <entry>Command</entry>
+                        <entry>Description</entry>
+                    </row>
+                </thead>
+
+                <tbody>
+                    <row>
+                        <entry><programlisting>$ systemctl start &daemon; </programlisting></entry>
+                        <entry>Start daemon.</entry>
+                    </row>
+
+                    <row>
+                        <entry><programlisting>$ systemctl stop &daemon; </programlisting></entry>
+                        <entry>Stop daemon. The <code>SIGTERM</code> signal is used to tell the daemon to stop.</entry>
+                    </row>
+
+                    <row>
+                        <entry><programlisting>$ systemctl restart &daemon; </programlisting></entry>
+                        <entry>Effectively a <code>stop</code> + <code>start</code>.</entry>
+                    </row>
+
+                    <row>
+                        <entry><programlisting>$ systemctl reload &daemon; </programlisting></entry>
+                        <entry>Reload configuration. This is done in real time without restarting the daemon. The <code>SIGHUP</code> signal is used to tell the daemon to reload its configuration file. Note that configuration parameters that affect connections (e.g. <code>kato</code>), will not apply to existing connections. Only connections established after the configuration was changed will utilize the new configuration parameters.</entry>
+                    </row>
+                </tbody>
+            </tgroup>
+        </table>
+    </refsect1>
+
+    <refsect1>
+      <title>Design</title>
+
+      <para>
+          <command>&daemon;</command> use the <code>GLib</code> main loop.
+          The <code>GLib</code> Python module provides several low-level
+          building blocks that <command>&daemon;</command> requires. In
+          addition, many Python modules "play nice" with <code>GLib</code>
+          such as <code>dasbus</code> (D-Bus package) and <code>pyudev</code>
+          (UDev package). <code>GLib</code> also provides additional components
+          such as timers, signal handlers, and much more.
+      </para>
+
+      <para>
+          <command>&daemon;</command> connects to the <code>avahi-daemon</code>
+          using D-Bus. The <code>avahi-daemon</code>, or simply
+          <emphasis>Avahi</emphasis>, is an mDNS discovery service used for
+          zero-configuration networking (zeroconf). <command>&daemon;</command>
+          registers with Avahi to automatically locate Central Discovery
+          Controllers (CDC) and Direct Discovery Controllers (DDC). When Avahi
+          finds Discovery Controllers (DC), it notifies <command>&daemon;</command>
+          which connects to the DC with the help of the <code>libnvme</code> library.
+          Once a connection to a DC is established, <command>&daemon;</command>
+          can retrieve the <emphasis>discovery log pages</emphasis> from
+          that DC and cache them in memory.
+      </para>
+    </refsect1>
+
+
+    <refsect1>
+        <title>Configuration</title>
+        <para>
+            <command>&daemon;</command> can automatically locate discovery
+            controllers (DC) with the help of Avahi and connect to them. However,
+            <command>&daemon;</command> can also operate in a non-automatic
+            mode based on manually entered configuration. In other words,
+            DCs can be entered in a configuration named
+            <filename>/etc/stas/&daemon;.conf</filename>.
+            This configuration file also provides additional parameters, such
+            as log-level attributes used for debugging purposes.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>D-Bus API</title>
+        <para>
+            The interface to <command>&daemon;</command> is D-Bus.
+            This allows other programs, such as <command>&control;</command>,
+            to communicate with <command>&daemon;</command>. The D-Bus address
+            is <code>org.nvmexpress.staf</code>.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>See Also</title>
+
+        <para>
+            <citerefentry>
+                <refentrytitle>&daemon;.conf</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry>,
+            <citerefentry>
+                <refentrytitle>&daemon;.service</refentrytitle>
+                <manvolnum>8</manvolnum>
+            </citerefentry>,
+            <citerefentry>
+                <refentrytitle>stafctl</refentrytitle>
+                <manvolnum>1</manvolnum>
+            </citerefentry>,
+            <citerefentry>
+                <refentrytitle>org.nvmexpress.staf</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry>.
+        </para>
+    </refsect1>
+</refentry>