iSCSI Storage Setup with ESXCLI

You can set up iSCSI storage using vSphere Web Client, commands in the esxcli iscsi namespace, or vicfg-iscsi commands (see iSCSI Storage Setup with vicfg-iscsi).

Setting Up Software iSCSI with ESXCLI

Software iSCSI setup requires several tasks. For each task, see the discussion of the corresponding command in this chapter or the reference information available from esxcli iscsi --help and the VMware Documentation Center. Specify one of the options listed in Connection Options in place of <conn_options>

1	Enable software iSCSI.

esxcli <conn_options> iscsi software set --enabled=true

2	Check whether a network portal, that is, a bound port, exists for iSCSI traffic.

esxcli <conn_options> iscsi adapter list

3	If no adapter exists, add one. Software iSCSI does not require port binding, but requires that at least one VMkernel NIC is available and can be used as an iSCSI NIC. You can name the adapter as you add it.

esxcli <conn_options> iscsi networkportal add -n <portal_name> -A <vmhba>

4	(Optional) Check the status.

esxcli <conn_options> iscsi software get

The system prints true if software iSCSI is enabled, or false if it is not enabled.

5	(Optional) Set the iSCSI name and alias.

esxcli <conn_options> iscsi adapter set --adapter=<iscsi adapter> --name=<name>

esxcli <conn_options> iscsi adapter set --adapter=<iscsi adapter> --alias=<alias>

6	Add a dynamic discovery address or a static discovery address.

The two types of target differ as follows:

■	With dynamic discovery, all storage targets associated with a host name or IP address are discovered. You run the following command.

esxcli <conn_options> iscsi adapter discovery sendtarget add --address=<ip/dns[:port]> --adapter=<adapter_name>

■	With static discovery, you must specify the host name or IP address and the iSCSI name of the storage target. You run the following command.

esxcli <conn_options> iscsi adapter discovery statictarget add --address=<ip/dns[:port]>

--adapter=<adapter_name> --name=<target_name>

When you later remove a discovery address, it might still be displayed as the parent of a static target. You can add the discovery address and rescan to display the correct parent for the static targets.

7	(Optional) Set the authentication information for CHAP (see Setting iSCSI CHAP and Enabling iSCSI Authentication). You can set per-target CHAP for static targets, per-adapter CHAP, or apply the command to the discovery address.

Adapter-level CHAP	esxcli iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba>
Discovery-level CHAP	esxcli iscsi adapter discovery sendtarget auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --address<sendtarget_address>
Target-level CHAP	esxcli iscsi adapter target portal auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --name<iscsi_iqn_name>

Supported Levels for CHAP lists what each supported level does.

For example:

esxcli <conn_options> iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=preferred --secret=uni_secret --adapter=vmhba33

8	(Optional) Set the authentication information for mutual CHAP by running esxcli iscsi adapter auth chap set again with --direction set to mutual and a different authentication user name and secret.

Adapter-level CHAP	esxcli iscsi adapter auth chap set --direction=mutual --mchap_username=<name2> --mchap_password=<pwd2> --level=[prohibited required] --secret=<string2> --adapter=<vmhba>
Discovery-level CHAP	esxcli iscsi adapter discovery sendtarget auth chap set --direction=mutual --mchap_username=<name2> --mchap_password=<pwd2> --level=[prohibited, required] --secret=<string2> --adapter=<vmhba> --address=<sendtarget_address>
Target-level CHAP	eesxcli iscsi adapter target portal auth chap set --direction=mutual --mchap_username=<nam2e> --mchap_password=<pwd2> --level=[prohibited required] --secret=<string2> --adapter=<vmhba> --name=<iscsi_iqn_name>

Important You are responsible for making sure that CHAP is set before you set mutual CHAP, and for using compatible levels for CHAP and mutual CHAP.

9	(Optional) Set iSCSI parameters.

Adapter-level parameters	esxcli iscsi adapter param set --adapter=<vmhba> --key=<key> --value=<value>
Discovery-level parameters	esxcli iscsi adapter discovery sendtarget param set --adapter=<vmhba> --key=<key> --value=<value> --address=<sendtarget_address>
Target-level parameters	esxcli iscsi adapter target portal param set --adapter=<vmhba> --key=<key> --value=<value> --address=<address> --name=<iqn.name>

See Listing and Setting iSCSI Parameters

10	After setup is complete, perform rediscovery and rescan all storage devices. For example:

esxcli <conn_options> iscsi adapter discovery rediscover

esxcli <conn_options> storage core adapter rescan --adapter=vmhba36

11	(Optional) If you want to make additional iSCSI login parameter changes (see Listing and Setting iSCSI Parameters), you must log out of the corresponding iSCSI session and log back in.

a	Run esxcli iscsi session remove to log out.

b	Run esxcli iscsi session add or rescan the adapter to add the session back.

Setting Up Dependent Hardware iSCSI with ESXCLI

Dependent hardware iSCSI setup requires several high-level tasks. For each task, see the discussion of the corresponding command in this chapter or the reference information available from esxcli iscsi --help and the VMware Documentation Center. Specify one of the options listed in Connection Options in place of <conn_options>.

1	Determine the iSCSI adapter type and retrieve the iSCSI adapter ID.

esxcli <conn_options> iscsi adapter list

2	(Optional) Set the iSCSI name and alias.

esxcli <conn_options> iscsi adapter set --adapter <adapter_name> --name=<name>

esxcli <conn_options> iscsi adapter set --adapter <adapter_name> --alias=<alias>

3	Set up port binding by following these steps:

a	Identify the VMkernel port of the dependent hardware iSCSI adapter.

esxcli <conn_options> iscsi logicalnetworkportal list --adapter=<adapter_name>

b	Connect the dependent hardware iSCSI initiator to the iSCSI VMkernel ports by running the following command for each port.

esxcli <conn_options> iscsi networkportal add --nic=<bound_vmknic> --adapter=<iscsi_adapter>

c	Verify that the ports were added to the dependent hardware iSCSI initiator.

esxcli <conn_options> iscsi physicalnetworkportal list --adapter=<adapter_name>

4	Add a dynamic discovery address or a static discovery address.

The two types of target differ as follows:

■	With dynamic discovery, all storage targets associated with a host name or IP address are discovered. You run the following command.

esxcli <conn_options> iscsi adapter discovery sendtarget add --address=<ip/dns[:port]> --adapter=<adapter_name>

■	With static discovery, you must specify the host name or IP address and the iSCSI name of the storage target. You run the following command.

esxcli <conn_options> iscsi adapter discovery statictarget add --address=<ip/dns[:port]>

--adapter=<adapter_name> --name=<target_name>

When you later remove a discovery address, it might still be displayed as the parent of a static target. You can add the discovery address and rescan to display the correct parent for the static targets.

5	(Optional) Set the authentication information for CHAP (see Setting iSCSI CHAP and Enabling iSCSI Authentication). You can set per-target CHAP for static targets, per-adapter CHAP, or apply the command to the discovery address.

Adapter-level CHAP	esxcli iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba>
Discovery-level CHAP	esxcli iscsi adapter discovery sendtarget auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --address<sendtarget_address>
Target-level CHAP	esxcli iscsi adapter target portal auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --name<iscsi_iqn_name>

Supported Levels for CHAP lists what each supported level does.

For example:

esxcli <conn_options> iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=preferred --secret=uni_secret --adapter=vmhba33

6	(Optional) Set the authentication information for mutual CHAP by running esxcli iscsi adapter auth chap set again with --direction set to mutual and a different authentication user name and secret.

Adapter-level CHAP	esxcli iscsi adapter auth chap set --direction=mutual --mchap_username=<name> --mchap_password=<pwd> --level=[prohibited required] --secret=<string2> --adapter=<vmhba>
Discovery-level CHAP	esxcli iscsi adapter discovery sendtarget auth chap set --direction=mutual --mchap_username=<name> --mchap_password=<pwd> --level=[prohibited, required] --secret=<string2> --adapter=<vmhba> --address=<sendtarget_address>
Target-level CHAP	esxcli iscsi adapter target portal auth chap set --direction=mutual --mchap_username=<name> --mchap_password=<pwd> --level=[prohibited required] --secret=<string2> --adapter=<vmhba> --name=<iscsi_iqn_name>

Important You are responsible for making sure that CHAP is set before you set mutual CHAP, and for using compatible levels for CHAP and mutual CHAP.

7	(Optional) Set iSCSI parameters.

Adapter-level parameters	esxcli iscsi adapter param set --adapter=<vmhba> --key=<key> --value=<value>
Discovery-level parameters	esxcli iscsi adapter discovery sendtarget param set --adapter=<vmhba> --key=<key> --value=<value> --address=<sendtarget_address>
Target-level parameters	esxcli iscsi adapter target portal param set --adapter=<vmhba> --key=<key> --value=<value> --address=<address> --name=<iqn.name>

See Listing and Setting iSCSI Parameters

8	After setup is complete, perform rediscovery and rescan all storage devices. For example:

esxcli <conn_options> iscsi adapter discovery rediscover

esxcli <conn_options> storage core adapter rescan --adapter=vmhba36

9	(Optional) If you want to make additional iSCSI login parameter changes (see Listing and Setting iSCSI Parameters), you must log out of the corresponding iSCSI session and log back in.

a	Run esxcli iscsi session remove to log out.

b	Run esxcli iscsi session add or rescan the adapter to add the session back.

Setting Up Independent Hardware iSCSI with ESXCLI

With independent hardware-based iSCSI storage, you use a specialized third-party adapter capable of accessing iSCSI storage over TCP/IP. This iSCSI initiator handles all iSCSI and network processing and management for your ESXi system.

You must install and configure the independent hardware iSCSI adapter for your host before you can access the iSCSI storage device. For installation information, see vendor documentation.

Hardware iSCSI setup requires a number of high-level tasks. For each task, see the discussion of the corresponding command-line option in this chapter or the reference information. Specify one of the options listed in Connection Options in place of <conn_options>.

1	Determine the iSCSI adapter type and retrieve the iSCSI adapter ID.

esxcli <conn_options> iscsi adapter list

2	Configure the hardware initiator (HBA) by running esxcli iscsi networkportal ipconfig with one or more of the following options.

-A|--adapter=<str>	iSCSI adapter name. (required).
-1|--dns1=<str>	iSCSI network portal primary DNS address.
-2|--dns2=<str>	iSCSI network portal secondary DNS address.
-g|--gateway=<str>	iSCSI network portal gateway address.
-i|--ip=<str>	iSCSI network portal IP address (required).
-n|--nic=<str>	iSCSI network portal (vmknic).
-s|--subnet=<str>	iSCSI network portal subnet mask (required).

3	(Optional) Set the iSCSI name and alias.

esxcli <conn_options> iscsi adapter set --adapter <adapter_name> --name=<name>

esxcli <conn_options> iscsi adapter set --adapter <adapter_name> --alias=<alias>

4	Add a dynamic discovery address or a static discovery address.

The two types of target differ as follows:

■	With dynamic discovery, all storage targets associated with a host name or IP address are discovered. You run the following command.

esxcli <conn_options> iscsi adapter discovery sendtarget add --address=<ip/dns[:port]> --adapter=<adapter_name>

■	With static discovery, you must specify the host name or IP address and the iSCSI name of the storage target. You run the following command.

esxcli <conn_options> iscsi adapter discovery statictarget add --address=<ip/dns[:port]>

5	(Optional) Set the authentication information for CHAP (see Setting iSCSI CHAP and Enabling iSCSI Authentication). You can set per-target CHAP for static targets, per-adapter CHAP, or apply the command to the discovery address.

Adapter-level CHAP	esxcli iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba>
Discovery-level CHAP	esxcli iscsi adapter discovery sendtarget auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --address<sendtarget_address>
Target-level CHAP	esxcli iscsi adapter target portal auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --name<iscsi_iqn_name>

Supported Levels for CHAP lists what each supported level does.

For example:

esxcli <conn_options> iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=preferred --secret=uni_secret --adapter=vmhba33

Mutual CHAP is not supported for independent hardware iSCSI storage.

6	(Optional) Set iSCSI parameters.

Adapter-level parameters	esxcli iscsi adapter param set --adapter=<vmhba> --key=<key> --value=<value>
Discovery-level parameters	esxcli iscsi adapter discovery sendtarget param set --adapter=<vmhba> --key=<key> --value=<value> --address=<sendtarget_address>
Target-level parameters	esxcli iscsi adapter target portal param set --adapter=<vmhba> --key=<key> --value=<value> --address=<address> --name=<iqn.name>

See Listing and Setting iSCSI Parameters

7	After setup is complete, run esxcli storage core adapter rescan --adapter=<iscsi_adapter> to rescan all storage devices.

8	After setup is complete, perform rediscovery and rescan all storage devices. For example:

esxcli <conn_options> iscsi adapter discovery rediscover

esxcli <conn_options> storage core adapter rescan --adapter=vmhba36