Managing namespaces with nvmeof-cli

As a system administrator, you can manage NVMe-oF subsystem namespaces by using the command-line interface (CLI). Use this information to add, delete, resize, and list namespaces. You can also get I/O statistics, change load-balancing groups, and set Quality of Service (QoS) limits for namespaces.

Before you begin

Use this information to manage namespaces with no masking. To manage masked namespaces, use the commands that are detailed in Managing masked namespaces with nvmeof-cli.

Managing NVMe-oF subsystem namespaces 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

Namespaces are automatically load balanced across gateways in a gateway group during namespace addition and namespace deletion. For more information about load balancing, see Using load balancing with scale-up and scale-down with nvmeof-cli.

At any point, you can use the -h or --help parameters for command help.

The following parameters are interchangeable:
  • --subsystem and -n
  • --uuid and -u
  • --rbd-pool and -p
  • --rbd-image and -i
  • --rbd-create-image and -c
  • --block-size and -s
Important: Namespaces might not be visible if an initiator is connected to two different gateway groups with the same NQN.
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 namespace

Use the namespace add command to add a namespace to an NVMe-oF subsystem. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace add --subsystem SUBSYSTEM_NQN --rbd-pool POOL_NAME --rbd-image IMAGE_NAME
For example, 
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace add --subsystem nqn.2016-06.io.spdk:cnode1.group1 --rbd-pool pool1 --rbd-image image1
You can optionally add the following parameters to the command:
--uuid
Enter the namespace UUID. When multiple namespaces exist on the same subsystem, each namespace has its own UUID.
Note: When this parameter is not used, the gateway automatically generates a UUID value.
--nsid
Enter the namespace ID of the subsystem.
Note: When this parameter is not used, the gateway automatically generates an NSID value, the next available value on the subsystem, starting with 1.
--block-size
Enter the namespace block size.
--size
The size is indicated in bytes, by default. To indicate a different size type, specify the unit. The supported size units are: KB, KiB, MB, MiB, GB, GiB, TB, and TiB.
Note: The --size parameter can only be used together with the --rbd-create-image parameter.
--rbd-create-image
Create an image within any RADOS Block Device (RBD) application-enabled pool.
Note: The --size parameter must be used together with --rbd-create-image.
--force
Use the --force parameter to create a namespace even if its image is already used by another namespace.
--rbd-trash-image-on-delete
Instructs the gateway to automatically delete the Ceph Block Device (RBD) image that is created for the namespace when the namespace is deleted.
This parameter only applies to RBD images created when adding a namespace. If the namespace was added by using an existing RBD image, this image will not be deleted with the namespace.
Note: The --rbd-trash-image-on-delete parameter can only be used together with the --rbd-create-image parameter.
--no-auto-visible
Makes the namespace visible only to specific hosts. For more information and instructions, see Managing masked namespaces with nvmeof-cli.
--read-only
Use to create a namespace that cannot be modified. Use read-only namespaces to prevent namespace changes during operations such as during disaster recovery tests. The Read-Only or Read-Write status can be seen in the namespace list output.
Important: Once a namespace is flagged as read-only it cannot be modified to read-write.

Examples

  • Add a namespace while creating a Ceph Block Device (RBD) image and pool, while setting the image to automatically delete during the namespace deletion. 
    [root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace add --subsystem nqn.2016-06.io.spdk:cnode1.group1 --rbd-pool pool1 --rbd-create-image --rbd-image image1 --size 1024 --rbd-trash-image-on-delete
  • Add a namespace with an already created Ceph Block Device (RBD) image in pool. 
    [root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace add --subsystem nqn.2016-06.io.spdk:cnode1.group1 --rbd-image image1 --rbd-pool rbd --nsid 1

Listing namespaces for a specific NVMe-oF subsystem

Use the namespace list command to list namespaces of an NVMe-oF subsystem. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace list --subsystem SUBSYSTEM_NQN [--uuid UUID] [--nsid NSID]
The following is an example output for two namespaces on a subsystem. 
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace list --subsystem nqn.2016-06.io.spdk:cnode1.group1
Namespaces in subsystem nqn.2016-06.io.spdk:cnode1.group1:
NSID| Bdev                    | RBD   | RBD    | Mode       | Image    | Block | UUID                | Load            | R/W IOs    | R/W MB     | Read MBs   | Write MBs
    | Name                    | Pool  | Image  |            | Size     | Size  |                     | Balancing Group | per second | per second | per second | per second    
==============================================================================================================================================================
1   | bdev-32c94dd8-8754-     | pool1 | image1 | Read-Write | 1024 MiB | 512 B | 32c94dd8-8754-442f- | 2               | unlimited  | unlimited  | unlimited  | unlimited  
    | 442f-a12c-123abc456789  |       |        |            |          |       | a12c-123abc456789   |                 |            |            |            |            
--------------------------------------------------------------------------------------------------------------------------------------------------------------
2   | bdev-45c94ee8-ab56-     | pool1 | image2 | Read-Only  | 1024 MiB | 512 B | 45c94ee8-ab56-332f- | 1               | unlimited  | unlimited  | unlimited  | unlimited  
    | 332f-a24c-abc123ae7890  |       |        |            |          |       | a24c-abc123ae7890   |                 |            |            |            |
You can optionally add the following parameters to the command:
--uuid
Enter the namespace UUID. When multiple namespaces exist on the same subsystem, each namespace has its own UUID.

Use this parameter to display results for a specific UUID. When listing namespaces with no specific IDs, all namespaces from the specified subsystem are listed.

--nsid
Enter the namespace ID of the subsystem.

Use this parameter to display results for a specific namespace ID. When listing with no specific IDs, all namespaces from the specified subsystem are listed.

Listing namespaces for all NVMe-oF subsystems

Use the namespace list command to list namespaces from all connected NVMe-oF subsystems. To list all relevant namespaces from all subsystems, omit the --subsystem parameter, or enter "*". 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace list [--uuid UUID] [--nsid NSID]
The following is an example output for all namespaces on a subsystem. 
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace list
Namespaces in all subsystems:
NQN                               | NSID| Bdev                    | RBD        | Mode       | Image  | Block | UUID                | Load            | Visibility | R/W IOs    | R/W MB     | Read MBs   | Write MBs
                                  |     | Name                    | Image      |            | Size   | Size  |                     | Balancing Group |            | per second | per second | per second | per second    
==========================================================================================================================================================================================================
nqn.2016-06.io.spdk:cnode1.group1 | 1   | bdev-32c94dd8-8754-     | rbd/image1 | Read-Write | 10 MiB | 512 B | 32c94dd8-8754-442f- | 1               | All Hosts  | unset      | unset      | unset      | unset      
                                  |     | 442f-a12c-123abc456789  |            |            |        |       | a12c-123abc456789   |                 |            |            |            |            
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
nqn.2016-06.io.spdk:cnode1.group1 | 2   | bdev-45c94ee8-ab56-     | rbd_image2 | Read-Only  | 10 MiB | 512 B | 45c94ee8-ab56-332f- | 2               | All Hosts  | unset      | unset      | unset      |  unset      
                                  |     | 332f-a24c-abc123ae7890  |            |            |        |       | a24c-abc123ae7890   |                 |            |            |            |            |          
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
nqn.2016-06.io.spdk:cnode2.group1 | 1   | bdev-5dev4dd8-8754-     | rbd/image3 | Read-Only  | 10 MiB | 512 B | 5dev4dd8-8754-442f- | 1               | All Hosts  | unset      | unset      | unset      | unset      
                                  |     | 442f-a12c-123abc456123  |            |            |        |       | a12c-123abc456123   |                 |            |            |            |            
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
nqn.2016-06.io.spdk:cnode2.group1 | 2   | bdev-370c4ee8-ab56-     | rbd_image4 | Read-Only  | 10 MiB | 512 B | 370c4ee8-ab56-332f- | 2               | All Hosts  | unset      | unset      | unset      | unset      
                                  |     | 332f-a24c-abc123ae7567  |            |            |        |       | a24c-abc123ae7567   |                 |            |            |            |            |
You can optionally add the following parameters to the command:
--uuid
Enter the namespace UUID. When multiple namespaces exist on the same subsystem, each namespace has its own UUID.

Use this parameter to display results for the specific UUID from all subsystems. When listing namespaces with no specific IDs, all namespaces from all subsystems are listed.

--nsid
Enter the namespace ID of the subsystem.

Use this parameter to display results for a specific namespace ID from all subsystems. When listing namespaces with no specific IDs, all namespaces from all subsystems are listed.

Deleting a namespace

Use the namespace del command to delete a namespace from an NVMe-oF subsystem. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace del --subsystem SUBSYSTEM_NQN --nsid NSID [--i-am-sure]
The --i-am-sure parameter must be used when the namespace is set with --rbd-trash-image-on-delete.
Important: If the automatic deletion for Ceph Block Device (RBD) images on the namespace is set and the --i-am-sure parameter is not used the command fails.
For example, 
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace del --subsystem nqn.2016-06.io.spdk:cnode1.group1 --nsid 1

Resizing a namespace

Important: A block device image can be expanded but not reduced.

Use the namespace resize command to increase the size of a namespace.

For more information, see Expanding a block device image with nvmeof-cli. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace resize --subsystem SUBSYSTEM_NQN --nsid NSID --size SIZE

The size is indicated in bytes, by default. To indicate a different size type, specify the unit. The supported size units are: KB, KiB, MB, MiB, GB, GiB, TB, and TiB.

For example, 
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace resize --subsystem nqn.2016-06.io.spdk:cnode1.group1 --nsid 2 --size 1536
In this example, the size of NSID 2 on the nqn.2016-06.io.spdk:cnode1.group1subsystem is being increased to 1536 bytes.

Getting I/O statistics

Use the namespace get_io_stats command to retrieve I/O statistics for a namespace on a subsystem. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace get_io_stats --subsystem SUBSYSTEM_NQN --nsid NSID
For example, 
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace get_io_stats --subsystem nqn.2016-06.io.spdk:cnode1.group1 --nsid 1

Changing the Ceph Block Device image delete policy for during a namespace deletion

If the Ceph Block Device (RBD) image was set to delete with a namespace, use the command namespace set_rbd_trash_image to keep it after the namespace deletion. Use this command to change an image that was created by using the --rbd-create-image parameter during the namespace creation.

The image status for automatic deletion can be changed at any time, until the namespace is deleted, only if the namespace was created with the --rbd-trash-image-on-delete parameter. For more information, see Adding a namespace.

nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace set_rbd_trash_image --subsystem SUBSYSTEM_NQN --nsid NSID --rbd-trash-image-on-delete <yes|no>

Set the --rbd-trash-image-on-delete option to yes to set automatic image deletion and set to no to remove automatic deletion, keeping the image after deleting the namespace.