nvme-stas/doc/stasadm.xml

<?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>