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