VMware ESXi and vSphere Cluster Management

Configure an iSCSI Software Initiator on VMware ESXi

Learn how to enable the ESXi software iSCSI initiator, bind VMkernel networking, discover targets, configure CHAP, rescan storage, and verify LUN paths.

The ESXi software iSCSI initiator allows a host to access block storage through a standard Ethernet network. This lesson covers enabling the adapter, associating it with an iSCSI VMkernel adapter, discovering target portals, validating LUN paths, and preparing the storage for VMFS datastore use.

How the Software iSCSI Initiator Works

iSCSI transports SCSI storage commands over TCP/IP. An iSCSI initiator is the client that requests storage, while an iSCSI target is the storage-system endpoint that provides block devices.

The ESXi software iSCSI initiator is a host software adapter. It uses ESXi networking and VMkernel interfaces to communicate with storage. A hardware iSCSI adapter performs some or all iSCSI processing on a dedicated physical adapter, whereas the software initiator uses host CPU and standard Ethernet networking.

• The ESXi host contains the software initiator and its unique initiator IQN.
• A VMkernel adapter supplies the host-side IP connectivity for iSCSI traffic.
• A target portal is the storage address and TCP port used to contact an iSCSI target.
• The target presents one or more LUNs, which are logical block-storage devices.
• After a LUN is visible, an administrator can create or mount a VMFS datastore.

Target discovery alone does not create a datastore. The storage system must authorize the initiator, map a LUN, and expose it through a reachable portal before ESXi can detect a usable device.

Prerequisites and Planning

Use a host managed through vCenter Server and the vSphere Client. If the host is not yet managed by vCenter, see Add ESXi Host To vCenter Server Inventory.

• Have the iSCSI target portal IP addresses or resolvable hostnames.
• Confirm the TCP port. The standard iSCSI port is 3260, although a storage environment may use another configured port.
• Prepare an existing VMkernel adapter dedicated or intended for iSCSI traffic.
• Confirm the storage VLAN, switch configuration, uplinks, routing, and firewall rules.
• Keep MTU values consistent end-to-end if jumbo frames are used. Do not enable jumbo frames on only part of the path.
• Ensure DNS works when target hostnames are entered. Using an IP address can help isolate DNS problems.
• Obtain the ESXi initiator IQN so the storage administrator can configure target ACLs, LUN masking, or initiator access.
• Confirm which LUNs should be presented and whether multiple hosts must share the resulting datastore.

Simple IP reachability is not the same as valid iSCSI port binding. A design can allow packets to reach the target while still failing to meet the supported association between the software adapter and VMkernel ports.

Enable the ESXi Software iSCSI Adapter

1. Open the vSphere Client and select the ESXi host.
2. Open the host's Storage view and locate the storage adapters or storage-device configuration area.
3. Choose the action to add an adapter, then select Software iSCSI adapter.
4. Complete the task and refresh the storage adapter inventory if necessary.
5. Select the new adapter and record its name, which normally uses the vmhba format, such as vmhba64.

Adding or activating the adapter creates the host-side iSCSI initiator identity. The exact vmhba number is assigned by ESXi and can differ between hosts.

Review the Initiator IQN and Set an Alias

Open the software adapter's general settings. Locate the iSCSI initiator name, normally displayed as an IQN, for example:

iqn.1998-01.com.example:esxi-host01

An IQN, or iSCSI Qualified Name, is the unique, globally formatted identifier used by iSCSI initiators and targets. Storage access controls commonly use this value to authorize the host and determine which LUNs it may see.

You may also configure an optional human-readable iSCSI alias, such as esxi-host01-iscsi. The alias helps administrators recognize the initiator, but it does not replace the unique IQN. Record the IQN exactly as displayed and provide it to the storage administrator before LUN discovery.

Bind the Adapter to VMkernel Networking

1. With the software iSCSI adapter selected, open its network port binding configuration.
2. Choose Add and select the intended iSCSI VMkernel adapter.
3. Repeat the operation for additional VMkernel adapters when implementing multipathing.
4. Apply the configuration and verify that each intended VMkernel port appears as bound.

Network port binding associates the software iSCSI adapter with selected VMkernel interfaces. This tells ESXi which host networking interfaces are intended for iSCSI sessions.

Single-path design

A basic connection can use one VMkernel adapter on a storage VLAN, one reachable target portal, and one physical network path. A successful rescan should show one target path to the presented LUN.

Multipathing design

Multipathing uses multiple storage paths for availability and, depending on the path-selection policy, load distribution. For a two-path design:

• Use two dedicated iSCSI VMkernel adapters.
• Use separate physical uplinks or storage fabrics where the design requires independent failure domains.
• Ensure each VMkernel port has the correct VLAN, IP configuration, and physical connectivity.
• Provide reachable target portals on the corresponding storage networks.
• Use separate IP subnets for bound VMkernel ports unless the storage design explicitly supports another valid arrangement.
• Avoid invalid active/standby uplink arrangements that cause both bound ports to use the same unintended network path.

Binding two VMkernel ports does not automatically guarantee two paths. Each bound port, target portal, physical route, and storage-side mapping must be functional.

Configure Target Discovery

Dynamic discovery

Dynamic discovery uses a target portal to ask the storage system which iSCSI targets are available. In the software adapter's discovery settings, open Dynamic Discovery or Send Targets, then add the target hostname or IP address and TCP port.

1. Select Add in the dynamic-discovery list.
2. Enter the target portal IP address or hostname.
3. Enter 3260, unless the storage system uses another configured port.
4. Apply the change.

A portal may reveal one or more target IQNs and their available paths. If the storage has multiple portal addresses, add each portal required by the design.

Static discovery

Static discovery manually defines a specific target IQN together with its portal address and port. It can be useful when the storage system does not support send-target discovery, when a tightly controlled target list is required, or when troubleshooting a known target identity. Dynamic and static discovery should reflect the storage administrator's design rather than being added indiscriminately.

Configure CHAP Authentication

CHAP, or Challenge-Handshake Authentication Protocol, authenticates iSCSI connections using a username and shared secret.

• One-way CHAP: the target authenticates the initiator.
• Mutual CHAP: the target authenticates the initiator and the initiator also authenticates the target.

Configure authentication in the software adapter's authentication settings or in the relevant target-specific settings, depending on the vSphere version and storage design. The storage system and ESXi must use the same authentication mode, username, and secret. Some environments apply authentication at the adapter level, while others support target-level settings.

Protect CHAP secrets like passwords. After changing authentication, reconnect or rescan the adapter and verify that the target and paths return to an available state.

Rescan the iSCSI Adapter

After adding discovery portals, changing VMkernel networking, changing access controls, or correcting CHAP, rescan the software adapter:

1. Select the software iSCSI adapter.
2. Choose Rescan or Rescan storage.
3. Wait for the task to complete.
4. Review targets, devices, paths, and datastore visibility.

A storage-adapter rescan refreshes target, path, device, and datastore information associated with the adapter. A host-wide storage rescan can be appropriate when validating broader storage or network changes.

Validate Targets, Devices, and Paths

Review the adapter's discovered targets and paths. Confirm that the expected target IQNs, portal addresses, LUNs, and path states appear. Do not create a datastore until the expected LUN is visible as a storage device.

Path count depends on the number of functional combinations among bound VMkernel interfaces, reachable target portals, physical network paths, and storage-side LUN mappings. In a planned two-path design, one path usually indicates that at least one of those components is missing or unavailable.

CLI verification

ESXi CLI output can corroborate vSphere Client settings. Replace vmhbaX with the actual software adapter identifier.

esxcli iscsi adapter list
esxcli iscsi adapter get -A vmhbaX
esxcli iscsi networkportal list -A vmhbaX
esxcli iscsi adapter discovery sendtarget list -A vmhbaX
esxcli storage core adapter rescan -A vmhbaX
esxcli storage core path list
esxcli storage core device list

Use the adapter commands to verify identity, bound network portals, and discovery configuration. Use the storage core commands to inspect paths and devices after a rescan.

Configuration Checklist

Discovery Method Comparison

Troubleshooting

The software adapter cannot be added

• Confirm that the ESXi host, rather than a cluster or unrelated inventory object, is selected.
• Check that the adapter-creation task completed successfully.
• Refresh the storage adapter inventory and verify with esxcli iscsi adapter list.

No target appears after dynamic discovery

• Check the portal address and TCP port.
• Verify the VMkernel VLAN, switch port group, uplink, routing, and firewall policy.
• Check MTU consistency if jumbo frames are configured.
• Use the portal IP address to isolate DNS resolution problems.
• Confirm that the target service is listening and permits the host's network.

The target is visible but no LUN or device appears

• Compare the ESXi IQN with the target ACL entry.
• Confirm that the LUN is mapped to the correct initiator or host group.
• Review LUN masking and storage-side access policies.
• Verify CHAP mode and credentials on both systems, then rescan.

Only one path appears when multiple paths are expected

• Review the network port binding entries.
• Validate every VMkernel interface, VLAN, uplink, and physical route.
• Confirm that all planned target portals are configured and reachable.
• Check storage-side portal and LUN mapping, then rescan.

CHAP authentication fails

• Check the username and secret for exact matches.
• Confirm that one-way and mutual CHAP modes match on both systems.
• Verify whether the credentials were configured at adapter-wide or target-specific scope.
• Reconnect or rescan after correcting the settings.

The LUN is visible but no datastore is available

Discovery and datastore provisioning are separate operations. Inspect the device and datastore inventory. Mount an existing compatible datastore when appropriate, or create a new VMFS datastore only after confirming that the LUN is intended for formatting. A device may already be claimed, contain an incompatible layout, or be intentionally excluded from formatting.

After Discovery: Create or Mount VMFS

Once the expected LUN and paths are visible, the next storage task is to create a VMFS datastore on the presented device or mount an existing compatible datastore. When multiple ESXi hosts will access the same datastore, configure identical target authorization and LUN presentation for every host, and verify that all hosts see the same datastore consistently.

For broader VMware administration study, see the VMware ESXi Online Course and the VMware ESXi topic index.

Exam-Relevant Notes

• The software iSCSI initiator is identified by a vmhba-style adapter name and an initiator IQN.
• An alias is descriptive; the IQN remains the identity used for authorization.
• Port binding links the software adapter to VMkernel networking; IP reachability alone does not prove valid binding.
• Target discovery does not guarantee LUN visibility, datastore creation, or multipath redundancy.
• Path count should match the intended combination of VMkernel ports, target portals, physical paths, and storage mappings.
• CHAP settings must match the storage system, including the authentication direction and credentials.