What is an iSCSI LUN? It is one block volume that a storage target exports over the network, addressed by a logical unit number that usually starts at 0. The host that logs in sees it as a blank local disk and formats it itself; the NAS only stores the blocks and never sees the files.
Strictly, the LUN is the number. RFC 7143, the iSCSI spec, says “Each LU has an address within a target called a Logical Unit Number (LUN),” and “A target can contain multiple LUs.” Everyone, NAS vendors included, also says “LUN” for the volume itself. Both usages are fine, as long as you remember that LUN 0 on one target and LUN 0 on another are different disks.
In homelab terms, the N100 mini-PC running Proxmox or Windows is the initiator, the NAS is the target, and the LUN is the disk in between. The protocol side (IQNs, discovery, CHAP, multipath) lives in iSCSI fundamentals: targets, initiators and MPIO. This post stays on the LUN itself: what backs it, who sees it, how big it really is, and when not to make one.
What does an iSCSI LUN look like on the client?
It looks like a disk someone just plugged in: no partitions, no filesystem, and to most software no different from a local SATA drive. On Linux, lsscsi prints every SCSI device with an [H:C:T:L] tuple, and its man page says the final element “is the Logical Unit Number (LUN).” That number is the one you set on the NAS.
The stable name is the by-path link. Red Hat’s persistent naming reference gives the pattern /dev/disk/by-path/ip-<ip_address>:<ip_port>-iscsi-<iqn_name>-lun-<lun_number> and warns that traditional names like /dev/sdb “are subject to change when devices are added or removed.” Check the link before you format, mount by UUID, and never assume sdb is still sdb after a reboot.
Map a new LUN to a target the host is already logged in to and nothing appears until the host rescans. The iscsiadm man page says -R without a session ID will “rescan all running sessions”:
sudo iscsiadm -m session -R # pick up LUNs mapped since login
lsscsi -s # [H:C:T:L] plus size; L is the LUN
ls -l /dev/disk/by-path/ | grep iscsi # one link per LUN, per pathOn Windows, the LUN appears in Disk Management as a new disk once the target is connected, waiting to be initialised like any fresh drive.
What actually backs an iSCSI LUN?
Storage that already exists on the target: a ZFS zvol, a plain file, a logical volume, a whole disk or a virtual-disk file. The initiator can’t tell which. You should care, because the backing store decides how the LUN is snapshotted, grown and backed up, and that matters more over a year than the protocol does.
| Target | What a LUN sits on | Worth knowing |
|---|---|---|
| TrueNAS 25.10 | A zvol (Device extent) or a single file (File extent) | LUN IDs run 0 to 1023, and TrueNAS “requires at least one LUN 0” |
| Synology DSM 7.4 SAN Manager | A LUN on a storage volume, thick or thin provisioned | Instant snapshots need thin LUNs on Btrfs; up to 512 LUNs per system, varying by model |
| Linux LIO with targetcli | A backstore: fileio, block, pscsi or ramdisk | New LUNs auto-map to existing ACLs unless you turn that off |
| Windows Server iSCSI Target | A .vhdx or legacy .vhd virtual disk | Fixed .vhdx up to 64 TB; LUN shrink on 2012 R2 and newer |
On TrueNAS, use a zvol. The screen reference says a Device extent “provides virtual storage access to zvols and zvol snapshots,” which brings ZFS snapshots and replication along for free. A File extent adds a filesystem layer you don’t need.
Whatever backs it, the NAS can’t see inside. A LUN snapshot is a whole-disk image, frozen as if the power were cut at that instant. You can’t browse to one lost spreadsheet from the NAS web UI; a single-file restore means cloning the snapshot, presenting the clone as another LUN and mounting it from a client. That is the real price of block storage at home, and the main reason NFS is the better default for most homelab shares.
How does a host get to see a LUN?
Through a mapping on the target. The LUN is attached to a target, and the target, or an ACL under it, lists which initiator IQNs may log in and which LUNs each sees. Get it wrong one way and the host sees nothing. Get it wrong the other way and a second machine sees a disk it should never touch.
Linux’s LIO target has the sharpest edge. Red Hat’s RHEL 9 target guide notes that LUNs are created read-write by default and that “if a new LUN is added after ACLs are created, LUN automatically maps to all available ACLs and can cause a security risk.” Running set global auto_add_mapped_luns=false in targetcli makes every mapping a deliberate step. Mapped LUNs can also be read-only.
TrueNAS uses initiator groups of allowed IQNs. Its wizard calls leaving the Initiators field blank, which allows every initiator, “recommended.” On a flat home network where every laptop, phone and smart plug can reach port 3260, paste the one IQN anyway. A Read-only extent “prevents the initiator from initializing this LUN,” which is what you want when presenting a snapshot clone for a restore. The click path is in setting up an iSCSI target on TrueNAS, and the Unraid version is in Unraid iSCSI target setup.
One more trap: a LUN number is not an identity. Red Hat’s walkthrough numbers LUNs 0, 1 and 2 within one target, so two targets will usually both have a LUN 0. To tell disks apart, use a WWID, which Red Hat describes as “a family of identifiers which are globally unique,” or the /dev/disk/by-id/ links built from vendor, model and serial.
Thick or thin: how much space does a LUN really use?
A thick LUN reserves its full size on the NAS the moment you create it; a thin LUN consumes space only as the host writes. Thin is more flexible, and Synology needs it for instant snapshots. It also lets the NAS promise more space than it has, and the host only finds out when writes start failing.
The vendor docs are blunt. TrueNAS calls its thin option Sparse, and its zvol screen reference says to “use caution when enabling, as writes can fail when the pool is low on space.” Sparse is also one of the settings you can’t change after Save. Synology’s specs say “instant snapshots and instant restore require Thin Provisioned LUNs on Btrfs volumes running DSM 6.2 or later.” Microsoft’s target lists thin provisioning as unsupported: dynamic VHDs work, but unmap doesn’t.
The practical rule: on TrueNAS, where the pool also holds media and backups, leave Sparse off so a runaway download can’t starve the VM’s disk. On Synology, go thin on Btrfs because you want the snapshots, then watch volume free space like it owes you money.
Start small. TrueNAS lets you grow a zvol-backed LUN, but its expansion docs say it does “not allow users to reduce the Zvol size” and won’t grow one past 80% of the pool. Windows Server 2012 R2 and newer can shrink a LUN. Growing is always two-sided: enlarge it on the target, then rescan on the client and grow the partition and filesystem there.
Pick the logical block size before the client formats anything, too. TrueNAS defaults extents to 512 bytes; its Modern OS preset uses 4K and its VMware preset 512.
Can two machines share one iSCSI LUN?
Only if the filesystem on it is built for sharing. The LUN itself doesn’t arbitrate between hosts, so two machines mounting ext4 or NTFS read-write on one LUN each cache and write as if they owned the disk, and the filesystem corrupts. Cluster filesystems and cluster-aware volume managers exist to solve exactly that.
VMware’s answer is VMFS; Broadcom’s docs say “as a cluster file system, VMFS lets multiple ESXi hosts access the same VMFS datastore concurrently.” Proxmox’s answer is LVM on the LUN. The Proxmox iSCSI page advises that “it is usually best to export one big LUN, and setup LVM on top of that LUN,” and the LVM page says the backend “implements proper cluster-wide locking if the storage is marked as shared.” The catch: the iSCSI storage type lists no snapshots, and LVM snapshots as a volume chain, available for VMs since Proxmox VE 9, are still a technology preview.
For two ordinary Linux or Windows boxes the rule is short: one LUN, one host.
When should a homelab use an iSCSI LUN at all?
When exactly one machine needs something that behaves like a local disk and its own storage is too small. Think Proxmox VM disks on a NAS, a Windows application that refuses to install to a network share, or a container whose SQLite database shouldn’t live on NFS. Media, ISOs, backups and anything two machines read belong on SMB or NFS.
The SQLite case converts a lot of people. SQLite’s own corruption guide says buggy file locking is “especially true of network filesystems and NFS in particular,” and that two processes hitting the same database on such a filesystem can corrupt it. On a LUN, the host’s local filesystem does the locking.
Be honest about the alternative. On a single mini-PC with a decent NVMe drive, the fastest home for VM disks is usually that NVMe, backed up to the NAS. A LUN puts the network under every disk write, so when the NAS reboots for an update the client watches a disk vanish. If you’re still weighing protocols, iSCSI vs SMB for a homelab NAS walks through the trade.
FAQ
what does lun stand for in iscsi
LUN stands for logical unit number. In SCSI terms a logical unit is an individual I/O device, and the LUN is its address within a target, carried in a 64-bit field in the iSCSI PDU header. The term comes from SCSI itself rather than iSCSI, so it means the same thing on any SCSI transport.
is an iscsi lun the same as a zvol
No. A zvol is a ZFS block device on the NAS; the LUN is the numbered address a target uses to export it. On TrueNAS you create the zvol, wrap it in a Device extent, then associate that extent with a target under a LUN ID. The zvol holds the data; the LUN is the door.
does an iscsi target need a lun 0
Some targets do, so give LUN 0 to a real volume rather than starting at 1. TrueNAS documents that it requires at least one LUN 0, and Red Hat’s targetcli walkthrough creates LUN 0 first. Beyond that the number is just an address, shown as the L in lsscsi output and the lun suffix in by-path names.
is iscsi lun traffic encrypted
No, not by default. The iSCSI spec says the protocol’s own security “only consists of authentication in the Login Phase,” so CHAP proves who is logging in while the blocks cross the wire in the clear. For a homelab, keep the portal on a trusted storage VLAN or second NIC, and never forward TCP 3260 through your router.
