Adding upstream version 2.2.1.upstream/2.2.1

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

1 files changed, 185 insertions, 0 deletions

diff --git a/doc/nvme-stas.xml b/doc/nvme-stas.xml
new file mode 100644
index 0000000..1e70c02
--- /dev/null
+++ b/doc/nvme-stas.xml
@@ -0,0 +1,185 @@
+<?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">
+<!--
+    SPDX-License-Identifier: Apache-2.0
+    Copyright (c) 2021, Dell Inc. or its subsidiaries.  All rights reserved.
+-->
+
+<refentry id="nvme-stas">
+
+  <refentryinfo>
+    <title>nvme-stas</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>nvme-stas</refentrytitle>
+    <manvolnum>7</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>nvme-stas</refname>
+    <refpurpose>NVMe over Fabrics STorage Appliance Services</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Introduction</title>
+
+    <para>
+        This page describes the services provided by the <code>nvme-stas</code> package.
+    </para>
+
+    <para>
+        <code>nvme-stas</code> is composed of two services, <citerefentry><refentrytitle>stafd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        and <citerefentry><refentrytitle>stacd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        running on a host computer (the NVMe Host).
+    </para>
+
+    <refsect2>
+        <title>STorage Appliance Finder (<code>stafd</code>)</title>
+        <para>
+            The tasks performed by <code>stafd</code> include:
+        </para>
+        <itemizedlist mark='opencircle'>
+            <listitem>
+                <para>
+                    Register for mDNS service type <parameter>_nvme-disc._tcp</parameter>
+                    with Avahi, the service discovery daemon. This allows <code>stafd</code>
+                    to automatically locate Central or Direct Discovery
+                    Controllers (CDC, DDC) with zero-configuration networking
+                    (zeroconf). <code>stafd</code> also allows users to manually enter CDCs
+                    and DDCs in a configuration file
+                    (<filename>/etc/stas/stafd.conf</filename>) when users
+                    prefer not to enable mDNS-based zeroconf.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Connect to discovered or configured CDCs or DDCs.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Retrieve the list of NVMe subsystem IO Controllers or
+                    Discovery Controller referrals from the Discovery Log Page 
+                    using the NVMe command "Get Log Page".
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Maintain a cache of the discovery log pages.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Provide a D-Bus API where other applications can interact
+                    with <code>stafd</code>. This API can be used, for example, to retrieve
+                    the list of cached discovery log pages.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </refsect2>
+
+    <refsect2>
+        <title>STorage Appliance Connector (<code>stacd</code>)</title>
+        <para>
+            The tasks performed by <code>stacd</code> include:
+        </para>
+        <itemizedlist mark='opencircle'>
+            <listitem>
+                <para>
+                    Read the list of storage subsystems (i.e., discovery log pages)
+                    from <code>stafd</code> over the D-Bus API.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Similar to <code>stafd</code>, <code>stacd</code> can also read a list of storage
+                    subsystems to connect to from a configuration
+                    file: (<filename>/etc/stas/stacd.conf</filename>).
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Set up the I/O controller connections to each storage subsystem.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    Provide a D-Bus API where other applications can interact
+                    with <code>stacd</code>. For example, an application could retrieve the
+                    list of I/O controllers that <code>stacd</code> connected to.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </refsect2>
+
+    <refsect2>
+        <title>System configuration</title>
+        <para>
+            A host must be provided with a Host NQN and a Host ID. <code>nvme-stas</code>
+            will not run without these two mandatory configuration parameters.
+            To follow in the footsteps of <code>nvme-cli</code> and <code>libnvme</code>,
+            <code>nvme-stas</code> will use the same Host NQN and ID that
+            <code>nvme-cli</code> and <code>libnvme</code> use by default.
+            In other words, <code>nvme-stas</code> will read the Host NQN and ID
+            from these two files by default:
+        </para>
+
+        <itemizedlist mark='opencircle'>
+            <listitem>
+                <para>
+                    <filename>/etc/nvme/hostnqn</filename>
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <filename>/etc/nvme/hostid</filename>
+                </para>
+            </listitem>
+        </itemizedlist>
+
+        <para>
+            Using the same configuration files will ensure consistency between
+            <code>nvme-stas</code>, <code>nvme-cli</code>, and <code>libnvme</code>.
+            On the other hand, <code>nvme-stas</code> can operate with a
+            different Host NQN and/or ID. In that case, one can specify them
+            in <filename>/etc/stas/sys.conf</filename>.
+        </para>
+            A new optional configuration parameters introduced in TP8010, the
+            Host Symbolic Name, can also be specified in <filename>/etc/stas/sys.conf</filename>.
+            The documentation for <filename>/etc/stas/sys.conf</filename>
+            can be found <filename>/etc/stas/sys.conf.doc</filename>.
+        <para>
+        </para>
+    </refsect2>
+
+  </refsect1>
+
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+        <citerefentry><refentrytitle>stacctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>stacd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>stacd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>stacd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>stafctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>stafd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>stafd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>stafd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+    </para>
+  </refsect1>
+
+</refentry>