Unraid iSCSI Target Setup: Plugins, LUNs and CHAP

Unraid is built around user shares exported over SMB and NFS. Those are file protocols: the server owns the filesystem and hands out files. iSCSI is not that. It hands the client a raw block device and lets the client put its own filesystem on it, which is why people reach for it to back a game library, a VM disk, a Time Machine target or anything else that wants to behave like a local drive.

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.

The three plugins and what each one does

Search Community Applications for “iSCSI” and three distinct things come back. They are not interchangeable and the names invite confusion.

iSCSI Target turns the Unraid box into the storage side. It installs the target software and dependencies and adds a configuration utility to the settings page, so the server can advertise LUNs that other machines attach to. The Community Applications listing describes it exactly that way: the plugin installs the software and dependencies for iSCSI and provides a utility on the settings page to configure targets.

iSCSI Initiator is the opposite direction. It lets Unraid attach to a LUN presented by some other array and mount the resulting volume locally. If the goal is “expose my Unraid storage to a Windows PC”, this is the wrong plugin.

iSCSI GUI is the newer front end. Its README states plainly that the plugin uses targetcli to show the iSCSI setup, so treat it as a management surface over the same backend rather than as a separate storage stack. The older target plugin’s own listing is honest about the state of that surface: it notes that the configuration utility is still in beta and that this does not affect the functionality of the targets themselves. That is a fair summary of the whole stack on Unraid. The backend is mature Linux storage code; the Unraid-facing configuration layer around it is community-maintained and younger.

What the plugin is really driving

None of these plugins implement iSCSI. They wrap LIO, the in-kernel Linux I/O target, through its targetcli shell. That matters more than it sounds, because it means everything documented for LIO on a mainstream distribution applies to Unraid too, and the enterprise documentation is far better than the plugin documentation.

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_back or write_thru, that write_back enables the local filesystem cache and improves performance at the cost of increased data-loss risk, and recommends write_back=false in favour of write_thru.
• block hands LIO a device from /sys/block directly. That includes physical disks, SSDs and logical devices such as software or hardware RAID volumes and LVM volumes.

On Unraid, fileio on a pool is the normal answer and block is the sharp tool. A block backstore pointed at a bare disk removes that disk from Unraid’s own management; it is no longer a share, it is no longer under the array’s control, and nothing in the web UI will remind you of that later.

Where the LUN should live

This is the decision that determines whether the result feels like a disk or like a punishment, and it is specific to Unraid’s storage model.

Unraid’s protected array is parity-based, and every write to a data disk has to update parity as well. For streaming media writes that overhead is invisible. For a LUN carrying a filesystem doing small scattered metadata updates, it is not. Block storage generates exactly the access pattern parity arrays are worst at.

Put the backing file on a pool device instead. A dedicated NVMe or SSD pool gives the LUN a write path with no parity update in it, and it keeps the array free to do what it is good at. If the data on the LUN matters, back the LUN up as a file, on a schedule, to the array; a raw block image is opaque to the array’s own protection story and no share-level backup will understand its contents.

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.
• Do not put the backing file on a share that also lives under user-share mover rules. Files that move between pool and array underneath an active LUN are a corruption path, not a tiering strategy.

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, the standard design is one subnet per path, one interface per subnet, and MPIO on the client stitching the two sessions into one device. To sanity-check whether the link or the pool is the limiting factor before buying anything, the iSCSI SAN bandwidth and MPIO sizer works the numbers for path count, media type and block size.

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.

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.