| blob | 505a75030b84a3d4650acd44a19c4f41549f0c19 |
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2016 Nexenta Systems, Inc. All rights reserved.
13 .\"
14 .Dd January 19, 2018
15 .Dt NVMEADM 1M
16 .Os
17 .Sh NAME
18 .Nm nvmeadm
19 .Nd NVMe administration utility
20 .Sh SYNOPSIS
21 .Nm
22 .Fl h
23 .Op Ar command
24 .Nm
25 .Op Fl dv
26 .Cm list
27 .Op Ar ctl[/ns][,...]
28 .Nm
29 .Op Fl dv
30 .Cm identify
31 .Ar ctl[/ns][,...]
32 .Nm
33 .Op Fl dv
34 .Cm get-logpage
35 .Ar ctl[/ns][,...]
36 .Ar logpage
37 .Nm
38 .Op Fl dv
39 .Cm get-features
40 .Ar ctl[/ns][,...]
41 .Op Ar feature-list
42 .Nm
43 .Op Fl dv
44 .Cm format
45 .Ar ctl[/ns]
46 .Op Ar lba-format
47 .Nm
48 .Op Fl dv
49 .Cm secure-erase
50 .Ar ctl[/ns]
51 .Op Fl c
52 .Nm
53 .Op Fl dv
54 .Cm detach
55 .Ar ctl[/ns]
56 .Nm
57 .Op Fl dv
58 .Cm attach
59 .Ar ctl[/ns]
60 .Sh DESCRIPTION
61 The
62 .Nm
63 utility can be used to enumerate the NVMe controllers and their
64 namespaces, query hardware information from a NVMe controller or
65 namespace, and to format or secure-erase a NVMe controller or
66 namespace.
67 .Pp
68 The information returned by the hardware is printed by
69 .Nm
70 in a human-readable form were applicable.
71 Generally all 0-based counts are normalized and values may be
72 converted to human-readable units such as MB (megabytes), W (watts),
73 or C (degrees Celsius).
74 .Sh OPTIONS
75 The following options are supported:
76 .Bl -tag -width Ds
77 .It Fl h
78 Print a short help text for
79 .Nm ,
80 or for an optionally specified
81 .Nm
82 command.
83 .It Fl d
84 Enable debugging output.
85 .It Fl v
86 Enable verbose output.
87 .El
88 .Sh ARGUMENTS
89 .Nm
90 expects the following kinds of arguments:
91 .Bl -tag -width "ctl[/ns]"
92 .It Ar command
93 Any command
94 .Nm
95 understands.
96 See section
97 .Sx COMMANDS .
98 .It Ar ctl[/ns]
99 Specifies a NVMe controller and optionally a namespace within that
100 controller.
101 The controller name consists of the driver name
102 .Qq nvme
103 followed by an instance number.
104 A namespace is specified by appending a single
105 .Qq /
106 followed by the namespace ID to the controller name.
107 The namespace ID is the EUI64 of the namespace, or a positive non-zero
108 decimal number if the namespace doesn't have an EUI64.
109 For commands that don't change the device state multiple controllers
110 and namespaces can be specified as a comma-separated list.
111 .Pp
112 The list of controllers and namespaces present in the system can be
113 queried with the
114 .Cm list
115 command without any arguments.
116 .It Ar logpage
117 Specifies the log page name for the
118 .Cm get-logpage
119 command.
120 .It Ar feature-list
121 A comma-separated list of feature names for the
122 .Cm get-features
123 command.
124 Feature names can be specified in upper or lower case and can be
125 shortened the shortest unique name.
126 Some features may also have an alternative short name.
127 .It Ar lba-format
128 A non-zero integer specifying the LBA format for the
129 .Cm format
130 command.
131 The list of supported LBA formats on a namespace can be retrieved
132 with the
133 .Nm
134 .Cm identify
135 command.
136 .El
137 .Sh COMMANDS
138 .Bl -tag -width ""
139 .It Xo
140 .Nm
141 .Cm list
142 .Op Ar ctl[/ns][,...]
143 .Xc
144 Lists the NVMe controllers and their namespaces in the system and
145 prints a 1-line summary of their basic properties for each.
146 If a list of controllers and/or namespaces is given then the listing
147 is limited to those devices.
148 .It Xo
149 .Nm
150 .Cm identify
151 .Ar ctl[/ns][,...]
152 .Xc
153 Print detailed information about the specified controllers and/or
154 namespaces.
155 The information returned differs depending on whether a controller or
156 a namespace is specified.
157 For an explanation of the data printed by this command refer to the
158 description of the
159 .Qq IDENTIFY
160 admin command in the NVMe specification.
161 .It Xo
162 .Nm
163 .Cm get-logpage
164 .Ar ctl[/ns][,...]
165 .Ar logpage
166 .Xc
167 Print the specified log page of the specified controllers and/or namespaces.
168 Most log pages are only available on a per-controller basis.
169 Known log pages are:
170 .Bl -tag -width "firmware"
171 .It error
172 Error Information
173 .It health
174 SMART/Health Information.
175 A controller may support this log page on a per-namespace basis.
176 .It firmware
177 Firmware Slot Information
178 .El
179 .Pp
180 For an explanation of the contents of the log pages refer to the
181 description of the
182 .Qq GET LOGPAGE
183 admin command in the NVMe specification.
184 .It Xo
185 .Nm
186 .Cm get-features
187 .Ar ctl[/ns][,...]
188 .Op Ar feature-list
189 .Xc
190 Prints information about the specified features, or all features if
191 none are given, of the specified controllers and/or namespaces.
192 Feature names are case-insensitive, and they can be shortened as long
193 as they remain unique.
194 Some features also have alternative short names to which the same
195 rules apply.
196 The following features are supported:
197 .Pp
198 .TS
199 tab(:);
200 l l l.
201 FULL NAME:SHORT NAME:CONTROLLER/NAMESPACE
202 Arbitration::controller
203 Power Management::controller
204 LBA Range Type:range:namespace
205 Temperature Threshold::controller
206 Error Recovery::controller
207 Volatile Write Cache:cache:controller
208 Number of Queues:queues:controller
209 Interrupt Coalescing:coalescing:controller
210 Interrupt Vector Configuration:vector:controller
211 Write Atomicity:atomicity:controller
212 Asynchronous Event Configuration:event:controller
213 Autonomous Power State Transition::controller
214 Software Progress Marker:progress:controller
215 .TE
216 .Pp
217 For an explanation of the individual features refer to the description
218 of the
219 .Qq SET FEATURES
220 admin command in the NVMe specification.
221 .It Xo
222 .Nm
223 .Cm format
224 .Ar ctl[/ns]
225 .Op Ar lba-format
226 .Xc
227 Formats the specified namespace or all namespaces of the specified
228 controller.
229 This command implies a
230 .Nm
231 .Cm detach
232 and subsequent
233 .Nm
234 .Cm attach
235 of the specified namespace(s), which will cause a changed LBA format
236 to be detected.
237 If no LBA format is specified the LBA format currently used by the
238 namespace will be used.
239 When formatting all namespaces without specifying a LBA format the LBA
240 format of namespace 1 will be used.
241 A list of LBA formats supported by a namespace can be queried with the
242 .Nm
243 .Cm identify
244 command.
245 .Pp
246 Note that not all devices support formatting individual or all
247 namespaces, or support formatting at all.
248 .Pp
249 LBA formats using a non-zero metadata size are not supported by
250 .Nm
251 or
252 .Xr nvme 7D .
253 .Pp
254 The list of supported LBA formats on a namespace can be retrieved
255 with the
256 .Nm
257 .Cm identify
258 command.
259 .It Xo
260 .Nm
261 .Cm secure-erase
262 .Ar ctl[/ns]
263 .Op Fl c
264 .Xc
265 Erases the specified namespace or all namespaces of the controller.
266 The flag
267 .Fl c
268 will cause a cryptographic erase instead of a normal erase.
269 This command implies a
270 .Nm
271 .Cm detach
272 and
273 .Nm
274 .Cm attach
275 of the specified namespace(s).
276 .Pp
277 Note that not all devices support erasing individual or all
278 namespaces, or support erasing at all.
279 .It Xo
280 .Nm
281 .Cm detach
282 .Ar ctl[/ns]
283 .Xc
284 Temporarily detaches the
285 .Xr blkdev 7D
286 instance from the specified namespace or all namespaces of the controller.
287 This will prevent I/O access to the affected namespace(s).
288 Detach will only succeed if the affected namespace(s) are not
289 currently opened.
290 The detached state will not persist across reboots or reloads of the
291 .Xr nvme 7D
292 driver.
293 .It Xo
294 .Nm
295 .Cm attach
296 .Ar ctl[/ns]
297 .Xc
298 Attaches the
299 .Xr blkdev 7D
300 instance to the specified namespace or all namespaces of the controller.
301 This will make I/O accesses to the namespace(s) possible again after a
302 previous
303 .Nm
304 .Cm detach
305 command.
306 .El
307 .Sh EXIT STATUS
308 .Ex -std
309 .Sh EXAMPLES
310 .Bl -tag -width ""
311 .It Sy Example 1: List all NVMe controllers and namespaces
312 .Bd -literal
313 # nvmeadm list
314 nvme1: model: INTEL SSDPEDMD800G4, serial: CVFT4134001R800CGN, FW rev: 8DV10049, NVMe v1.0
315 nvme1/1 (c1t1d0): Size = 763097 MB, Capacity = 763097 MB, Used = 763097 MB
316 nvme4: model: SAMSUNG MZVPV128HDGM-00000, serial: S1XVNYAGA00640, FW rev: BXW7300Q, NVMe v1.1
317 nvme4/1 (c2t2d0): Size = 122104 MB, Capacity = 122104 MB, Used = 5127 MB
318 .Ed
319 .It Sy Example 2: Identify a namespace
320 .Bd -literal
321 # nvmeadm identify nvme4/1
322 nvme4/1: Identify Namespace
323 Namespace Capabilities and Features
324 Namespace Size: 122104MB
325 Namespace Capacity: 122104MB
326 Namespace Utilization: 5127MB
327 Namespace Features
328 Thin Provisioning: unsupported
329 Number of LBA Formats: 1
330 Formatted LBA Size
331 LBA Format: 1
332 Extended Data LBA: no
333 Metadata Capabilities
334 Extended Data LBA: unsupported
335 Separate Metadata: unsupported
336 End-to-End Data Protection Capabilities
337 Protection Information Type 1: unsupported
338 Protection Information Type 2: unsupported
339 Protection Information Type 3: unsupported
340 Protection Information first: unsupported
341 Protection Information last: unsupported
342 End-to-End Data Protection Settings
343 Protection Information: disabled
344 Protection Information in Metadata: last 8 bytes
345 LBA Format 1
346 Metadata Size: 0 bytes
347 LBA Data Size: 512 bytes
348 Relative Performance: Best
349 .Ed
350 .It Sy Example 3: Get SMART/Health information (verbose)
351 .Bd -literal
352 # nvmeadm -v get-logpage nvme4/1 health
353 nvme4/1: SMART/Health Information
354 Critical Warnings
355 Available Space: OK
356 Temperature: OK
357 Device Reliability: OK
358 Media: OK
359 Volatile Memory Backup: OK
360 Temperature: 37C
361 Available Spare Capacity: 100%
362 Available Spare Threshold: 10%
363 Device Life Used: 0%
364 Data Read: 0GB
365 Data Written: 64GB
366 Read Commands: 52907
367 Write Commands: 567874
368 Controller Busy: 1min
369 Power Cycles: 6
370 Power On: 141h
371 Unsafe Shutdowns: 1
372 Uncorrectable Media Errors: 0
373 Errors Logged: 1
374 .Ed
375 .It Sy Example 4: Get Asynchronous Event Configuration information
376 .Bd -literal
377 # nvmeadm get-features nvme0,nvme4 event,power
378 nvme0: Get Features
379 Asynchronous Event Configuration
380 Available Space below threshold: disabled
381 Temperature above threshold: disabled
382 Device Reliability compromised: disabled
383 Media read-only: disabled
384 Power Management
385 Power State: 0
386 nvme4: Get Features
387 Asynchronous Event Configuration
388 Available Space below threshold: disabled
389 Temperature above threshold: disabled
390 Device Reliability compromised: disabled
391 Media read-only: disabled
392 Volatile Memory Backup failed: disabled
393 Power Management
394 Power State: 0
395 .Ed
396 .El
397 .Sh INTERFACE STABILITY
398 The command line interface of
399 .Nm
400 is
401 .Sy Evolving .
402 The output of
403 .Nm
404 is
405 .Sy Not-an-Interface
406 and may change any time.
407 .Sh SEE ALSO
408 .Xr nvme 7D
409 .Pp
410 .Lk http://www.nvmexpress.org/specifications/ "NVMe specifications"