summaryrefslogtreecommitdiffstats
path: root/doc/nvme-stas.xml
diff options
context:
space:
mode:
authorBenjamin Drung <bdrung@debian.org>2023-06-10 08:55:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2023-06-10 09:21:49 +0000
commit88837172f69eabc408ae3945d82e0270b8e07440 (patch)
treed6b7fa06694f45d25f54f6ea9ded93c981e51f6f /doc/nvme-stas.xml
parentInitial commit. (diff)
downloadnvme-stas-88837172f69eabc408ae3945d82e0270b8e07440.tar.xz
nvme-stas-88837172f69eabc408ae3945d82e0270b8e07440.zip
Adding upstream version 2.2.1.upstream/2.2.1
Signed-off-by: Benjamin Drung <bdrung@debian.org>
Diffstat (limited to 'doc/nvme-stas.xml')
-rw-r--r--doc/nvme-stas.xml185
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>