Manages TrueNAS ZFS volumes over iSCSI via the TrueNAS REST API. Each VM gets its own dedicated iSCSI target — no SSH keys or pre-created targets required.
tpmstate0) cannot be stored on this storage type.
If your VM uses Secure Boot / TPM, store the TPM state disk on local-lvm or NFS.
All other disk types (virtio, scsi, IDE, EFI) work normally.
| Field | Required | Description |
|---|---|---|
ID | Yes | Storage name used internally by Proxmox. Letters, numbers, and hyphens only. Cannot be changed after creation. |
TrueNAS Host | Yes | IP address or hostname of the TrueNAS server. Also used as the iSCSI portal address
unless Portal IP is set separately. Cannot be changed after creation. |
API Key | No* | Bearer token generated in TrueNAS. Click the eye icon to show/hide while pasting. Leave blank if you are using a keyfile (see below). |
Pool / Dataset Path | Yes | ZFS pool or dataset where volumes are created. Examples: tank or
tank/proxmox/vdisks. Cannot be changed after creation. |
Sub-dataset | No | Extra sub-path appended below Pool / Dataset Path. Leave blank in most cases. |
Shared | — | Should be checked for all cluster deployments. Marks storage accessible from all nodes. |
Use SSL | — | Use HTTPS for API calls. Recommended. Disable only if TrueNAS has no HTTPS configured. |
Verify SSL Certificate | — | Validate the TrueNAS HTTPS certificate against a CA. Leave unchecked for self-signed certificates (common in homelab setups). |
Portal IP | No | Override the iSCSI portal address. Use when the TrueNAS management IP differs from the iSCSI data IP. Defaults to TrueNAS Host if blank. |
Target IQN | No | Reference target used to discover portal and initiator group settings for new per-VM targets. Auto-discovered if blank. |
By default the API token is stored in /etc/pve/storage.cfg, which is replicated
in plaintext across the cluster. For production, store the token in a private keyfile instead:
# Run on each Proxmox node — replace 'truenas-vms' with your storage ID
STORAGEID="truenas-vms"
KEYFILE="/etc/pve/priv/truenas-${STORAGEID}.key"
echo -n "your-api-token-here" > "$KEYFILE"
chmod 600 "$KEYFILE"
pvesm set "$STORAGEID" --truenas_api_key ""
The plugin checks /etc/pve/priv/truenas-<storeid>.key automatically.
The keyfile must exist on every Proxmox node — copy it manually, as
/etc/pve/priv/ is not replicated across the cluster.
When you create a VM disk, the plugin:
zvol) on TrueNAS under your configured pool/datasetproxmox-vm-<vmid> if one does not existQEMU connects directly to TrueNAS via an iscsi:// URI — no iscsiadm
session management is needed on the Proxmox host. When the last disk for a VM is deleted,
the per-VM target is automatically removed.
| Symptom | Fix |
|---|---|
| "TrueNAS (ZFS/iSCSI)" missing from Add Storage dropdown | Hard-refresh the browser: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) |
| 401 Unauthorized in logs | API key is wrong, expired, or revoked — generate a new one in TrueNAS |
| No iSCSI portals found | Set the TrueNAS portal to listen on 0.0.0.0, or set Portal IP to match
the exact IP the portal is listening on |
| VM won't boot / disk not accessible | Check that TCP 3260 is reachable from the Proxmox node:
nc -zv <truenas-ip> 3260. Check the initiator group allows the
Proxmox node's IP. |
| API key stopped working after SCALE upgrade | SCALE 25.04+ may revoke keys on upgrade. Generate a new API key and update the storage config in Proxmox. |
| Portal PUT returns "Extra inputs are not permitted" (SCALE 25.04+) | Omit the port field from listen in
PUT /api/v2.0/iscsi/portal/id/<n>. SCALE 25.04 no longer accepts
it. See §6.9 in getting-started.md. |
# Plugin log messages on the Proxmox node grep -i TrueNASPlugin /var/log/syslog # PVE daemon journal journalctl -u pvedaemon --since "30 minutes ago" | grep -i truenas # Install / removal log cat /var/log/truenas-proxmox-install.log
curl -sk -H "Authorization: Bearer <your-api-key>"
https://<truenas-host>/api/v2.0/iscsi/global | python3 -m json.toolbasename field confirms the API key and connectivity are working.