Unraid normally exports user shares over SMB and NFS, where the server manages files. An iSCSI target instead presents a block device for the client to manage. Start below with Unraid’s community target plugin and backing-store placement, then use the platform sections for TrueNAS and Synology targets or a Proxmox initiator. The target configuration differs, but filesystem ownership and access controls still need an explicit plan.
The first thing to understand is that this capability is not in the stock product. Unraid’s own web interface exposes share export options for file protocols; iSCSI target support arrives through Community Applications plugins, which is why every guide starts with an app install rather than a settings page.
Choose the Unraid iSCSI target plugin
Search Community Applications for iSCSI Target and check the listing against your installed Unraid release before installing it. The published listing says it supplies target software and dependencies, a settings-page configuration utility, and a targetcli-based interface.
The role matters: a target exports storage to another machine; an initiator connects to storage exported elsewhere. To make an Unraid-backed disk available to a Windows or Linux host, configure the target side on Unraid and the initiator on that host.
The listing labels its configuration utility as beta. Treat persistence and release compatibility as things to verify using the plugin’s documentation and a disposable LUN before attaching important data.
What the plugin is really driving
The plugin exposes a targetcli management surface. Red Hat’s LIO documentation explains the underlying backstore, target and ACL objects; use the Unraid plugin’s instructions for installation and persistence rather than assuming distribution service commands apply unchanged.
Red Hat’s targetcli chapter is the useful reference here. It describes a tree-based configuration shell with tab completion and inline help, and it defines the two backstore types that decide how a LUN is backed:
- fileio backs the LUN with a regular file on an existing filesystem. Red Hat notes that fileio objects support either
write_backorwrite_thru, thatwrite_backenables the local filesystem cache and improves performance at the cost of increased data-loss risk, and recommendswrite_back=falsein favour ofwrite_thru. - block hands LIO a device from
/sys/blockdirectly. That includes physical disks, SSDs and logical devices such as software or hardware RAID volumes and LVM volumes.
For a file-backed LUN, choose a dedicated pool location whose placement you control. A block backstore grants the initiator access to the underlying device; it does not automatically remove that device from Unraid management. Never export a device that another filesystem, array or service is actively using.
targetcli: create a LUN mapping after the backstore
Red Hat documents a separate creation step for each object: create a fileio or block backstore, create the iSCSI target, then map that backstore under the target portal group’s luns branch. Add the client’s initiator IQN under acls and verify its mapped LUN. A backstore without the target-side LUN mapping is storage that the client cannot use yet.
Use the plugin’s configuration interface to inspect this object tree. Check the backing path, target IQN, portal binding and authorized initiator before login. Follow the plugin’s supported save procedure and verify that the same mapping returns after reboot; targetcli configuration and Unraid service startup are separate concerns.
Where the LUN should live
Unraid’s share documentation distinguishes primary storage, secondary storage and the mover action between them. For a stable file-backed target, choose a dedicated pool location and keep it out of automatic movement between pool and array. The physical pool layout still determines its redundancy and write behavior; “pool” alone does not mean fast or protected.
Capacity planning must include the whole backing pool. A guest can see free space inside its filesystem while the thin-provisioned storage underneath has exhausted physical capacity. Monitor that underlying space as well as the guest volume.
Two more placement rules worth stating outright:
- Do not thin-provision past the physical capacity of the pool without monitoring. When the pool fills, the target starts failing writes, and the client sees them as disk errors on what it thinks is a local drive.
- Set the backing share’s secondary storage to None when keeping its files on the chosen primary pool. Confirm the actual backing-file path and placement before connecting a client.
IQNs, ACLs and who is allowed in
Both ends of an iSCSI session are named with an iSCSI Qualified Name. The target decides which initiator names may see which LUNs; that mapping is the ACL, and it is the primary access control in the protocol. Get the initiator’s IQN from the client first, then create the ACL, then map the LUN into it. Doing it in the other order produces a target that either advertises nothing or advertises everything.
On Windows, the initiator name is on the Configuration tab of the iSCSI Initiator control panel. On Linux it lives in /etc/iscsi/initiatorname.iscsi. Both are editable, which is convenient and is also why an ACL alone is an identity check rather than an authentication check.
CHAP, and what it does not do
CHAP is the authentication layer. Red Hat’s description is the honest one: CHAP lets you protect the target with a password that the initiator must know in order to connect. One-way CHAP authenticates the initiator to the target. Mutual CHAP additionally authenticates the target to the initiator, which is the half that stops a host from attaching to an impostor target.
What CHAP does not do is encrypt anything. RFC 7143 defines iSCSI as a SCSI transport over TCP; confidentiality is not part of the login exchange. Payload on the wire is readable to anyone on the segment unless the traffic is wrapped in IPsec or confined to a network that is trusted for that purpose. On a home or small-office Unraid box, confining it is the practical answer: a storage VLAN, no route to the client LAN, and the target portal bound to that interface only.
Set CHAP even so. A LUN with no authentication on a flat network is one misconfigured client away from being attached by the wrong machine, and the failure mode is not a permissions error, it is filesystem corruption.
Networking on a box that has one NIC
Multipath I/O is the correct answer for redundancy and throughput, but it requires independent paths. A single-NIC Unraid server has one path, and no amount of configuration produces a second one. Link aggregation does not help either: bonding gives you more aggregate capacity across many connections, but a single iSCSI session still rides one member link. The distinction is covered in more depth in iSCSI fundamentals: targets, LUNs and multipathing.
If the box has two spare interfaces, a common design is one subnet per path, one interface per subnet, and MPIO on the client combining the sessions into one device. Compare the assumed path and media ceilings using the iSCSI Throughput and MPIO Calculator.
Whatever the path count, keep MTU consistent end to end. A jumbo-frame setting that is enabled on the server and the switch but not on the client produces the most annoying failure in this whole stack: discovery succeeds, login succeeds, and then large transfers stall. That symptom and its neighbours are worked through in iSCSI troubleshooting: login, timeout and path errors.
TrueNAS iSCSI target: zvol, extent and target association
TrueNAS supplies an iSCSI configuration interface. The following sequence follows the 25.04 documentation; check the documentation for your installed release when screen labels differ.
- Create a dedicated zvol with sufficient pool capacity. The TrueNAS datasets vs zvols guide explains which storage object to create.
- Open Shares, then the Block (iSCSI) Shares Targets configuration. Create a portal bound to the storage IP and an initiator group containing the intended client’s IQN.
- Configure authorized access for CHAP, then create the target using the intended portal, initiator group and authentication settings.
- Under Extents, add a Device extent and select the zvol. This identifies the backing device; it does not replace the target association.
- Under Associated Targets, associate the extent with the target and assign its LUN ID. Start the iSCSI service and enable startup if required.
Discover the storage portal from the client and confirm the expected device before formatting it. Keep the zvol dedicated to its initiator’s storage use.
Synology iSCSI target in SAN Manager
For DSM 7, use SAN Manager. Synology’s quick-start guide requires an existing volume in Storage Manager and directs administrators to check their model’s supported LUN limits.
Create a LUN with a name, volume location, capacity and space-allocation method. In the iSCSI configuration, create or select a target, record its IQN and map the LUN to it. Configure CHAP on the target and the matching initiator credentials; mutual CHAP requires configuration at both ends. Assign access permissions to the intended hosts or initiators instead of exposing every LUN to every client.
Connect from the initiator and confirm that the intended LUN appears. Monitor physical capacity when using thin provisioning. A target that exists without the LUN mapping is not a complete storage connection.
Proxmox VE as an iSCSI initiator
Proxmox consumes storage from these targets through its Open-iSCSI backend. Its documentation identifies portal and target as the connection properties and documents pvesm scan iscsi <HOST[:PORT]> for discovering targets on a specified storage host. Confirm each Proxmox node’s IQN is authorized before connecting it.
Provision the LUN on the NAS first: Proxmox’s plain iSCSI backend cannot allocate target-side LUNs. When using LVM on that LUN, set the iSCSI storage’s content to none so VM disks are allocated through the LVM layer rather than assigned the entire LUN directly.
Add an LVM storage entry using the existing volume group and the iSCSI base volume. Mark it shared only when the participating nodes actually access the same storage. The documented LVM backend coordinates storage-management operations with cluster-wide locking when configured as shared. That does not make an ordinary guest filesystem safe for simultaneous writers. LVM-thin is documented for non-shared local storage, so it is not interchangeable with this shared-LVM arrangement.
The rule that breaks the most home setups
One LUN, one host, unless the filesystem on it is cluster-aware. Two Windows machines attaching the same LUN with NTFS will both mount it, both cache metadata, both write, and destroy the volume. Block storage arbitrates nothing; there is no server-side lock manager, because there is no server-side filesystem. If several machines need the same data at the same time, that is what SMB and NFS are for, and the tradeoff is laid out in iSCSI vs NFS vs SMB.
Before calling it done
- The backing store is on a pool, not on the parity-protected array.
- The ACL lists the client’s real IQN, copied from the client rather than typed from memory.
- CHAP is enabled, and mutual CHAP if the network is shared with anything else.
- The client sees one disk, not one disk per path.
- The pool has headroom, and something alerts when it does not.
- A reboot of the Unraid box brings the target back automatically, and the client reconnects without manual intervention.
That last one deserves a real test. Plugin-provided services are community-maintained and their persistence across an Unraid version upgrade is not guaranteed by the vendor. Reboot deliberately, once, while nothing important is on the LUN, and find out how the stack behaves before a power cut asks the same question at a worse time.
