VMware ESXi and vSphere Cluster Management

Configure a Software iSCSI Initiator on a VMware ESXi Host

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

iSCSI carries SCSI block-storage commands over a TCP/IP network. In an ESXi environment, an iSCSI initiator is the host-side client that connects to an iSCSI target, which is the storage-system endpoint presenting block devices.

This lesson covers the software iSCSI workflow in the vSphere Client: prepare the network, add the software adapter, configure its identity, bind VMkernel networking, discover a target, rescan storage, and verify devices and paths.

How the ESXi Software iSCSI Initiator Works

The ESXi software iSCSI adapter implements iSCSI in software. It uses standard physical network adapters through ESXi VMkernel adapters, rather than requiring a dedicated iSCSI hardware adapter.

When you enable the adapter, ESXi creates a storage adapter and assigns it a name using the vmhba convention, such as vmhba64. The adapter is the ESXi representation of the software initiator. Creating it does not, by itself, connect to a target or make a LUN visible.

A hardware-dependent iSCSI adapter performs some or all iSCSI processing in a storage or network adapter and depends on that adapter model and driver. A software adapter uses general-purpose ESXi processing and standard network connectivity, so its performance and supported design depend on ESXi, the network, and the storage platform.

Plan the Configuration

Before changing ESXi, obtain a reachable target with at least one LUN exported for the host. The storage administrator must create the target-side host access rules and map the intended LUNs to the ESXi initiator.

Required network design

• Create or identify an iSCSI-specific VMkernel adapter.
• Connect its virtual switch or distributed switch to the intended physical uplink.
• Use the correct iSCSI VLAN and an address appropriate for that storage network.
• Keep iSCSI traffic isolated from general management or virtual-machine traffic unless the design explicitly allows sharing.
• Maintain consistent MTU settings across the VMkernel interface, virtual switch, physical switches, and storage interfaces. Configure jumbo frames only when every device in the path supports the same design.
• Verify routing and firewall rules. The ESXi host must be able to reach the target portal on its configured TCP port.
• Ensure DNS works when a target hostname is used. An IP address can help isolate hostname-resolution problems during troubleshooting.
• For availability, use redundant iSCSI networks, VMkernel interfaces, uplinks, switches, and storage target interfaces when supported by the storage design.

In common port-binding configurations, each iSCSI VMkernel port is associated with one intended active physical uplink. The exact uplink policy depends on the vSphere switch type and the storage vendor’s supported design. Do not assume that simply adding multiple uplinks creates independent iSCSI paths.

Information to collect

Enable the Software iSCSI Adapter

1. In the vSphere Client, select the intended ESXi host.
2. Open the host’s storage management area and select the storage adapters view.
3. Choose the action to add a storage adapter.
4. Select the software iSCSI adapter type and confirm the operation.
5. Return to the storage adapters list and select the new iSCSI adapter.
6. Record the resulting vmhba identifier.

The adapter may initially have no targets, sessions, devices, or paths. That is expected. Adapter creation only enables the host-side iSCSI implementation; networking, discovery, authorization, and LUN presentation still need to be configured.

Configure the Initiator Identity

Open the software iSCSI adapter’s general settings. ESXi normally assigns an iSCSI Qualified Name, or IQN, automatically. An IQN is a structured identifier used to identify iSCSI initiators and targets.

You may also enter an optional iSCSI alias. The alias is a human-readable label that can make the initiator easier to recognize, but it does not replace the IQN for access control.

Bind iSCSI Traffic to VMkernel Networking

1. With the software iSCSI adapter selected, open its network port binding settings.
2. Choose the option to add or bind a VMkernel adapter.
3. Select the dedicated iSCSI VMkernel adapter.
4. Confirm the binding and review the resulting association.

Port binding tells ESXi which VMkernel networking interface is allowed to carry traffic for the software iSCSI adapter. The selected VMkernel interface must have working physical connectivity to the target network.

For multipathing, bind multiple VMkernel adapters only when the ESXi network design and the storage array support that configuration. A typical redundant design uses separate iSCSI networks, separate VLANs or fabrics where appropriate, and independent physical uplinks. Each VMkernel port should have the intended one-to-one relationship with its active uplink in the port-binding design.

Configure Target Discovery

Dynamic discovery

Dynamic discovery lets ESXi contact a target portal and learn the target IQNs and available storage associated with that portal. In the software iSCSI adapter’s target settings, add the target portal hostname or IP address and its TCP port.

A normal example is:

Target portal address: 10.20.30.50
Port: 3260
Discovery type: Dynamic
Authentication: None or CHAP, according to target policy

After ESXi contacts the portal, the target returns the targets that are available to the initiator. This does not guarantee that a LUN will appear: the storage system must also authorize the initiator and map a LUN to it.

Static discovery

Static discovery manually defines both a target IQN and its portal. It can be useful when the storage design requires an exact target entry, when discovery services are restricted, or when a vendor specifically recommends static entries.

Configure Authentication and Access Control

Target-side authorization commonly combines the ESXi initiator IQN with source IP or network rules, host groups, LUN masking, and optional CHAP. CHAP means Challenge-Handshake Authentication Protocol and allows an iSCSI endpoint to authenticate using a shared username and secret.

• Unidirectional CHAP: The target authenticates the initiator.
• Mutual CHAP: The target authenticates the initiator and the initiator also authenticates the target.

Configure CHAP in the software iSCSI adapter’s authentication settings. Select the same authentication mode, username, and secret that the storage target expects. For mutual CHAP, configure the additional target-to-initiator credentials as required by the vSphere release and storage platform.

Rescan and Validate Storage Discovery

Rescan the iSCSI adapter after changing target discovery, authentication, network bindings, or storage presentation. A rescan refreshes ESXi’s view of targets, devices, and paths; it does not create a datastore automatically.

1. Select the software iSCSI vmhba in the storage adapters view.
2. Start an adapter rescan. If the client offers separate device and VMFS rescans, perform the appropriate storage refreshes.
3. Review the adapter’s targets or discovered devices.
4. Open the paths view and confirm that the expected target connections are online.
5. Confirm that each expected LUN is visible and has the expected identifier and capacity.
6. If the LUN is new, proceed with datastore creation only after confirming that it is the intended device.
7. If the LUN contains an existing VMFS datastore, use the mount or recognize workflow rather than formatting it.

Never format, initialize, or resignature an existing LUN unless that action is explicitly intended and approved. A mistaken datastore operation can destroy access to existing virtual machines.

Optional ESXi CLI verification

When CLI use is permitted by the operational procedure, these commands provide useful read-only checks and a rescan operation:

esxcli iscsi adapter list
esxcli iscsi session list
esxcli storage core device list
esxcli storage core path list
esxcli storage core adapter rescan --all

Use the first command to identify the software iSCSI adapter, the session command to inspect connected targets, and the device and path commands to inspect LUN visibility and path state. Command availability and output can vary by ESXi version and permissions.

Practical Configuration Examples

Single-path iSCSI lab

1. Use one iSCSI VMkernel adapter with address 10.20.30.11 on the iSCSI VLAN.
2. Add the software iSCSI adapter and record its IQN.
3. Authorize that IQN on the storage target and map the intended LUN.
4. Bind the VMkernel adapter to the software iSCSI adapter.
5. Add dynamic portal 10.20.30.50 on TCP port 3260.
6. Rescan and confirm one active path to the assigned LUN.

Redundant two-network design

1. Use separate VMkernel adapters, for example 10.20.30.11 and 10.20.31.11, on independent iSCSI networks.
2. Ensure each VMkernel adapter uses its intended active physical uplink.
3. Bind both VMkernel adapters to the software iSCSI adapter.
4. Add the corresponding storage portals, such as 10.20.30.50 and 10.20.31.50.
5. Rescan and verify multiple active paths to the same presented LUN.

CHAP-protected target

Configure the same CHAP mode, username, and secret on the target and the ESXi software iSCSI adapter. Ensure that the target also authorizes the ESXi initiator IQN and maps the LUN. Rescan only after both sides are ready, then verify that the expected session, device, and paths appear.

Validation Checklist

Operational Practices

• Configure every ESXi host that must access shared storage consistently, including initiator authorization, VMkernel networking, portals, and LUN mappings.
• Validate storage visibility on all intended hosts before creating or mounting a shared datastore.
• Document each host’s initiator IQN, VMkernel addresses, VLANs, physical uplinks, target portals, target IQNs, and LUN mappings.
• Monitor path failures, authentication errors, target availability, link state, and storage connectivity changes.
• Use the storage vendor’s supported multipathing and path-selection design. Multiple visible paths are not useful if they do not provide independent network and storage connectivity.

Troubleshooting

The software iSCSI adapter is not listed

• Confirm that you selected the correct ESXi host.
• Return to the host storage adapters view and add the software adapter.
• Check recent tasks and host events for an operation failure.
• Verify that your permissions allow storage adapter management.

The target is not discovered

• Check the portal address, TCP port, VLAN, VMkernel IP configuration, routing, and firewall rules.
• Confirm that the iSCSI VMkernel adapter is bound to the software adapter.
• Verify that the target is online and listening on the configured port.
• If a hostname was entered, test with the target IP address to isolate DNS problems.
• Rescan after correcting the configuration.

The target is visible but no LUNs appear

• Compare the ESXi initiator IQN with the storage-side host definition.
• Confirm that the target has mapped the LUN to the correct host or host group.
• Review LUN masking, access-control rules, source network permissions, and CHAP settings.
• Correct both sides and rescan.

Only one path appears when redundancy is expected

• Verify that both VMkernel adapters are bound and both target portals are configured.
• Check physical uplinks, switch ports, VLANs, MTU, and routing on each network.
• Confirm that each target interface presents the same LUN.
• Review the paths view after a rescan.

Authentication failures occur

• Compare the CHAP mode, username, and secret on ESXi and the target.
• For mutual CHAP, confirm the reverse authentication settings as well.
• Verify that the target authorizes the current initiator IQN.
• Apply coordinated changes and rescan after the settings match.

Summary

A working ESXi software iSCSI connection requires more than adding an adapter. The complete chain is: an authorized ESXi initiator, an iSCSI-specific VMkernel network, reachable target portals, matching authentication, target-side LUN presentation, and a storage rescan. Finish by checking devices and path states, then create or mount a datastore only after confirming that the discovered LUN is the intended one.

For the related workflow, see Configure the iSCSI Software Initiator.