Setting iSCSI CHAP

iSCSI storage systems authenticate an initiator using a name and key pair.
ESXi
systems support Challenge Handshake Authentication Protocol (CHAP).
Using CHAP for your SAN implementation is a best practice. The
ESXi
host and the iSCSI storage system must have CHAP enabled and must have common credentials. During iSCSI login, the iSCSI storage system exchanges its credentials with the
ESXi
system and checks them.
You can set up iSCSI authentication by using the
vSphere Client
, as discussed in the
vSphere Storage
documentation or by using the
esxcli
command, discussed in Enabling iSCSI Authentication. To use CHAP authentication, you must enable CHAP on both the initiator side and the storage system side. After authentication is enabled, it applies for targets to which no connection has been established, but does not apply to targets to which a connection is established. After the discovery address is set, the new volumes to which you add a connection are exposed and can be used.
For software iSCSI and dependent hardware iSCSI,
ESXi
hosts support per-discovery and per-target CHAP credentials. For independent hardware iSCSI,
ESXi
hosts support only one set of CHAP credentials per initiator. You cannot assign different CHAP credentials for different targets.
When you configure independent hardware iSCSI initiators, ensure that the CHAP configuration matches your iSCSI storage. If CHAP is enabled on the storage array, it must be enabled on the initiator. If CHAP is enabled, you must set up the CHAP authentication credentials on the
ESXi
host to match the credentials on the iSCSI storage.

Supported CHAP Levels

To set CHAP levels with
esxcli iscsi adapter setauth
, specify one of the values in Table 1 for
<level>
. Only two levels are supported for independent hardware iSCSI.
Mutual CHAP is supported for software iSCSI and for dependent hardware iSCSI, but not for independent hardware iSCSI.
Ensure that CHAP is set to
chapRequired
before you set mutual CHAP, and use compatible levels for CHAP and mutual CHAP. Use different passwords for CHAP and mutual CHAP to avoid security risks.
Supported Levels for CHAP
Level
Description
Supported
chapProhibited
Host does not use CHAP authentication. If authentication is enabled, specify
chapProhibited
to disable it.
Software iSCSI
Dependent hardware iSCSI
Independent hardware iSCSI
chapDiscouraged
Host uses a non-CHAP connection, but allows a CHAP connection as fallback.
Software iSCSI
Dependent hardware iSCSI
chapPreferred
Host uses CHAP if the CHAP connection succeeds, but uses non-CHAP connections as fallback.
Software iSCSI
Dependent hardware iSCSI
Independent hardware iSCSI
chapRequired
Host requires successful CHAP authentication. The connection fails if CHAP negotiation fails.
Software iSCSI
Dependent hardware iSCSI

Returning Authentication to Default Inheritance

The values of iSCSI authentication settings associated with a dynamic discovery address or a static discovery target are inherited from the corresponding settings of the parent. For the dynamic discovery address, the parent is the adapter. For the static target, the parent is the adapter or discovery address.
  • If you use the
    vSphere Client
    to modify authentication settings, you must deselect the
    Inherit from Parent
    check box before you can make a change to the discovery address or discovery target.
  • If you use
    esxcli iscsi
    commands, the value you set overrides the inherited value. You can set CHAP at the following levels.
    • esxcli iscsi adapter auth chap [get|set]
    • esxcli iscsi adapter discovery sendtarget auth chap [get|set]
    • esxcli iscsi adapter target portal auth chap [get|set]
Inheritance is relevant only if you want to return a dynamic discovery address or a static discovery target to its inherited value. In that case, use one of the following commands.
  • Dynamic discovery
    esxcli iscsi adapter discovery sendtarget auth chap set --inherit
  • Static discovery
    esxcli iscsi adapter target portal auth chap set --inherit
You can set target-level CHAP authentication properties to be inherited from the send target level and set send target level CHAP authentication properties to be inherited from the adapter level. Resetting adapter-level properties is not supported.