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 61The 62.Nm 63utility can be used to enumerate the NVMe controllers and their 64namespaces, query hardware information from a NVMe controller or 65namespace, and to format or secure-erase a NVMe controller or 66namespace. 67.Pp 68The information returned by the hardware is printed by 69.Nm 70in a human-readable form were applicable. 71Generally all 0-based counts are normalized and values may be 72converted to human-readable units such as MB (megabytes), W (watts), 73or C (degrees Celsius). 74.Sh OPTIONS 75The following options are supported: 76.Bl -tag -width Ds 77.It Fl h 78Print a short help text for 79.Nm , 80or for an optionally specified 81.Nm 82command. 83.It Fl d 84Enable debugging output. 85.It Fl v 86Enable verbose output. 87.El 88.Sh ARGUMENTS 89.Nm 90expects the following kinds of arguments: 91.Bl -tag -width "ctl[/ns]" 92.It Ar command 93Any command 94.Nm 95understands. 96See section 97.Sx COMMANDS . 98.It Ar ctl[/ns] 99Specifies a NVMe controller and optionally a namespace within that 100controller. 101The controller name consists of the driver name 102.Qq nvme 103followed by an instance number. 104A namespace is specified by appending a single 105.Qq / 106followed by the namespace ID to the controller name. 107The namespace ID is the EUI64 of the namespace, or a positive non-zero 108decimal number if the namespace doesn't have an EUI64. 109For commands that don't change the device state multiple controllers 110and namespaces can be specified as a comma-separated list. 111.Pp 112The list of controllers and namespaces present in the system can be 113queried with the 114.Cm list 115command without any arguments. 116.It Ar logpage 117Specifies the log page name for the 118.Cm get-logpage 119command. 120.It Ar feature-list 121A comma-separated list of feature names for the 122.Cm get-features 123command. 124Feature names can be specified in upper or lower case and can be 125shortened the shortest unique name. 126Some features may also have an alternative short name. 127.It Ar lba-format 128A non-zero integer specifying the LBA format for the 129.Cm format 130command. 131The list of supported LBA formats on a namespace can be retrieved 132with the 133.Nm 134.Cm identify 135command. 136.El 137.Sh COMMANDS 138.Bl -tag -width "" 139.It Xo 140.Nm 141.Cm list 142.Op Ar ctl[/ns][,...] 143.Xc 144Lists the NVMe controllers and their namespaces in the system and 145prints a 1-line summary of their basic properties for each. 146If a list of controllers and/or namespaces is given then the listing 147is limited to those devices. 148.It Xo 149.Nm 150.Cm identify 151.Ar ctl[/ns][,...] 152.Xc 153Print detailed information about the specified controllers and/or 154namespaces. 155The information returned differs depending on whether a controller or 156a namespace is specified. 157For an explanation of the data printed by this command refer to the 158description of the 159.Qq IDENTIFY 160admin command in the NVMe specification. 161.It Xo 162.Nm 163.Cm get-logpage 164.Ar ctl[/ns][,...] 165.Ar logpage 166.Xc 167Print the specified log page of the specified controllers and/or namespaces. 168Most log pages are only available on a per-controller basis. 169Known log pages are: 170.Bl -tag -width "firmware" 171.It error 172Error Information 173.It health 174SMART/Health Information. 175A controller may support this log page on a per-namespace basis. 176.It firmware 177Firmware Slot Information 178.El 179.Pp 180For an explanation of the contents of the log pages refer to the 181description of the 182.Qq GET LOGPAGE 183admin 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 190Prints information about the specified features, or all features if 191none are given, of the specified controllers and/or namespaces. 192Feature names are case-insensitive, and they can be shortened as long 193as they remain unique. 194Some features also have alternative short names to which the same 195rules apply. 196The following features are supported: 197.Pp 198.TS 199tab(:); 200l l l. 201FULL NAME:SHORT NAME:CONTROLLER/NAMESPACE 202Arbitration::controller 203Power Management::controller 204LBA Range Type:range:namespace 205Temperature Threshold::controller 206Error Recovery::controller 207Volatile Write Cache:cache:controller 208Number of Queues:queues:controller 209Interrupt Coalescing:coalescing:controller 210Interrupt Vector Configuration:vector:controller 211Write Atomicity:atomicity:controller 212Asynchronous Event Configuration:event:controller 213Autonomous Power State Transition::controller 214Software Progress Marker:progress:controller 215.TE 216.Pp 217For an explanation of the individual features refer to the description 218of the 219.Qq SET FEATURES 220admin command in the NVMe specification. 221.It Xo 222.Nm 223.Cm format 224.Ar ctl[/ns] 225.Op Ar lba-format 226.Xc 227Formats the specified namespace or all namespaces of the specified 228controller. 229This command implies a 230.Nm 231.Cm detach 232and subsequent 233.Nm 234.Cm attach 235of the specified namespace(s), which will cause a changed LBA format 236to be detected. 237If no LBA format is specified the LBA format currently used by the 238namespace will be used. 239When formatting all namespaces without specifying a LBA format the LBA 240format of namespace 1 will be used. 241A list of LBA formats supported by a namespace can be queried with the 242.Nm 243.Cm identify 244command. 245.Pp 246Note that not all devices support formatting individual or all 247namespaces, or support formatting at all. 248.Pp 249LBA formats using a non-zero metadata size are not supported by 250.Nm 251or 252.Xr nvme 7D . 253.Pp 254The list of supported LBA formats on a namespace can be retrieved 255with the 256.Nm 257.Cm identify 258command. 259.It Xo 260.Nm 261.Cm secure-erase 262.Ar ctl[/ns] 263.Op Fl c 264.Xc 265Erases the specified namespace or all namespaces of the controller. 266The flag 267.Fl c 268will cause a cryptographic erase instead of a normal erase. 269This command implies a 270.Nm 271.Cm detach 272and 273.Nm 274.Cm attach 275of the specified namespace(s). 276.Pp 277Note that not all devices support erasing individual or all 278namespaces, or support erasing at all. 279.It Xo 280.Nm 281.Cm detach 282.Ar ctl[/ns] 283.Xc 284Temporarily detaches the 285.Xr blkdev 7D 286instance from the specified namespace or all namespaces of the controller. 287This will prevent I/O access to the affected namespace(s). 288Detach will only succeed if the affected namespace(s) are not 289currently opened. 290The detached state will not persist across reboots or reloads of the 291.Xr nvme 7D 292driver. 293.It Xo 294.Nm 295.Cm attach 296.Ar ctl[/ns] 297.Xc 298Attaches the 299.Xr blkdev 7D 300instance to the specified namespace or all namespaces of the controller. 301This will make I/O accesses to the namespace(s) possible again after a 302previous 303.Nm 304.Cm detach 305command. 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 314nvme1: model: INTEL SSDPEDMD800G4, serial: CVFT4134001R800CGN, FW rev: 8DV10049, NVMe v1.0 315 nvme1/1 (c1t1d0): Size = 763097 MB, Capacity = 763097 MB, Used = 763097 MB 316nvme4: 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 322nvme4/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 353nvme4/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 378nvme0: 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 386nvme4: 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 398The command line interface of 399.Nm 400is 401.Sy Evolving . 402The output of 403.Nm 404is 405.Sy Not-an-Interface 406and may change any time. 407.Sh SEE ALSO 408.Xr nvme 7D 409.Pp 410.Lk http://www.nvmexpress.org/specifications/ "NVMe specifications" 411