1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
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>
|
