illumos: manual page: nvmeadm.8

NVMEADM(8) Maintenance Procedures NVMEADM(8)

NAME

nvmeadm - NVMe administration utility

SYNOPSIS

nvmeadm -h [command]
nvmeadm [-dv] list [-p -o field[,...]] [ctl[/ns][,...]]
nvmeadm [-dv] identify ctl[/ns][,...]
nvmeadm [-dv] get-logpage ctl[/ns][,...] logpage
nvmeadm [-dv] get-features ctl[/ns][,...] [feature-list]
nvmeadm [-dv] format ctl[/ns] [lba-format]
nvmeadm [-dv] secure-erase ctl[/ns] [-c]
nvmeadm [-dv] detach ctl[/ns]
nvmeadm [-dv] attach ctl[/ns]
nvmeadm [-dv] list-firmware ctl
nvmeadm [-dv] load-firmware ctl firmware-file [offset]
nvmeadm [-dv] commit-firmware ctl slot
nvmeadm [-dv] activate-firmware ctl slot

DESCRIPTION

The nvmeadm utility can be used to enumerate the NVMe controllers and their
namespaces, query hardware information from a NVMe controller or namespace,
and to format or secure-erase a NVMe controller or namespace.

The information returned by the hardware is printed by nvmeadm in a human-
readable form were applicable. Generally all 0-based counts are normalized
and values may be converted to human-readable units such as MB (megabytes),
W (watts), or C (degrees Celsius).

OPTIONS

The following options are supported:

-h Print a short help text for nvmeadm, or for an optionally specified
nvmeadm command.

-d Enable debugging output.

-v Enable verbose output.

ARGUMENTS

nvmeadm expects the following kinds of arguments:

command Any command nvmeadm understands. See section COMMANDS.

ctl[/ns] Specifies a NVMe controller and optionally a namespace within
that controller. The controller name consists of the driver name
"nvme" followed by an instance number. A namespace is specified
by appending a single "/" followed by the namespace ID to the
controller name. The namespace ID is the EUI64 of the namespace,
or a positive non-zero decimal number if the namespace doesn't
have an EUI64. For commands that don't change the device state
multiple controllers and namespaces can be specified as a comma-
separated list.

The list of controllers and namespaces present in the system can
be queried with the list command without any arguments.

logpage Specifies the log page name for the get-logpage command.

feature-list
A comma-separated list of feature names for the get-features
command. Feature names can be specified in upper or lower case
and can be shortened the shortest unique name. Some features may
also have an alternative short name.

lba-format
A non-zero integer specifying the LBA format for the format
command. The list of supported LBA formats on a namespace can be
retrieved with the nvmeadm identify command.

firmware-file
Specifies the name of a firmware file to be loaded into the
controller using the load-firmware command.

offset Specifies the byte offset at which to load firmware-file within
the controller's upload buffer. Vendors may require multiple
images to be loaded at different offsets before a firmware set is
committed to a slot.

slot Specifies the firmware slot into which a firmware set is
committed using the commit-firmware command, and subsequently
activated with the activate-firmware command. Slots and their
contents can be printed using the nvmeadm list-firmware command.

COMMANDS

nvmeadm list [-p -o field[,...]] [ctl[/ns][,...]]
Lists the NVMe controllers and their namespaces in the system and prints
a 1-line summary of their basic properties for each. If a list of
controllers and/or namespaces is given then the listing is limited to
those devices. By default, output is human-readable; however, a parsable
form can controlled by using the following options:

-p Rather than printing human-readable output, outputs an entry
for each of the specified controllers and namespaces. If no
controllers or namespaces are given as arguments, then the
primary namespace of each controller is listed and if the -v
option is specified, then all of the namespaces for a
controller are listed. This option requires that output
fields be selected with the -o option.

-o field[,...]
A comma-separated list of one or more output fields to be
used. Fields are listed below and the name is case
insensitive.

The following fields can be specified when using the parsable form:

MODEL The model number of the device, generally containing
information about both the manufacturer and the product.

SERIAL The NVMe controller's serial number.

FWREV The controller's firmware revision.

VERSION The version of the NVMe specification the controller supports.

SIZE The logical size in bytes of the namespace.

CAPACITY The amount of logical bytes that the namespace may actually
have allocated at any time. This may be different than size
due to the use of thin provisioning or due to administrative
action.

USED The number of bytes used in the namespace.

INSTANCE The name of the device node and instance of it.

NAMESPACE
The numerical value of the namespace which can be used as part
of other nvmeadm operations.

DISK The name of the disk device that corresponds to the namespace,
if any.

nvmeadm identify ctl[/ns][,...]
Print detailed information about the specified controllers and/or
namespaces. The information returned differs depending on whether a
controller or a namespace is specified. For an explanation of the data
printed by this command refer to the description of the "IDENTIFY" admin
command in the NVMe specification.

nvmeadm get-logpage ctl[/ns][,...] logpage
Print the specified log page of the specified controllers and/or
namespaces. Most log pages are only available on a per-controller basis.
Known log pages are:

error Error Information

health SMART/Health Information. A controller may support this log
page on a per-namespace basis.

firmware Firmware Slot Information

For an explanation of the contents of the log pages refer to the
description of the "GET LOGPAGE" admin command in the NVMe specification.

nvmeadm get-features ctl[/ns][,...] [feature-list]
Prints information about the specified features, or all features if none
are given, of the specified controllers and/or namespaces. Feature names
are case-insensitive, and they can be shortened as long as they remain
unique. Some features also have alternative short names to which the
same rules apply. The following features are supported:

FULL NAME SHORT NAME CONTROLLER/NAMESPACE
Arbitration controller
Power Management controller
LBA Range Type range namespace
Temperature Threshold controller
Error Recovery controller
Volatile Write Cache cache controller
Number of Queues queues controller
Interrupt Coalescing coalescing controller
Interrupt Vector Configuration vector controller
Write Atomicity atomicity controller
Asynchronous Event Configuration event controller
Autonomous Power State Transition controller
Software Progress Marker progress controller

For an explanation of the individual features refer to the description of
the "SET FEATURES" admin command in the NVMe specification.

nvmeadm format ctl[/ns] [lba-format]
Formats the specified namespace or all namespaces of the specified
controller. This command implies a nvmeadm detach and subsequent nvmeadm
attach of the specified namespace(s), which will cause a changed LBA
format to be detected. If no LBA format is specified the LBA format
currently used by the namespace will be used. When formatting all
namespaces without specifying a LBA format the LBA format of namespace 1
will be used. A list of LBA formats supported by a namespace can be
queried with the nvmeadm identify command.

Note that not all devices support formatting individual or all
namespaces, or support formatting at all.

LBA formats using a non-zero metadata size are not supported by nvmeadm
or nvme(4D).

The list of supported LBA formats on a namespace can be retrieved with
the nvmeadm identify command.

nvmeadm secure-erase ctl[/ns] [-c]
Erases the specified namespace or all namespaces of the controller. The
flag -c will cause a cryptographic erase instead of a normal erase. This
command implies a nvmeadm detach and nvmeadm attach of the specified
namespace(s).

Note that not all devices support erasing individual or all namespaces,
or support erasing at all.

nvmeadm detach ctl[/ns]
Temporarily detaches the blkdev(4D) instance from the specified namespace
or all namespaces of the controller. This will prevent I/O access to the
affected namespace(s). Detach will only succeed if the affected
namespace(s) are not currently opened. The detached state will not
persist across reboots or reloads of the nvme(4D) driver.

It is not an error to detach a namespace that is already detached, any
such request will be silently ignored.

nvmeadm attach ctl[/ns]
Attaches the blkdev(4D) instance to the specified namespace or all
namespaces of the controller. This will make I/O accesses to the
namespace(s) possible again after a previous nvmeadm detach command.

It is not an error to attach a namespace that is already attached, any
such request will be silently ignored.

nvmeadm list-firmware ctl
List currently active firmware slot, the next active firmware slot, and
the current contents of all firmware slots of an NVMe controller. This
is a synonym for the nvmeadm get-logpage ctl firmware command.

nvmeadm load-firmware ctl firmware-file [offset]
Loads firmware-file into the controller's upload memory at offset, the
default is 0. A vendor may require multiple files to be loaded at
different offsets before the firmware is committed to a slot.

nvmeadm commit-firmware ctl slot
Commits firmware previously loaded by the load-firmware command to slot.

nvmeadm activate-firmware ctl slot
Activates the firmware in slot slot. The firmware image in slot is
activated at the next NVM controller reset.

EXIT STATUS

The nvmeadm utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

Example 1: List all NVMe controllers and namespaces

# nvmeadm list
nvme1: model: INTEL SSDPEDMD800G4, serial: CVFT4134001R800CGN, FW rev: 8DV10049, NVMe v1.0
nvme1/1 (c1t1d0): Size = 763097 MB, Capacity = 763097 MB, Used = 763097 MB
nvme4: model: SAMSUNG MZVPV128HDGM-00000, serial: S1XVNYAGA00640, FW rev: BXW7300Q, NVMe v1.1
nvme4/1 (c2t2d0): Size = 122104 MB, Capacity = 122104 MB, Used = 5127 MB

Example 2: Identify a namespace

# nvmeadm identify nvme4/1
nvme4/1: Identify Namespace
Namespace Capabilities and Features
Namespace Size: 122104MB
Namespace Capacity: 122104MB
Namespace Utilization: 5127MB
Namespace Features
Thin Provisioning: unsupported
Number of LBA Formats: 1
Formatted LBA Size
LBA Format: 1
Extended Data LBA: no
Metadata Capabilities
Extended Data LBA: unsupported
Separate Metadata: unsupported
End-to-End Data Protection Capabilities
Protection Information Type 1: unsupported
Protection Information Type 2: unsupported
Protection Information Type 3: unsupported
Protection Information first: unsupported
Protection Information last: unsupported
End-to-End Data Protection Settings
Protection Information: disabled
Protection Information in Metadata: last 8 bytes
LBA Format 1
Metadata Size: 0 bytes
LBA Data Size: 512 bytes
Relative Performance: Best

Example 3: Get SMART/Health information (verbose)

# nvmeadm -v get-logpage nvme4/1 health
nvme4/1: SMART/Health Information
Critical Warnings
Available Space: OK
Temperature: OK
Device Reliability: OK
Media: OK
Volatile Memory Backup: OK
Temperature: 37C
Available Spare Capacity: 100%
Available Spare Threshold: 10%
Device Life Used: 0%
Data Read: 0GB
Data Written: 64GB
Read Commands: 52907
Write Commands: 567874
Controller Busy: 1min
Power Cycles: 6
Power On: 141h
Unsafe Shutdowns: 1
Uncorrectable Media Errors: 0
Errors Logged: 1

Example 4: Get Asynchronous Event Configuration information

# nvmeadm get-features nvme0,nvme4 event,power
nvme0: Get Features
Asynchronous Event Configuration
Available Space below threshold: disabled
Temperature above threshold: disabled
Device Reliability compromised: disabled
Media read-only: disabled
Power Management
Power State: 0
nvme4: Get Features
Asynchronous Event Configuration
Available Space below threshold: disabled
Temperature above threshold: disabled
Device Reliability compromised: disabled
Media read-only: disabled
Volatile Memory Backup failed: disabled
Power Management
Power State: 0

Example 5: Load and activate firmware

# nvmeadm list-firmware nvme3
nvme3: Firmware Slot Information
Active Firmware Slot: 4
Next Firmware Slot: 4
Firmware Revision for Slot 1: KNGND110 (read-only)
Firmware Revision for Slot 2: KNGND110
Firmware Revision for Slot 3: KNGND110
Firmware Revision for Slot 4: KNGND112
Firmware Revision for Slot 5: KNGND110

# nvmeadm -v load-firmware nvme3 KNGND113.bin
1740544 bytes downloaded.

# nvmeadm -v commit-firmware nvme3 5
Firmware committed to slot 5.

# nvmeadm -v activate-firmware nvme3 5
Slot 5 activated: NVM subsystem reset required - power cycle your system.

# nvmeadm list-firmware nvme3
nvme3: Firmware Slot Information
Active Firmware Slot: 4
Next Firmware Slot: 5
Firmware Revision for Slot 1: KNGND110 (read-only)
Firmware Revision for Slot 2: KNGND110
Firmware Revision for Slot 3: KNGND110
Firmware Revision for Slot 4: KNGND112
Firmware Revision for Slot 5: KNGND113

INTERFACE STABILITY

The command line interface of nvmeadm is Evolving. The output of nvmeadm
is Not-an-Interface and may change any time.