diff options
Diffstat (limited to 'doc/stasadm.xml')
| -rw-r--r-- | doc/stasadm.xml | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/doc/stasadm.xml b/doc/stasadm.xml new file mode 100644 index 0000000..576328c --- /dev/null +++ b/doc/stasadm.xml @@ -0,0 +1,201 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--*-nxml-*--> +<!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="stasadm" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>stasadm</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>stasadm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>stasadm</refname> + <refpurpose>STorage Appliance Services admin functions</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>stasadm</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>stasadm</command> is used to configure <code>nvme-stas</code>. The + configuration is saved to <filename>/etc/stas/sys.conf</filename>. + </para> + + <para> + Although <code>nvme-stas</code>' configuration is saved to + <filename>/etc/stas/sys.conf</filename>, it's still possible to + interoperate with the configuration of <command>nvme-cli</command> + and <command>libnvme</command>. <code>nvme-stas</code> allows one to + save individual parameters such as the Host NQN and ID outside of + <filename>/etc/stas/sys.conf</filename>. This allows, for example, + using the same default Host NQN and ID defined by + <command>nvme-cli</command> and <command>libnvme</command> in + <filename>/etc/nvme/hostnqn</filename> and <filename>/etc/nvme/hostid</filename> + respectively. To tell <code>nvme-stas</code> that you want to use the + those files, simply use <command>stasadm</command>'s + <option>--file=FILE</option> option. + </para> + </refsect1> + + <refsect1> + <title>Commands</title> + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>hostnqn</command></term> + <listitem> + <para> + Generate the Host NQN. This is typically used as a post + installation step to generate <filename>/etc/nvme/hostnqn</filename>. + </para> + <para> + The NVMe base specifications says: <quote>An NQN is + permanent for the lifetime of the host</quote>. For + this reason, the host NQN should only be generated + if <filename>/etc/nvme/hostnqn</filename> does not exist + already. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>hostid</command></term> + <listitem> + <para> + Generate the Host ID. This is typically used as a post + installation step to generate <filename>/etc/nvme/hostid</filename>. + </para> + <para> + Although not explicitly specified in the NVMe + specifications, the Host ID, like the Host NQN, should + be permanent for the lifetime of the host. Only generate + the Host ID if <filename>/etc/nvme/hostid</filename> + does not exist. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>set-symname [SYMNAME]</command></term> + <listitem> + <para> + Set the host symbolic name. + </para> + + <para> + The symbolic name is an optional parameter that can be + used for explicit registration with a discovery controller. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>clear-symname</command></term> + <listitem> + <para> + Clear the host symbolic name. + </para> + </listitem> + </varlistentry> + </variablelist> + </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"/> + + <varlistentry> + <term><option>-fFILE</option></term> + <term><option>--file=FILE</option></term> + <listitem> + <para> + By default, <command>hostnqn</command> and <command>hostid</command> + save the values to <filename>/etc/stas/sys.conf</filename>. + This option allows saving to a separate file. + </para> + <para> + Traditionally, <command>nvme-cli</command> and + <command>libnvme</command> retrieve the default Host NQN + and ID from <filename>/etc/nvme/hostnqn</filename> and + <filename>/etc/nvme/hostid</filename> respectively. The + <option>--file=FILE</option> option can be + used to tell <code>nvme-stas</code> that it should + use those same configuration files. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + <para> + On success, 0 is returned; otherwise, a non-zero failure code is + returned. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Generate <filename>/etc/nvme/hostnqn</filename></title> + <programlisting>$ stasadm hostnqn --file /etc/nvme/hostnqn</programlisting> + </example> + + <example> + <title>Generate <filename>/etc/nvme/hostid</filename></title> + <programlisting>$ stasadm hostid -f /etc/nvme/hostid</programlisting> + </example> + + <example> + <title>Configure the host's symbolic name</title> + <programlisting>$ stasadm set-symname LukeSkywalker</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry> + <refentrytitle>nvme-stas</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + </para> + </refsect1> +</refentry> |