Set Up Software iSCSI with ESXCLI

Software iSCSI setup requires a number of high-level tasks.

You should be familiar with the corresponding command for each task. You can refer to the relevant documentation for each command or run esxcli iscsi --help in the console. Specify one of the options listed in Connection Options for vCLI Host Management Commands in place of <conn_options>.

Prerequisites

• Verify that you are familiar with iSCSI authentication. See Enabling iSCSI Authentication.
• Verify that you are familiar with CHAP. See Setting iSCSI CHAP.
• Verify that you are familiar with iSCSI parameters. See Listing and Setting iSCSI Parameters.

Procedure

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.
   • With dynamic discovery, all storage targets associated with a host name or IP address are discovered. You can 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 can 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.
   You can set per-target CHAP for static targets, per-adapter CHAP, or apply the command to the discovery address.

   Option	Command
   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>

   The following example sets adapter-level CHAP.

   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.

   Option	Command
   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	esxcli 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.

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

10. After setup is complete, perform rediscovery and rescan all storage devices.
    The following example performs the rediscovery and rescan operations.

    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, you must log out of the corresponding iSCSI session and log back in.
    1. Run esxcli iscsi session remove to log out.
    2. Run esxcli iscsi session add or rescan the adapter to add the session back.