Managing host access

As a system administrator, you can add, list, and delete NVMe-oF host access by using ceph nvmeof commands.

About this task

Important: In-band authentication is supported on an initiator with Red Hat Enterprise Linux 9.5 or later. ESX is not supported.

Adding a host

Procedure

  • Use the host add command to grant an initiator host access to an NVMe‑oF subsystem. 
    
ceph nvmeof host add --nqn NQN [--host_nqn HOST_NQN] [--dhchap_key KEY_VALUE] [--psk PSK_VALUE] [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS] [--dhchap_controller_key KEY_VALUE]
    Note: You can specify a single host NQN, multiple specific host NQNs, or all hosts by using --host_nqn "*".
    Important:
    • Only use the --dhchap_key parameter with a single, specific host NQN. Do not use --host_nqn "*" with this parameter.
    • The --dhchap_controller_key parameter can be used only with a single host NQN. Do not use this parameter if a subsystem-level DHCHAP key is defined. If either condition is not met, the command fails.

    The following example adds a specific NVMe initiator host:

    [root@host01 ~]# ceph nvmeof host add --nqn nqn.2016-06.io.spdk:cnode1.group1 --host_nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3 --dhchap_key DHHC-1:00:abEcb12F100FNlZkIOkv37idpu/notvalid!!si1VQ09KhKv2g
Success
  • Add all NVMe initator hosts with a wildcard (*)

    The following example adds all NVMe initiator hosts:

    [root@host01 ~]# ceph nvmeof host add --nqn nqn.2016-06.io.spdk:cnode1.group1 --host_nqn "*"
Success
  • Specify multiple specific hosts by listing their NQNs separated by spaces.
    Note: Do not use commas between host NQNs or quotation marks (") around multiple NQNs. Use the following format:

    --host_nqn HOST01_NQN HOST02_NQN

    Example of specifying multiple specific hosts by listing their NQNs separated by spaces:

    [root@host01 ~]# ceph nvmeof host add --nqn nqn.2016-06.io.spdk:cnode1.group1 --host_nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3 nqn.2014-08.org.nvmexpress:uuid:123ddadf-f456-47b7-9416-b9bb233f67f4
Success

Setting or updating a host authentication key

Procedure

Use the host change_key command to change the in-band authentication keys for a host.
Important: Using the host change_key command without adding the --dhchap_key parameter removes the existing key.

This command only modifies host authentication keys. The command does not affect controller‑level DH‑HMAC‑CHAP keys.

ceph nvmeof host change_key --nqn NQN --host_nqn HOST01_NQN [--dhchap_key KEY_VALUE] [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]
For example, 
[root@host01 ~]# ceph nvmeof host change_key --nqn nqn.2016-06.io.spdk:cnode1.group1 --host_nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3

Changing a controller authentication key

Procedure

Use the host change_controller_key command to set or update the controller-level DH-HMAC-CHAP authentication key for a specific host that accesses an NVMe-oF subsystem. 
ceph nvmeof host change_controller_key --nqn NQN --host_nqn HOST_NQN --dhchap_controller_key KEY_VALUE [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]
Important:
  • This command applies only to a single, specific host NQN. Wildcard host NQNs (*) and multiple host NQNs are not supported.
  • The command fails if a subsystem‑level DH‑HMAC‑CHAP key is defined for the specified subsystem. Controller‑level and subsystem‑level DHCHAP keys cannot be used together.

The following example updates the controller authentication key for a specific initiator host:

[root@host01 ~]# ceph nvmeof host change_controller_key --nqn nqn.2016-06.io.spdk:cnode1.group1 --host_nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3 --dhchap_controller_key DHHC-1:00:abEcb12F100FNlZkIOkv37idpu/notvalid!!si1VQ09KhKv2g
Success

Deleting a controller authentication key

Procedure

Use the host del_controller_key command to remove the controller‑level DH‑HMAC‑CHAP authentication key for a specific host that accesses an NVMe‑oF subsystem. 
ceph nvmeof host del_controller_key --nqn NQN --host_nqn HOST_NQN [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]
Note:
  • This command applies only to a single, specific host NQN. Wildcard host NQNs (*) and multiple host NQNs are not supported.
  • Removing a controller‑level authentication key does not automatically apply a subsystem‑level DHCHAP key. After the key is removed, the host connects without a controller‑specific authentication key.

The following example removes the controller authentication key from a specific initiator host: 

[root@host01 ~]# ceph nvmeof host del_controller_key --nqn nqn.2016-06.io.spdk:cnode1.group1 --host_nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3
Success

Listing host access

Procedure

Use the host list command to list NVMe-oF subsystem host access. 
ceph nvmeof host list --nqn NQN [--clear-alerts] [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]
For example, 
[root@host01 ~]# ceph nvmeof host list --nqn nqn.2016-06.io.spdk:cnode1.group1
+--------------------------------------------------------------------+-------+----------+
|Nqn                                                                 |Use Psk|Use Dhchap|
+--------------------------------------------------------------------+-------+----------+
|*                                                                   |       |          |
|nqn.2014-08.org.nvmexpress:uuid:6da0b855-8b41-4ae0-bc9d-b1fdebb73d18|False  |True      |
+--------------------------------------------------------------------+-------+----------+
[root@host01 ~]#

Deleting host access

Procedure

  • Use the host del command to remove host access from NVMe-oF subsystems. 
    ceph nvmeof host del --nqn NQN [--host_nqn HOST01_NQN] [--dhchap_key KEY_VALUE] [--gw_group GW_GROUP] [--server-address SERVER_ADDRESS]
    For example, 
    [root@host01 ~]# ceph nvmeof host del --nqn nqn.2016-06.io.spdk:cnode1.group1 --host_nqn "*"
Success
  • To delete host access to multiple hosts, separate them by using a space.
    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 ~]# ceph nvmeof host del --nqn nqn.2016-06.io.spdk:cnode1.group1 --host-nqn nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3 nqn.2014-08.org.nvmexpress:uuid:123ddadf-f456-47b7-9416-b9bb233f67f4
Removing host nqn.2014-08.org.nvmexpress:uuid:950ddadf-f995-47b7-9416-b9bb233f66e3  access from nqn.2016-06.io.spdk:cnode1.group1: Success
Removing host nqn.2014-08.org.nvmexpress:uuid:123ddadf-f456-47b7-9416-b9bb233f67f4 access from nqn.2016-06.io.spdk:cnode1.group1: Success