Digital 52

Understanding nvme-cli tool: basics


The nvme-cli utility has an incredible feature-set that’s difficult to grasp at first glance. We’re going to go over a few basic commands, list, id-ctrl, and smart-log that give the information necessary about the devices.

Lets take a look at all the commands provided first.

usage: nvme <command> [<device>] [<args>]

The '<device>' may be either an NVMe character device (ex: /dev/nvme0) or an
nvme block device (ex: /dev/nvme0n1).

The following are all implemented sub-commands:
  list              List all NVMe devices and namespaces on machine
  list-subsys       List nvme subsystems
  id-ctrl           Send NVMe Identify Controller
  id-ns             Send NVMe Identify Namespace, display structure
  list-ns           Send NVMe Identify List, display structure
  ns-descs          Send NVMe Namespace Descriptor List, display structure
  create-ns         Creates a namespace with the provided parameters
  delete-ns         Deletes a namespace from the controller
  attach-ns         Attaches a namespace to requested controller(s)
  detach-ns         Detaches a namespace from requested controller(s)
  list-ctrl         Send NVMe Identify Controller List, display structure
  get-ns-id         Retrieve the namespace ID of opened block device
  get-log           Generic NVMe get log, returns log in raw format
  telemetry-log     Retrieve FW Telemetry log write to file
  fw-log            Retrieve FW Log, show it
  smart-log         Retrieve SMART Log, show it
  error-log         Retrieve Error Log, show it
  effects-log       Retrieve Command Effects Log, show it
  get-feature       Get feature and show the resulting value
  set-feature       Set a feature and show the resulting value
  set-property      Set a property and show the resulting value
  format            Format namespace with new block format
  fw-commit         Verify and commit firmware to a specific slot (fw-activate in old version < 1.2)
  fw-download       Download new firmware
  admin-passthru    Submit an arbitrary admin command, return results
  io-passthru       Submit an arbitrary IO command, return results
  security-send     Submit a Security Send command, return results
  security-recv     Submit a Security Receive command, return results
  resv-acquire      Submit a Reservation Acquire, return results
  resv-register     Submit a Reservation Register, return results
  resv-release      Submit a Reservation Release, return results
  resv-report       Submit a Reservation Report, return results
  dsm               Submit a Data Set Management command, return results
  flush             Submit a Flush command, return results
  compare           Submit a Compare command, return results
  read              Submit a read command, return results
  write             Submit a write command, return results
  write-zeroes      Submit a write zeroes command, return results
  write-uncor       Submit a write uncorrectable command, return results
  sanitize          Submit a sanitize command
  sanitize-log      Retrive sanitize log, show it
  reset             Resets the controller
  subsystem-reset   Resets the controller
  ns-rescan         Rescans the NVME namespaces
  show-regs         Shows the controller registers or properties. Requires character device
  discover          Discover NVMeoF subsystems
  connect-all       Discover and Connect to NVMeoF subsystems
  connect           Connect to NVMeoF subsystem
  disconnect        Disconnect from NVMeoF subsystem
  gen-hostnqn       Generate NVMeoF host NQN
  dir-receive       Submit a Directive Receive command, return results
  dir-send          Submit a Directive Send command, return results
  version           Shows the program version
  help              Display this help

See 'nvme help <command>' for more information on a specific command

The following are all installed plugin extensions:
  netapp          NetApp vendor specific extensions
  huawei          Huawei vendor specific extensions
  wdc             Western Digital vendor specific extensions
  memblaze        Memblaze vendor specific extensions
  lnvm            LightNVM specific extensions
  intel           Intel vendor specific extensions

See 'nvme <plugin> help' for more information on a plugin

Honestly, it is quite extensive and a bit intimidating, but lets get through some of the basic commands first.



The list command lists the general information above each drive, most importantly listing the block device (node), serial number, model, and capacity.

# ./nvme list
Node             SN                   Model                                    Namespace Usage                      Format           FW Rev
---------------- -------------------- ---------------------------------------- --------- -------------------------- ---------------- --------
/dev/nvme0n1     BTXXXXXXXXXXXXXXXN   INTEL SSDPE2KX020T8                      1           2.00  TB /   2.00  TB    512   B +  0 B   VDV10120
/dev/nvme1n1     BTXXXXXXXXXXXXXXXN   INTEL SSDPE2KX020T8                      1           2.00  TB /   2.00  TB    512   B +  0 B   VDV10120
/dev/nvme2n1     BTXXXXXXXXXXXXXXXN   INTEL SSDPE2KX020T8                      1           2.00  TB /   2.00  TB    512   B +  0 B   VDV10120
/dev/nvme3n1     BTXXXXXXXXXXXXXXXN   INTEL SSDPE2KX020T8                      1           2.00  TB /   2.00  TB    512   B +  0 B   VDV10120


id-ctrl works well in conjunction with the list command. Once you get the node you can use it against id-ctrl to identify the more in-depth details about the device.

# ./nvme id-ctrl /dev/nvme0n1
NVME Identify Controller:
vid     : 0x8086
ssvid   : 0x8086
mn      : INTEL SSDPE2KX020T8
fr      : VDV10120
rab     : 0
ieee    : 5cd2e4
cmic    : 0
mdts    : 5
cntlid  : 0
ver     : 10200
rtd3r   : 1e8480
rtd3e   : 2dc6c0
oaes    : 0
ctratt  : 0
oacs    : 0x6
acl     : 3
aerl    : 3
frmw    : 0x2
lpa     : 0x2
elpe    : 63
npss    : 0
avscc   : 0
apsta   : 0
wctemp  : 343
cctemp  : 353
mtfa    : 0
hmpre   : 0
hmmin   : 0
tnvmcap : 2000398934016
unvmcap : 0
rpmbs   : 0
edstt   : 0
dsto    : 0
fwug    : 0
kas     : 0
hctma   : 0
mntmt   : 0
mxtmt   : 0
sanicap : 0
hmminds : 0
hmmaxd  : 0
sqes    : 0x66
cqes    : 0x44
maxcmd  : 0
nn      : 1
oncs    : 0x6
fuses   : 0
fna     : 0x4
vwc     : 0
awun    : 0
awupf   : 0
nvscc   : 0
acwu    : 0
sgls    : 0
subnqn  :
ioccsz  : 0
iorcsz  : 0
icdoff  : 0
ctrattr : 0
msdbd   : 0
ps    0 : mp:25.00W operational enlat:0 exlat:0 rrt:0 rrl:0
          rwt:0 rwl:0 idle_power:- active_power:-

There is a lot of data here, so lets just go over the most important.

  • sn - This is pretty obvious, but this is the serial number of the device.
  • mn - The second most obvious item is mn as its the make and or model of the device.
  • fr - stands for firmware revision, in case you need to update it later.
  • tnvmcap - This is the total nvme capacity, in bytes.

For a more detail explanation of all the options, go to the nvme specs document here:


Arguably one of the more useful metrics available via nvme-cli is smart-log, which doles out the SMART information. While this can be gathered using the newer smartctl versions, the human readability of this is better than smartctl. It displays information like percentage_used, media-errors, critical_warning and num_err_log_entries. These are useful to help understand and test the capability of an NVMe device.

# ./nvme smart-log /dev/nvme0n1
Smart Log for NVME device:nvme0n1 namespace-id:ffffffff
critical_warning                    : 0
temperature                         : 36 C
available_spare                     : 100%
available_spare_threshold           : 10%
percentage_used                     : 1%
data_units_read                     : 152,938,914
data_units_written                  : 175,044,490
host_read_commands                  : 5,037,964,015
host_write_commands                 : 5,973,916,988
controller_busy_time                : 1,378
power_cycles                        : 56
power_on_hours                      : 1,667
unsafe_shutdowns                    : 48
media_errors                        : 0
num_err_log_entries                 : 0
Warning Temperature Time            : 0
Critical Composite Temperature Time : 0
Thermal Management T1 Trans Count   : 0
Thermal Management T2 Trans Count   : 0
Thermal Management T1 Total Time    : 0
Thermal Management T2 Total Time    : 0


There are quite a few commands available using nvme-cli. I hope this gives a useful summary of the basic commands and information provided by those commands.

comments powered by Disqus