238 lines
8.7 KiB
XML
238 lines
8.7 KiB
XML
|
<?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>
|