Managing subsystems with nvmeof-cli

As a system administrator, you can add, list, and delete NVMe-oF subsystems by using the command-line interface (CLI).

Before you begin

Managing NVMe-oF subsystems with the CLI requires the nvmeof-cli alias setup. For more information about defining the alias, see step 1 of Defining an NVMe-oF subsystem with nvmeof-cli.

About this task

At any point, you can use the -h or --help parameters for command help.
The following parameters are interchangeable:
  • --subsystem and -n
  • --serial-number and -s
  • --max-namespaces and -m
  • --dhchap-key and -k
Note: Creating subsystems with the same NQNs within more than one gateway group causes issues with the NVMe-oF initiators.
Use the commands listed here to manage your subsystems.
Note: The commands here show the SUBSYSTEM_NQN with the subsystem NQN and group name, assuming that the --no-group-append was not added when adding the subsystem. For more information, see Managing subsystems with nvmeof-cli.

Adding a subsystem

Use the subsystem add command to add an NVMe-oF subsystem. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT subsystem add --subsystem SUBSYSTEM_NQN  [--serial-number SERIAL_NUMBER] [--max-namespaces MAX_NAMESPACES]  [--dhchap-key KEY_VALUE]
The SUBSYSTEM_NQN is a user-defined string with and appended group name, assuming that the --no-group-append was not added when adding the subsystem. In this example it is defined as nqn.2016-06.io.spdk:cnode1.group1.
Important: Use this flag with extreme caution. When using this flag, if an initiator is connected to two different gateway groups with the same subsystem NQNs, not all NVMe-oF devices are listed with the nvme list command.
Important: NQN and gateway name values must not contain an underscore character.

The default --server-port value is 5500.

The following parameters can optionally be added to the command:
--serial-number
If the serial number is not specified, the number is randomly generated.

Input type: String

--max-namespaces
The maximum number of namespaces per subsystem default is 256.

Input type: Number

--dhchap-key
Use this flag to add a generated DH-HMAC-CHAP key for use with bidirectional in-band authentication.

Input type: String

For example, 
[root@host01 ~]# nvmeof-cli --server-address 10.0.195.226 --server-port 5500 subsystem add --subsystem nqn.2016-06.io.spdk:cnode1.group1 --serial-number 1 --dhchap-key DHHC-1:00:abEcb12F100FNlZkIOkv37idpu/notvalid!!si1VQ09KhKv2g:
Adding subsystem nqn.2016-06.io.spdk:cnode1.group1: Successful

Changing a subsystem authentication key

Use the subsystem change_key command to change the in-band authentication keys for a subsystem.
Important: Using the subsystem change_key command without adding the --dhchap-key parameter removes the existing key.
subsystem change_key --subsystem SUBSYSTEM_NQN --dhchap-key KEY_VALUE
For example, 
[root@host01 ~]# nvmeof-cli subsystem change_key --subsystem nqn.2016-06.io.spdk:cnode1.group1 --dhchap-key DHHC-1:00:abEcb12F100FNlZkIOkv37idpu/notvalid!!si1VQ09KhKv2g:

Listing subsystems

Use the subsystem list command to list NVMe-oF subsystems associated with a specific gateway. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT subsystem list [--subsystem SUBSYSTEM_NQN] [--serial-number SERIAL_NUMBER]
For example, 
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 subsystem list
Subsystems:
Subtype| NQN                        | HA State | Serial            | Controller IDs | Namespace | Max
       |                            |          | Number            |                | Count     | Namespaces
=============================================================================================================
NVMe   | nqn.2016-06.10.spdk:cnode1.group1 | enabled  | Ceph1230985676540 | 4081-6120      | 32        | 256        
-------------------------------------------------------------------------------------------------------------
NVMe   | nqn.2016-06.10.spdk:cnode2.group1 | enabled  | Ceph5400985676123 | 4081-6120      | 32        | 256

Deleting a subsystem

Use the subsystem del command to delete NVMe-oF subsystems associated with a specific gateway. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT subsystem del --subsystem SUBSYSTEM_NQN [--force]
Use the --force parameter to delete any existing subsystem namespaces before deleting the subsystem.
Important: The --force parameter is optional but if not set and the subsystem contains a namespace, the subsystem deletion results in failure.
For example, 
[root@host01 ~]# nvmeof-cli --server-address 10.0.195.226 --server-port 5500 subsystem del --subsystem nqn.2016-06.io.spdk:cnode1.group1 --force