Storage

Storage, backup and replication2026-09-15· By Franz Senn

The TrueNAS Plugin for Proxmox: Official ZFS over iSCSI, Still Not Production Ready

Anyone who feeds Proxmox clusters from a NAS over iSCSI knows the ritual behind every virtual disk: create a zvol on the TrueNAS side, wrap it in an extent, attach it to a target, log the LUN in on the node. And when anything changes, run the lap again. TrueNAS has now published its own plugin to end that loop. The announcement promises that Proxmox can provision, snapshot, resize, migrate and delete TrueNAS-backed VM disks directly, with no manual LUN management at all. That reads like ZFS over iSCSI, finally made official. We read the source code instead of the billboard. State of play, 15 September 2026, updated 23 September 2026.

What the plugin actually does

The basis here is the source itself: TrueNASPlugin.pm, roughly 290 KB of Perl under GPL-3.0, maintained under the TrueNAS organisation on GitHub. In short:

The control plane is the TrueNAS WebSocket API. For every VM disk the plugin creates a zvol under a chosen dataset (pool.dataset.create), an iSCSI extent on top of it (iscsi.extent.create), and maps everything to a single shared target. The plugin assigns LUN numbers itself; in Proxmox the volumes show up as vol-<name>-lun<n>.
The data plane is plain, standard iSCSI. Each Proxmox node runs discovery and login via iscsiadm and addresses the disk through its by-path device. Multipath is on by default, CHAP is optional. NVMe/TCP is available as an alternative, which requires Proxmox 9.x and TrueNAS SCALE 25.10 or newer.
Snapshots are real ZFS snapshots on the zvol (pool.snapshot.create). That is the genuine gain over NFS and file storage: where a big NFS disk can block VM I/O during a snapshot, this is a copy-on-write operation on the array, done in seconds, rollback included.

So functionally: the classic ZFS-over-iSCSI architecture with API automation bolted on top. Nothing fundamentally new, but done carefully and maintained by a vendor for the first time. Proxmox itself now uses the category literally: the 9.2 changelog lists TPM state on iSCSI and "ZFS over iSCSI" storages as newly supported.

The command goes to the API; the disk data takes a separate iSCSI path. (Quelle: Our own analysis of the plugin source)

The pattern is not new

"ZFS over iSCSI" is the name of a community plugin that has existed for years: freenas-proxmox under AGPL-3.0, actively maintained, latest release v4.0.1 (2 September 2026). Both plugins coexist today, and nobody has declared one the successor of the other. They do share one constraint: TrueNAS is retiring the old REST interface, deprecated from SCALE 25.04 and gone in 26.x, so both had to move to WebSocket.

	TrueNAS plugin	freenas-proxmox
Maintained by	TrueNAS (an iXsystems engineer plus the author of the predecessor plugin)	Community
License	GPL-3.0	AGPL-3.0
NVMe/TCP	yes (SCALE 25.10+, PVE 9.x)	no
TrueNAS versions	25.10 or newer only	older releases supported too
Latest state	v2.1.23-beta5 (23 Sep 2026)	v4.0.1 (2 Sep 2026)

What survives contact with the marketing

Four claims from the announcement, checked against code and documentation:

"Live snapshots including RAM." The wording does not hold. RAM does not go into the ZFS snapshot; the PVE core writes it to a separate vmstate volume (tn_vmstate_storage shared or local in the plugin). Live snapshots work on Proxmox 9, that is a PVE feature and not TrueNAS magic. The volume chains underneath are still a tech preview on the Proxmox side.
"Migrate." That is ordinary shared-block live migration, working because every node sees the same LUN. No plugin code involved. Moving a single disk between storages currently does not work at all, there is an open issue for it.
"Clones." Full clones copy byte by byte. ZFS clones exist in the code, but PVE bypasses the clone paths of external block storages, and the vendor's own limitations page warns of "No Fast Clone Support".
"Delete without leftovers." If a clone fails or a destroy aborts, orphaned zvols stay behind in the dataset and block VMID reuse. The limitations page ships the cleanup recipe along with the warning.

Where it stands: built well, officially beta

The architecture is clean, and real ZFS snapshots are exactly what NFS-backed Proxmox storage always lacked. The maturity statement comes from the vendor itself:

The TrueNAS documentation says it verbatim: active development, not fully tested, Community Edition only, do not use in production workloads. Enterprise systems stay on the unsupported list.
On 22 Sep 2026 the maintainers closed 22 issues in a single day, most of them pointing at v2.1.23-beta3 or beta4: the storage that went dead after 30 days, the HA refusal, the broken cloud-init detection after clones.
What remains is 14 open issues and 7 open pull requests (23 Sep 2026, counted through the GitHub API). Five of them concern NVMe: "VM disk on NVME-tcp corruption" (#32), NVMe-oF errors on large I/O under load (#96), nvmet_tcp failures during vzdump (#45), the NVMe service needing a restart before devices are published (#12) and timeout warnings inside the storage API call (#4). The sweep left that group untouched.
Bus factor: an iXsystems employee (@truenas.com, @ixsystems.com) wrote 39 of the last 60 commits. The bulk of the existing code belongs to one external developer, 331 of 381 commits.
Version churn: v2.1.5 (June) to v2.1.23-beta5 (23 Sep 2026), eight published builds between 24 Aug and 23 Sep.

Update 16 Sep 2026

One more day of tracker data, measured through the GitHub API on 16 Sep 2026:

The HA bug is in the package as of v2.1.23-beta4. PR #101 merged on 14 Sep 2026 and is inside the release of 19 Sep 2026, the postinst of that tag restarts pvedaemon pveproxy pvestatd pve-ha-crm pve-ha-lrm, with TRUENAS_PLUGIN_NO_RESTART=1 as an escape hatch. iXsystems marks beta4 itself as a pre-release, the three betas before it were regular. An APT install still pulls an older series whose Release file names 01 Jul 2026 and version 2.1.17+deb1.
The TrueNAS 26 patch was closed on 16 Sep 2026 without being merged. PR #83 (host whitelist, DH-CHAP, namespace rendering, open since 21 Jul) was shut after eight weeks with not a single comment. Still open: #95 (CHAP on 25.10, since 23 Aug), #97 (bounded API probes while the array is unreachable, since 26 Aug), #94 (NVMe/TCP portals, since 17 Aug). There is also #92, the lead developer's own fix from 06 Aug. The oldest untouched outside PRs date from 2 Jul and 23 Jun. That is the yardstick for the two conditions below: how fast a merge happens.
The number for 16 Sep 2026: 31 open issues and 6 open pull requests (16 Sep 2026); yesterday's 38 counted both together. Plus issue #99 (30 Aug, open): the plugin reports TESTED_APIVER = 14 while TrueNAS 25.10.6 is on API version 15, so every storage call comes back with a deprecation warning. No outage, but the same mechanism that already took the REST interface away. A third-party fork (23 Aug 2026) now carries the CHAP and session fixes outside upstream; anyone unwilling to wait is patching it themselves.
Two dates belong together: the documentation page carrying the production warning was last modified on 26 Mar 2026 and still reads "do not use in production workloads", with Enterprise explicitly not supported. The announcement of 11 Sep 2026 calls Enterprise support "in active validation and orderable". The older statement is documented, the newer one is a vendor claim without independent evidence. Our condition stays attached to the documentation.
The HA problem belongs to Proxmox itself. The same failure is documented in Pure Storage's Proxmox plugin (pve-purestorage-plugin#75). We read it as structural for third-party Proxmox storage plugins: pve-ha-crm and pve-ha-lrm pick up plugin types only at service start. Which makes a sixth point for the test list below: check the HA manager explicitly after installing, well before an emergency.

Update 23 Sep 2026: the causes are on record

How the 30-day failure happened

Issue #98 has a clean cause, written into the issue on 22 Sep 2026. The broker kept holding a WebSocket key that had expired but stayed open, and TrueNAS caps a session at 30 days (AA_LEVEL1.max_session_age). The liveness probe called core.ping, and that call is no_auth_required, so it never sees an expired session. Fixed in v2.1.23-beta3 by making the probe require auth.me, which forces the next call to build a fresh session. A health check that cannot see its own failure mode is something any system can grow.

Two causes for the corruption, one of them sits in Proxmox

Issue #96 has been analysed down to the kernel by an outside user since 28 Aug 2026. nvmet_tcp_ops has no .get_mdts in mainline Linux, while the RDMA and PCIe transports do. The target therefore advertises no maximum transfer size, the initiator sends I/Os of 6 to 32 MiB, and the target answers with sc 0x6. The patch has been on the linux-nvme list in third revision since 31 Aug 2026 and carries a Reviewed-by from Sagi Grimberg. It is not merged.

The second half concerns us regardless of TrueNAS. Proxmox runs qemu-img convert onto a block target with the default -t unsafe. A write error sitting behind the page cache is dropped and qemu-img exits with code 0. The task log reads TASK OK while data is missing. Proxmox has tracked this as bug 8054 since 17 Sep 2026, status ASSIGNED, last moved 23 Sep 2026. That answers the question we asked in the first version: all it needs is a block storage that returns write errors, and the path runs on every storage of this build. Our own data sits on LINSTOR/DRBD under PVE 9.2.20, so this half reaches us directly.

The documentation was edited on 23 Sep, the warning stayed

The page carrying the production reservation is stamped 23 Sep 2026, 09:46 EDT (commit 6375bfff, DOCS-2765). The line do not use in production workloads is untouched and Enterprise is still listed as unsupported. The announcement of 11 Sep 2026, which includes Enterprise appliances and calls support orderable, remains as a second statement inside the same company.

One outside PR landed in three days, three others are still waiting

PR #110 imports foreign ZFS snapshots into the guest configuration, so that qm rollback stops failing quietly against a newer snapshot on the zvol. It arrived on 19 Sep 2026 and was merged by iXsystems on 22 Sep 2026 at 15:05 UTC, 2848 lines in two commits. The tool is called truenas-proxmox-manage import-snapshots --dry-run. Our reading of 16 Sep 2026 does not survive that: #110 was inside after three days, while #95, #94 and #97 remain open after five to eight weeks.

A setup walkthrough from outside

A long installation walkthrough appeared on 22 Sep 2026 (VirtualizationHowto). It shows the shape in which the plugin is being tried right now: one node, TrueNAS as a VM with three virtual disks, iSCSI as transport, no HA, no load, no delete test. The production warning from the documentation appears nowhere in the text. The post is useful anyway, because it documents a real tripwire: TrueNAS refuses to import the pool when the virtual SCSI disks carry no serial number, and Proxmox does not supply one by default. The fix is serial=TNBOOT001 per disk in /etc/pve/qemu-server/<vmid>.conf.

What we make of it

Our production stack stays as it is: DRBD and LINSTOR as shared storage, Vitastor still under watch (field test), TrueNAS remaining our file server (field report). What changes: if you run a TrueNAS in your rack, want snapshots driven from the array side and can live with a beta, there is now a clean path without LUN handwork. In our environment that means the homelab on pve7, the industrial cluster stays out of it. We will test it there against this list:

Versions first: SCALE 25.10 or newer, PVE 9.x, plugin from the signed APT repository.
The standard lap: create, live snapshot, rollback, resize, destroy, with no orphans left behind.
Kill the API session under load: does the 30-day failure need time, or does a dropped connection trigger it too?
vzdump on LXC (a documented vzdump collision) and destroy after an aborted clone.
Measure snapshot I/O behaviour against NFS snapshots: does the copy-on-write variant actually spare the guest?
HA manager check after installation: stop a guest, let HA start it again, with no manual service restart in between.
Force a write error: dm-flakey on a target disk, then a clone or a disk move across it. If the task reports TASK OK while writes disappear, bug 8054 is live. That point stands on its own and belongs on any test list covering block targets.

We will not put it into production while two conditions are open. First, the production warning has to leave the documentation. The documentation is what we measure, and the announcement of 11 Sep 2026 is no release approval; on 23 Sep 2026 the sentence is still in place, also after that day's edit. Second, corruption issue #32 has to be closed with a bugfix and a reproduction, together with the four remaining large-I/O issues in the NVMe group (#96, #45, #12, #4). The sweep of 22 Sep 2026 showed the maintainers can clear 22 issues in one day. Until the NVMe group is closed, we install this plugin in the lab only.