iSCSI carries SCSI commands over TCP/IP. That single sentence explains most of its behaviour, including the parts that surprise people coming from file sharing protocols. The client is not asking a server for a file. It is issuing block level commands to what it believes is a locally attached disk, and the network is only the transport.
What an iSCSI LUN is
A LUN is a logical unit number: the SCSI address used to identify a logical unit within a target. Administrators also use “LUN” as shorthand for the storage volume presented at that address. RFC 7143 distinguishes the target, which can contain multiple logical units, from the LUN carried in a command to select one of them.
For a disk-like logical unit, the initiator sees a block device and supplies the filesystem or volume manager. Creating a target IQN alone does not provide a disk: the target also needs backing storage and a mapping that makes that storage visible to the intended initiator.
| Object | What it identifies | What to record |
|---|---|---|
| Target IQN | The storage endpoint | Target name and permitted initiators |
| Portal | A network endpoint | Storage IP address and TCP port |
| LUN | A logical unit within the target | LUN number, backing volume and owning host |
| Initiator IQN | The client endpoint | A distinct name for each host |
Two targets can each expose LUN 0 without exposing the same disk. Conversely, one volume can appear through several paths. Confirm the device identity before formatting; a LUN number alone is not a globally unique volume identifier.
Initiators and targets
The initiator is the client. It runs in software on the host operating system, or in hardware on an iSCSI capable adapter, and it is the side that issues commands.
The target is the storage side. It presents one or more logical units, each identified by a logical unit number, or LUN. A LUN is the thing the host sees as a raw disk. It can be backed by a file, a logical volume, a ZFS zvol, a whole physical disk or an array volume, and the initiator neither knows nor cares which.
Both ends can be named with an iSCSI qualified name, or IQN. Its format is iqn.YYYY-MM.reversed-domain:unique-suffix, with a date establishing when the naming authority owned the domain. IQNs are identifiers, not addresses, and targets can use them to control which initiators see which LUNs. A worked example of that mapping on a NAS-class box, including which backing store to choose, is in Unraid, TrueNAS and Synology target setup.
Keep an inventory of target IQNs, portal addresses, LUN mappings and owning hosts outside the target configuration. On Linux, check /etc/iscsi/initiatorname.iscsi after cloning a host: the open-iscsi documentation requires distinct initiator names. Copy the actual name into the target’s allow-list. Store CHAP secrets in a credential store separately from that inventory.
Discovery and authentication
The initiator connects to a portal, which is an IP address and port on the target, and performs discovery. The target responds with the list of targets it is willing to advertise. The initiator then logs in to a specific target and begins a session.
Access control has two independent layers and both matter. Initiator masking restricts which IQNs may access a given LUN. CHAP provides authentication during login. One way CHAP authenticates the initiator to the target. Mutual CHAP additionally authenticates the target to the initiator, which is what prevents a host from attaching to an impostor target.
Discovery and login are separate exchanges: a target that lists but refuses login warrants checking identity and authentication, as well as reachability of the advertised portal. That split, and how to read it, is the starting point of iSCSI troubleshooting for login, timeout and path errors.
Neither layer encrypts traffic. iSCSI data crosses the wire in the clear unless you wrap it in IPsec or confine it to a trusted network segment. Confining it is the usual answer.
Network design
Treat the storage network as a separate network. A dedicated VLAN or dedicated physical interfaces keep general traffic from competing with storage traffic, and keep the storage fabric out of reach of clients that have no business on it.
Flow control and switch buffering matter more here than on general networks, because TCP retransmission on a storage path shows up to applications as latency spikes on a disk. Larger frame sizes can reduce per packet overhead, but every device in the path must agree on the setting, and a mismatch produces silent fragmentation or dropped frames that are painful to diagnose.
Before adding interfaces, compare the network and media ceilings with the iSCSI Throughput and MPIO Calculator for a given path count, block size and storage class.
MPIO is not link aggregation
This is a recurring architectural error. Link aggregation bonds physical links into one logical link, and a single TCP connection still traverses one member link, so a single iSCSI session gains no bandwidth from it.
Multipath I/O works at the SCSI layer instead. The initiator establishes independent sessions over independent paths, recognises that the LUNs arriving on each path are the same device, and presents one device to the operating system. The multipath layer then distributes I/O across paths and fails over when one dies. Choose the subnet layout for the host platform and the storage vendor’s supported topology. Microsoft’s Windows MPIO guidance calls for separate network adapters; verify the physical paths and failover rather than treating subnet count alone as proof of redundancy.
Connect the initiator and check persistence
The open-iscsi workflow separates discovery from login. Discover each intended storage portal, verify the target IQN returned, then establish the sessions required by the host’s multipath configuration. Check the target’s host mapping before using a newly visible disk.
For sessions that should reconnect at boot, review the saved node’s node.startup setting. The upstream configuration defaults to manual; the README documents automatic for startup login. Changing the default configuration does not update existing node records. Verify the saved records and the host’s startup service configuration together, then restart during a maintenance window with disposable data.
Verify MPIO failover before using the LUN
On Linux, inspect multipath -ll for one map per volume and the expected paths. On Windows, Microsoft’s MPIO guidance calls for separate network adapters and checks that the device has multiple paths. Use the array’s supported path grouping and policy; an ALUA array can distinguish optimized and non-optimized access, so counting sessions alone does not establish that all paths should carry equal traffic.
For the Windows commands, configure a Windows Server iSCSI target with CHAP and MPIO before checking path failover.
In a planned validation using disposable data, interrupt one path, confirm the remaining path carries I/O, restore it, and repeat for the other path. Record the interruption and recovery behavior. This is a procedure for the reader to perform, not a measurement made by this site.
Also decide what should happen when every path is unavailable. Review the initiator replacement timeout together with the multipath queueing policy and the application’s timeout expectations. The login and path troubleshooting guide covers those timers. A successful login does not validate reconnection after reboot or recovery from path loss.
Common mistakes
Mounting the same LUN read write on two hosts with an ordinary filesystem. Block storage does no arbitration, so both hosts cache and write independently and the filesystem corrupts. Sharing a LUN requires a cluster aware filesystem or a clustered volume manager. When several machines genuinely need the same data at once, a file protocol is the right tool instead, and the ownership models are compared in iSCSI vs NFS vs SMB.
Others worth avoiding: assuming multiple sessions prove independent physical paths without checking the host’s supported topology; leaving CHAP disabled on a routable network; thin provisioning past physical capacity with no monitoring, which turns a full backing store into write failures on every attached host; and forgetting that snapshots on the target are crash consistent unless the host is quiesced first.
Where to go next
- Build a target on consumer NAS hardware: Unraid iSCSI target setup.
- Decide whether block storage is the right choice at all: iSCSI vs NFS vs SMB.
- Diagnose a session that will not come up, or a path that keeps dropping: iSCSI troubleshooting: login, timeout and path errors.
- Size the fabric: iSCSI Throughput and MPIO Calculator.
