Managing masked namespaces with nvmeof-cli

In some cases, namespaces require isolation on a per-volume basis including multi-tenancy and for other various security purposes. By default, all hosts with access to a subsystem can see all namespaces within the subsystem. Use this information to change the visibility of a specific namespace, as well as to add and remove hosts from a masked namespace, one that is not automatically visible.

Before you begin

Get the namespace ID. You can retrieve the namespace ID by using the namespace list command. For more information, see Listing namespaces for a specific NVMe-oF subsystem or Listing namespaces for all NVMe-oF subsystems.

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

  • To create a namespace with a masked namespace, use the --no-auto-visible in the namespace add command.
  • To change a host from no restrictions, to one with restrictive visibility, use the --auto-visible no option in the namespace change_visibility command.
After a namespace is masked, only hosts that are added to the namespace can connect to it. In a case where a host is not added to the masked namespace, no output regarding the namespace will be visible when connecting to the relevant subsystem.

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

The following parameters are interchangeable:
  • --subsystem and -n
  • --host-nqn and -t

Creating a namespace with restrictive visibility

Create a namespace with restrictive visibility, by using the --no-auto-visible parameter to the with namespace add command. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace add --subsystem SUBSYSTEM_NQN --rbd-pool POOL_NAME --rbd-image IMAGE_NAME --no-auto-visible
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 --no-auto-visible
Namespaces in subsystem nqn.2016-06.io.spdk:cnode1.group1:
NSID| Bdev                    | RBD                  | 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    
==================================================================================================================================================================================
1   | bdev-32c94dd8-8754-     | nvmeof_images/image1 | 1 TiB  | 512 Bytes | 32c94dd8-8754-442f- |              1 | Restrictive |unset       | unset      | unset      | unset 
    | 442f-a12c-123abc456789  |                      |        |           | a12c-123abc456789   |                |             |            |            |            |
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2   | bdev-45c94ee8-ab56-     | nvmeof_images/image2 | 1 TiB  | 512 Bytes | 45c94ee8-ab56-332f- |              2 | Restrictive |unset       | unset      | unset      | unset  
    | 332f-a24c-abc123ae7890  |                      |        |           | a24c-abc123ae7890   |                |             |            |            |            |
The following parameters can optionally be added 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 is 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 using an existing RBD image, this image will not be deleted with the namespace.
Note: The --rbd-trash-image-on-delete parameter is only be used together with the --rbd-create-image parameter.
--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.

Changing namespace visibility

Namespace automatic visibility allows all hosts to view the namespace. To have a namespace be visible to all hosts, use the auto-visible yes option. To mask a namespace, for a namespace to only be visible to specific hosts, use the auto-visible no option.
Important: When namespace masking is enabled, and is changed from auto-visible yes to auto-visible no the command fails when there are previously connected hosts to the namespace unless the --force parameter is used.
Use the namespace change_visibility command to enable or disable namespace masking on a namespace. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace change_visibility --subsystem SUBSYSTEM_NQN --nsid NSID --auto-visible <yes|no> [--force]

Use no to enable namespace masking and yes to remove namespace masking.

Example for enabling namespace masking
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace change_visibility --subsystem nqn.2016-06.io.spdk:cnode1.group1 --nsid 3 –-auto-visible no
Example for removing namespace masking
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace change_visibility --subsystem nqn.2016-06.io.spdk:cnode1.group1 --nsid 3 –-auto-visible yes --force
Namespaces in subsystem nqn.2016-06.io.spdk:cnode1.group1:
NSID| Bdev                   | RBD                  | 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    
===========================================================================================================================================================================================================
2   | bdev-45c94ee8-ab56-    | nvmeof_images/image2 | 1 TiB  | 512 Bytes | 45c94ee8-ab56-332f- |              2 | All Hosts  | unset      | unset      | unset      | unset  
    | 332f-a24c-abc123ae7890 |                      |        |           | a24c-abc123ae7890   |                |            |            |            |            |          
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
3   | bdev-57c94ff8-7896-    | nvmeof_images/image3 | 1 TiB  | 512 Bytes | 57c94ff8-7896-332f  |              2 | All Hosts  | unset      | unset      | unset      | unset  
    | 332f-a24c-efg234ae7892 |                      |        |           | a24c-efg234ae7892   |                |            |            |            |            |

Adding a host to a masked namespace

Use the namespace add_host command to add a host to a masked namespace. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace add_host --subsystem SUBSYSTEM_NQN --nsid NSID --host-nqn HOST_NQN
Multiple host NQNs can be added to the namespace.
Note: Do not use commas between host NQNs or quotes (") around the multiple host NQNs. Use the following example format:

--host-nqn HOST01_NQN HOST02_NQN

For example, 
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace add_host --subsystem nqn.2016-06.io.spdk:cnode2.group3 --nsid 3 --host-nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3
Namespaces in subsystem nqn.2016-06.io.spdk:cnode2.group3:
NSID| Bdev                   | RBD                  | 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    
===========================================================================================================================================================================================================
1   | bdev-32c94dd8-8754-    | nvmeof_images/image1 | 1 TiB  | 512 Bytes | 32c94dd8-8754-442f- |              2 | nqn.2014-08.org.nvmexpress:uuid:     | unset      | unset      | unset      | unset  
    | 442f-a12c-123abc456789 |                      |        |           | a12c-123abc456789   |                | 793ddadf-e737-47b7-9416-b9bb233f65e4 |            |            |            |
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2   | bdev-45c94ee8-ab56-    | nvmeof_images/image2 | 1 TiB  | 512 Bytes | 45c94ee8-ab56-332f- |              2 | nqn.2014-08.org.nvmexpress:uuid:     | unset      | unset      | unset      | unset  
    | 332f-a24c-abc123ae7890 |                      |        |           | a24c-abc123ae7890   |                | 890ddadf-f883-47b7-9416-b9bb233f67f5 |            |            |            |          
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
3   | bdev-57c94ff8-7896-    | nvmeof_images/image3 | 1 TiB  | 512 Bytes | 57c94ff8-7896-332f  |              2 | nqn.2014-08.org.nvmexpress:uuid:     | unset      | unset      | unset      | unset  
    | 332f-a24c-efg234ae7892 |                      |        |           | a24c-efg234ae7892   |                |950ddadf-f995-47b7-9416-b9bb233f66e3  |            |            |            |

Removing a host from a masked namespace

Use the namespace del_host command to remove a host from a masked namespace. 
nvmeof-cli --server-address GATEWAY_IP --server-port SERVER_PORT namespace del_host --subsystem SUBSYSTEM_NQN --nsid NSID --host-nqn HOST_NQN
Multiple host NQNs can be removed from the namespace.
Note: Do not use commas between host NQNs or quotes (") around the multiple host NQNs. Use the following example format:

--host-nqn HOST01_NQN HOST02_NQN

For example, 
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace del_host --subsystem nqn.2016-06.io.spdk:cnode1.group1 --nsid 3 --host-nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3
[root@host01 ~]# nvmeof-cli --server-address 10.172.19.01 --server-port 5500 namespace add_host --subsystem nqn.2016-06.io.spdk:cnode2.group3 --nsid 3 --host-nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3
Namespaces in subsystem nqn.2016-06.io.spdk:cnode2.group3:
NSID| Bdev                   | RBD                  | 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    
===========================================================================================================================================================================================================
1   | bdev-32c94dd8-8754-    | nvmeof_images/image1 | 1 TiB  | 512 Bytes | 32c94dd8-8754-442f- |              2 | nqn.2014-08.org.nvmexpress:uuid:     | unset      | unset      | unset      | unset  
    | 442f-a12c-123abc456789 |                      |        |           | a12c-123abc456789   |                | 793ddadf-e737-47b7-9416-b9bb233f65e4 |            |            |            |
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2   | bdev-45c94ee8-ab56-    | nvmeof_images/image2 | 1 TiB  | 512 Bytes | 45c94ee8-ab56-332f- |              2 | nqn.2014-08.org.nvmexpress:uuid:     | unset      | unset      | unset      | unset  
    | 332f-a24c-abc123ae7890 |                      |        |           | a24c-abc123ae7890   |                | 890ddadf-f883-47b7-9416-b9bb233f67f5 |            |            |            |          
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
3   | bdev-57c94ff8-7896-    | nvmeof_images/image3 | 1 TiB  | 512 Bytes | 57c94ff8-7896-332f  |              2 | Restrictive                          | unset      | unset      | unset      | unset  
    | 332f-a24c-efg234ae7892 |                      |        |           | a24c-efg234ae7892   |                |                                      |            |            |            |