Proxmox VE Storage Plugin

The TrueNAS Proxmox VE Storage Plugin lets you use TrueNAS as high-performance block storage for Proxmox VE clusters, accessible via iSCSI or NVMe/TCP. Unlike standard iSCSI, the plugin automates zvol creation, iSCSI extent mapping, and target association through the TrueNAS API. You provision storage directly from Proxmox without manual setup on the TrueNAS side. It uses ZFS to provide instant, space-efficient snapshots, including live VM state with RAM. It supports CHAP authentication, thin provisioning, ZFS compression, and multipath I/O. It works with Proxmox cluster deployments that use shared storage.

The TrueNAS Proxmox VE Storage Plugin is developed and maintained by TrueNAS. Proxmox VE is a third-party virtualization platform not affiliated with TrueNAS. TrueNAS support covers plugin functionality only. For Proxmox VE issues, consult the Proxmox documentation and Proxmox support. To report a plugin bug or follow development progress, see the truenas-proxmox-plugin GitHub repository.

This plugin requires Proxmox VE 8.x or later (9.x recommended) and TrueNAS 25.10 or later. NVMe/TCP mode requires Proxmox VE 9.x or later.

Proxmox nodes must be able to reach TrueNAS on port 3260 (iSCSI) and port 443 (WebSocket API). For NVMe/TCP mode, install nvme-cli on each Proxmox node. You must also have a TrueNAS API key with sufficient privileges to create and manage datasets and iSCSI or NVMe/TCP resources.

Before installing the plugin, complete these steps on TrueNAS:

1. Create a ZFS dataset to use for Proxmox storage (for example, tank/proxmox). Set Dataset Preset to Generic.
2. Enable the iSCSI service in System > Services and set it to start automatically.
3. Create an iSCSI portal in Shares > iSCSI > Portals. Set the IP address to your TrueNAS IP and the port to 3260.
4. Create an iSCSI initiator group in Shares > iSCSI > Initiators. Leave the defaults to allow all initiators.
5. Create an iSCSI target in Shares > iSCSI > Targets. After saving, edit the target and add a group. Set the Portal Group ID to the portal you created in step 3. Set the Initiator Group ID to the initiator you created in step 4.
6. Generate a TrueNAS API key in Credentials > Users. Select your user, then click Add API Key on the Access widget to open the Add API Key screen. For a user that already has a key, click View API Keys on the Access widget instead, then click Add on the User API Keys screen. Enter a name for the key and click Save. Save the key securely. TrueNAS does not show the key again after you close the screen.
7. For NVMe/TCP mode, enable the NVMe-oF service in System > Services.

Granting the built-in SHARING_ADMIN role to the user account for the API key covers the steps above. For a narrower, least-privilege role set instead, see Minimum API Permissions in Additional Resources.

See the Installation Guide for detailed TrueNAS setup steps.

The plugin is installed on each Proxmox VE node, not on TrueNAS.

The APT repository method provides automatic version detection and updates. Run the following command on each Proxmox node. The installer automatically detects your Proxmox VE version and selects the correct APT suite.

This command installs from the alpha branch. The plugin team currently publishes its latest fixes there ahead of main.

bash <(curl -sSL https://raw.githubusercontent.com/truenas/truenas-proxmox-plugin/alpha/install.sh) --non-interactive --apt-install

cat >/etc/apt/sources.list.d/truenas-proxmox-plugin.sources <<'EOF'
Types: deb
URIs: https://truenas.github.io/truenas-proxmox-plugin/apt/
Suites: <bookworm|trixie>
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/truenas-proxmox-plugin.gpg
EOF

mkdir -p /etc/apt/keyrings
curl -fsSL https://truenas.github.io/truenas-proxmox-plugin/apt/pubkey.gpg -o /etc/apt/keyrings/truenas-proxmox-plugin.gpg
apt-get update
apt-get install -y truenas-proxmox-plugin

Download a release package from the releases page and install it directly. Replace <RELEASE_TAG> and <DEB_VERSION> with the values from the release you want to install:

wget https://github.com/truenas/truenas-proxmox-plugin/releases/download/v<RELEASE_TAG>/truenas-proxmox-plugin_<DEB_VERSION>_all.deb
dpkg -i truenas-proxmox-plugin_<DEB_VERSION>_all.deb
apt-get -f install -y

The interactive installer provides a menu-driven setup with a configuration wizard, health checks, and built-in validation. It supports both iSCSI and NVMe/TCP. Run the following command and follow the prompts:

bash <(curl -sSL https://raw.githubusercontent.com/truenas/truenas-proxmox-plugin/alpha/install.sh)

The interactive installer configures /etc/pve/storage.cfg automatically and supports cluster-wide installation across all nodes simultaneously. If you used the interactive installer, review the examples in the Configuration section below to verify or modify your setup.

If you used the APT repository or .deb installation, manually add a storage backend entry to /etc/pve/storage.cfg on each Proxmox node using the GNU nano text editor.

nano /etc/pve/storage.cfg

truenasplugin: truenas-storage
    tn_api_host 192.168.1.100
    tn_api_key 1-your-truenas-api-key-here
    tn_api_insecure 1
    tn_target_iqn iqn.2005-10.org.freenas.ctl:proxmox
    tn_dataset tank/proxmox
    tn_discovery_portal 192.168.1.100:3260
    content images
    shared 1

truenasplugin: truenas-nvme
    tn_api_host 192.168.1.100
    tn_api_key 1-your-truenas-api-key-here
    tn_api_insecure 1
    tn_transport_mode nvme-tcp
    tn_subsystem_nqn nqn.2005-10.org.freenas.ctl:proxmox-nvme
    tn_dataset tank/proxmox
    tn_discovery_portal 192.168.1.100:4420
    content images
    shared 1

In both examples, replace 192.168.1.100 with your TrueNAS IP address. Replace the API key value with your generated key, and tank/proxmox with your ZFS dataset path. tn_api_insecure 1 disables SSL certificate verification. Include this parameter when TrueNAS uses a self-signed certificate, which is the default. Remove this line only if TrueNAS uses a valid signed certificate.

Every plugin-specific storage.cfg parameter uses a tn_ prefix (tn_api_host, tn_dataset, and so on). The content and shared parameters are standard Proxmox storage options and keep their unprefixed names.

For all available configuration parameters, see the Configuration Reference.

The plugin team maintains an extensive wiki covering setup, configuration, and operation in more depth than this overview.

• Installation Guide: Full installation walkthrough, including cluster-wide deployment and update procedures.
• Configuration Reference: Every storage.cfg parameter, with example configurations for single-node, cluster, HA, and IPv6 deployments.
• NVMe/TCP Setup Guide: Detailed NVMe/TCP setup, including DH-CHAP authentication and multipath configuration.
• Minimum API Permissions: A least-privilege role set for the plugin API user, as an alternative to a broad admin role.

• Troubleshooting Guide: Common error messages and diagnostic steps for installation, connection, and volume issues.
• Known Limitations: Restrictions and workarounds to review before deploying to production.
• Changelog: Version history for the plugin.

• Advanced Features: Performance tuning, cluster and HA configuration, and security hardening.
• Multi-Tenancy: Guidance for safely sharing one TrueNAS system across multiple Proxmox clusters.
• API Reference: Technical detail on the TrueNAS API integration used by the plugin, intended for integrators and contributors.

• Testing Guide: Covers the plugin development test suite. The built-in installer already covers day-to-day health checks. This suite is for plugin development and debugging, not production systems.
• Tools and Utilities: Reference for the installer diagnostics menu and other included tooling.