diff options
Diffstat (limited to 'doc/nvme-stas.xml')
| -rw-r--r-- | doc/nvme-stas.xml | 185 |
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> |