'\" t
.\"     Title: stafd
.\"    Author: Mr. Martin Belanger
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/04/2023
.\"    Manual: stafd
.\"    Source: nvme-stas
.\"  Language: English
.\"
.TH "STAFD" "8" "" "nvme-stas 2.3-rc5" ""
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
stafd \- STorage Appliance Finder
.SH "SYNOPSIS"
.HP \w'\fBstafd\fR\ 'u
\fBstafd\fR [OPTIONS...]
.SH "DESCRIPTION"
.PP
\fBstafd\fR
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
\fBstafd.conf\fR(5)
to connect to Discovery Controllers that cannot be located using mDNS\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print the help text and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print the version string and exit\&.
.RE
.PP
\fB\-fFILE\fR, \fB\-\-conf\-file=FILE\fR
.RS 4
Specify a different configuration file than
\fBstafd.conf\fR(5)
(default:
/etc/stas/stafd\&.conf)\&.
.RE
.PP
\fB\-s\fR, \fB\-\-syslog\fR
.RS 4
Send messages to syslog instead of stdout\&. Use this when running stafd as a daemon\&. (default:
false)\&.
.RE
.PP
\fB\-\-tron\fR
.RS 4
Trace ON\&. (default:
false)
.RE
.PP
\fB\-\-idl=FILE\fR
.RS 4
Print D\-Bus IDL to FILE and exit\&.
.RE
.SH "EXIT STATUS"
.PP
On success, 0 is returned, a non\-zero failure code otherwise\&.
.SH "DAEMONIZATION"
.PP
stafd is managed by
systemd\&. The following operations are supported:
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&
.TS
allbox tab(:);
lB lB.
T{
Command
T}:T{
Description
T}
.T&
l l
l l
l l
l l.
T{
.if n \{\
.RS 4
.\}
.nf
$ systemctl start stafd 
.fi
.if n \{\
.RE
.\}
T}:T{
Start daemon\&.
T}
T{
.if n \{\
.RS 4
.\}
.nf
$ systemctl stop stafd 
.fi
.if n \{\
.RE
.\}
T}:T{
Stop daemon\&. The SIGTERM signal is used to tell the daemon to stop\&.
T}
T{
.if n \{\
.RS 4
.\}
.nf
$ systemctl restart stafd 
.fi
.if n \{\
.RE
.\}
T}:T{
Effectively a stop + start\&.
T}
T{
.if n \{\
.RS 4
.\}
.nf
$ systemctl reload stafd 
.fi
.if n \{\
.RE
.\}
T}:T{
Reload configuration\&. This is done in real time without restarting the daemon\&. The SIGHUP signal is used to tell the daemon to reload its configuration file\&. Note that configuration parameters that affect connections (e\&.g\&. kato), will not apply to existing connections\&. Only connections established after the configuration was changed will utilize the new configuration parameters\&.
T}
.TE
.sp 1
.SH "DESIGN"
.PP
\fBstafd\fR
use the
GLib
main loop\&. The
GLib
Python module provides several low\-level building blocks that
\fBstafd\fR
requires\&. In addition, many Python modules "play nice" with
GLib
such as
dasbus
(D\-Bus package) and
pyudev
(UDev package)\&.
GLib
also provides additional components such as timers, signal handlers, and much more\&.
.PP
\fBstafd\fR
connects to the
avahi\-daemon
using D\-Bus\&. The
avahi\-daemon, or simply
\fIAvahi\fR, is an mDNS discovery service used for zero\-configuration networking (zeroconf)\&.
\fBstafd\fR
registers with Avahi to automatically locate Central Discovery Controllers (CDC) and Direct Discovery Controllers (DDC)\&. When Avahi finds Discovery Controllers (DC), it notifies
\fBstafd\fR
which connects to the DC with the help of the
libnvme
library\&. Once a connection to a DC is established,
\fBstafd\fR
can retrieve the
\fIdiscovery log pages\fR
from that DC and cache them in memory\&.
.SH "CONFIGURATION"
.PP
\fBstafd\fR
can automatically locate discovery controllers (DC) with the help of Avahi and connect to them\&. However,
\fBstafd\fR
can also operate in a non\-automatic mode based on manually entered configuration\&. In other words, DCs can be entered in a configuration named
/etc/stas/stafd\&.conf\&. This configuration file also provides additional parameters, such as log\-level attributes used for debugging purposes\&.
.SH "D\-BUS API"
.PP
The interface to
\fBstafd\fR
is D\-Bus\&. This allows other programs, such as
\fBstafctl\fR, to communicate with
\fBstafd\fR\&. The D\-Bus address is
org\&.nvmexpress\&.staf\&.
.SH "SEE ALSO"
.PP
\fBstafd.conf\fR(5),
\fBstafd.service\fR(8),
\fBstafctl\fR(1),
\fBorg.nvmexpress.staf\fR(5)\&.