Short answer: software iSCSI port binding is managed with esxcli iscsi networkportal. Use list to see the bound VMkernel ports, add -A vmhbaNN -n vmkN to bind one, and remove -A vmhbaNN -n vmkN to unbind it. When ESX refuses because an iSCSI session is still active on the vmknic, remove --force unbinds it anyway, which logs those sessions out. Log them out deliberately first with esxcli iscsi session remove. Syntax below is from Broadcom’s ESXCLI reference for ESX 9.1.0 and is unchanged from ESXi 8.0 U3.
iSCSI port binding in one minute
Port binding ties the software iSCSI initiator to specific VMkernel adapters, so iSCSI traffic leaves only through those vmknics and each one becomes a separate path for multipathing. The usual rules: one vmknic per bound port, each vmknic with exactly one active physical uplink and no standby uplinks, all bound vmknics in the same subnet as the target portals, and unbound vmknics are never used for iSCSI. If your targets sit in a different subnet than the vmknics, read Broadcom’s routed port binding guidance before you bind anything.
esxcli iscsi networkportal options (ESX 9.1)
| Command | Options | What the option does |
|---|---|---|
esxcli iscsi networkportal list | --adapter | -A | Limit the list to one iSCSI adapter |
esxcli iscsi networkportal add | --adapter | -A (required) | The iSCSI adapter, e.g. vmhba64 |
--nic | -n (required) | The vmknic to bind | |
--force | -f | Bind the vmknic even if it is not compatible with iSCSI multipathing | |
esxcli iscsi networkportal remove | --adapter | -A (required) | The iSCSI adapter |
--nic | -n (required) | The bound vmknic to remove | |
--force | -f | Remove the vmknic even when sessions are active on it |
The reference writes the flag as --force. The ESX error message suggests it as --force=true, so both spellings mean the same flag.
Find the software iSCSI adapter and the vmknics
esxcli iscsi adapter list
esxcli network ip interface ipv4 get
esxcli iscsi networkportal listadapter list gives you the adapter name (the software initiator is usually vmhba6x). networkportal list shows each bound vmknic with its adapter, IP, uplink, compliance status and path status. A non-compliant vmknic is the first thing to fix.
Add a network portal (bind a vmknic)
esxcli iscsi networkportal add -A vmhba64 -n vmk2
esxcli iscsi networkportal add -A vmhba64 -n vmk3
esxcli storage core adapter rescan -A vmhba64
esxcli storage core path listReplace vmhba64 and the vmknic names with your own. Rescan after binding so the new paths appear. Avoid add --force. It binds a vmknic that fails the multipathing checks (typically a port group with more than one active uplink), which leaves you with paths that do not fail over the way you expect. Fix the teaming instead: one active uplink, the rest unused.
Remove a network portal (unbind a vmknic)
esxcli iscsi networkportal remove -A vmhba64 -n vmk3
esxcli storage core adapter rescan -A vmhba64With no active sessions on the vmknic, this is all you need.
“iSCSI session is active on the vmknic … use –force=true”
This is the message most people search for. ESX refuses to unbind because an iSCSI session still uses the vmknic, and suggests forcing it. Broadcom documents the same message when removing a static target (KB 370577). remove --force logs out every session on that vmknic. If a LUN has no other working path, that is an all-paths-down event for every VM on the datastore.
The safe order:
- Check that every LUN still has an active path through another vmknic:
esxcli storage core path list -d naa.xxxx. - List the sessions on the adapter and note the ISID of the session that uses this vmknic:
esxcli iscsi session list -A vmhba64andesxcli iscsi session connection list -A vmhba64. - Log out only that session:
esxcli iscsi session remove -A vmhba64 -s <isid>. Without-sor-n,session removelogs out every session on the adapter. - Unbind:
esxcli iscsi networkportal remove -A vmhba64 -n vmk3. - Rescan the adapter and confirm the remaining paths.
Use --force only when the vmknic is already unusable (for example, a dead uplink during a NIC replacement) and you have confirmed the paths through the other vmknics.
iSCSI vmknics and netstacks
Searches for “netstack instance: iscsi” come from the output of esxcli network ip interface list, which prints the netstack every vmknic belongs to. To check:
esxcli network ip netstack list
esxcli network ip interface listA vmknic gets its netstack when it is created. The reference documents esxcli network ip netstack add -N <name> and esxcli network ip interface add -i vmkN -p <portgroup> -N <netstack> (or -s <dvs-name> -P <dvport-id> on a distributed switch). An existing vmknic cannot be moved to another netstack; it has to be removed and created again. The main reason to give iSCSI its own netstack is a separate routing table. If your iSCSI traffic is not routed, the default netstack is the simpler choice. Before you port-bind vmknics on a custom netstack in production, confirm support with Broadcom’s vSphere Storage documentation and your array vendor, because the public documentation does not state it either way.
Verify paths after any change
esxcli iscsi networkportal list -A vmhba64
esxcli iscsi session list -A vmhba64
esxcli storage core path list
esxcli storage nmp device listYou want one active path per bound vmknic and target portal, and the path selection policy your array vendor recommends (usually Round Robin).
Common errors
- “iSCSI session is active on the vmknic”: see the safe order above.
- vmknic not compliant for binding: the port group has more than one active uplink, or a standby uplink. Set exactly one active uplink and move the others to unused. Don’t paper over it with
add --force. - No new paths after add: no rescan, a target in a different subnet than the vmknic, or the array’s host access list does not include the initiator IQN.
Reference
- Broadcom: ESXCLI Command Reference 9.1.0, esxcli iscsi and esxcli network
- Broadcom KB 370577: Unable to remove static iSCSI target
- Broadcom KB 403944: How to remove iSCSI targets on ESXi
- vDan: ESXCLI commands for ESX 9.x, ESXi 8.0, ESXi 7.0
