TrueNAS Proxmox VE Storage Plugin

A high-performance storage plugin for Proxmox VE that integrates TrueNAS SCALE via iSCSI or NVMe/TCP, featuring live snapshots, LXC container storage, ZFS integration, and cluster compatibility.

Features

• Dual Transport Support - iSCSI (traditional) or NVMe/TCP (lower latency) block storage
• iSCSI Block Storage - Direct integration with TrueNAS SCALE via iSCSI targets
• NVMe/TCP Support - Modern NVMe over TCP for reduced latency and CPU overhead (TrueNAS SCALE 25.10+)
• LXC Container Storage - Block-backed container rootfs support alongside VM disk storage
• ZFS Snapshots - Instant, space-efficient snapshots via TrueNAS ZFS
• Live Snapshots - Full VM state snapshots including RAM (vmstate)
• Cluster Compatible - Full support for Proxmox VE clusters with shared storage
• Automatic Volume Management - Dynamic zvol creation and iSCSI extent mapping
• Configuration Validation - Pre-flight checks and validation prevent misconfigurations
• Rate Limiting Protection - Automatic retry with exponential backoff for TrueNAS API limits
• Storage Efficiency - Thin provisioning and ZFS compression support
• Multi-path Support - Native support for iSCSI multipathing
• CHAP Authentication - Optional CHAP security for iSCSI connections
• Volume Resize - Grow-only resize with preflight space checks
• Error Recovery - Comprehensive error handling with actionable error messages
• Performance Optimization - Configurable block sizes and sparse volumes

Feature Comparison

Legend: ✅ Native Support | ⚠️ Via Additional Layer | ❌ Not Supported

Notes:

• Standard iSCSI: Raw iSCSI lacks native snapshots/clones. Use LVM-thin on iSCSI for full snapshot/clone/thin-provisioning support, or volume chains (Proxmox VE 9+). Container storage available via LVM on iSCSI.
• NFS: Snapshots/clones require qcow2 format (performance overhead vs raw). Supports backups, ISOs, and containers natively.
• TrueNAS Plugin: Native ZFS features with raw image performance and automated zvol/iSCSI extent management via TrueNAS API. Container (LXC) rootfs stored as ext4-formatted block devices.
• VM State Snapshots: All storage types supporting the 'images' content type can store vmstate files for live snapshots with RAM.

Quick Start

Installation

Option 1 (Recommended): APT Repository

Install from the official APT repository with the installer:

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

Optional suite override (for scripted installs):

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

Suite mapping:

• Proxmox VE 8 -> bookworm
• Proxmox VE 9 -> trixie

Manual deb822 source setup:

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

Option 2: Direct .deb Installation

Download a release package and install it directly:

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

Option 3: Interactive Installer (Existing Workflow)

Download and run the installer interactively:

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

Or download first, then run:

wget https://raw.githubusercontent.com/truenas/truenas-proxmox-plugin/alpha/install.sh
chmod +x install.sh
./install.sh

The installer provides:

• ✅ Interactive menu-driven setup
• ✅ Automatic version detection and updates
• ✅ Built-in configuration wizard (supports iSCSI and NVMe/TCP)
• ✅ Health check validation
• ✅ Plugin function testing with graceful interrupt handling (Ctrl+C)
• ✅ Backup and rollback support
• ✅ Cluster-wide installation (install/update on all nodes simultaneously)

For expanded installation instructions, see the Installation Guide.

Alternative: Manual Plugin File Installation

If you prefer manual plugin file installation:

# Download the plugin
wget https://raw.githubusercontent.com/truenas/truenas-proxmox-plugin/main/TrueNASPlugin.pm

# Copy to plugin directory
cp TrueNASPlugin.pm /usr/share/perl5/PVE/Storage/Custom/

# Set permissions
chmod 644 /usr/share/perl5/PVE/Storage/Custom/TrueNASPlugin.pm

# Restart Proxmox services
systemctl restart pvedaemon pveproxy

Configuration

Configure Storage

Add to /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

Replace:

• 192.168.1.100 with your TrueNAS IP
• 1-your-truenas-api-key-here with your TrueNAS API key
• tank/proxmox with your ZFS dataset path

NVMe/TCP Configuration (Alternative)

For lower latency and reduced CPU overhead, use NVMe/TCP instead of iSCSI:

truenasplugin: truenas-nvme
    tn_api_host 192.168.1.100
    tn_api_key 1-your-truenas-api-key-here
    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

NVMe/TCP Requirements:

• TrueNAS SCALE 25.10.0 or later
• Proxmox VE 9.x or later
• Install nvme-cli on Proxmox: apt-get install nvme-cli
• Enable NVMe-oF Target service in TrueNAS

See wiki/NVMe-Setup.md for complete NVMe/TCP setup guide.

TrueNAS SCALE Setup

1. Create Dataset

Navigate to Datasets → Create new dataset:

• Name: proxmox (under existing pool like tank)
• Dataset Preset: Generic

2. Enable iSCSI Service

Navigate to System Settings → Services:

• Enable iSCSI service
• Set to start automatically

3. Create iSCSI Target

Navigate to Shares → Block Shares (iSCSI) → Targets:

• Click Add
• Target Name: proxmox (becomes iqn.2005-10.org.freenas.ctl:proxmox)
• Target Mode: iSCSI
• Click Save

4. Create iSCSI Portal

Navigate to Shares → Block Shares (iSCSI) → Portals:

• Default portal should exist on 0.0.0.0:3260
• If not, create one with your TrueNAS IP and port 3260

5. Generate API Key

Navigate to Credentials → Local Users:

• Select root user (or create dedicated user)
• Click Edit
• Scroll to API Key section
• Click Add to generate new API key
• Copy and save the API key securely (you won't be able to see it again)

6. Verify Configuration

The plugin will automatically:

• Create zvols under your dataset (tank/proxmox/vm-XXX-disk-N)
• Create iSCSI extents for each zvol
• Associate extents with your target
• Handle all iSCSI session management

Basic Usage

Create VM with TrueNAS Storage

# Create VM
qm create 100 --name "test-vm" --memory 2048 --cores 2

# Add disk from TrueNAS storage
qm set 100 --scsi0 truenas-storage:32

# Start VM
qm start 100

Snapshot Operations

# Create snapshot
qm snapshot 100 backup1 --description "Before updates"

# Create live snapshot (with RAM state)
qm snapshot 100 live1 --vmstate 1

# List snapshots
qm listsnapshot 100

# Rollback to snapshot
qm rollback 100 backup1

# Delete snapshot
qm delsnapshot 100 backup1

Storage Management

# Check storage status
pvesm status truenas-storage

# List all volumes
pvesm list truenas-storage

# Check available space
pvesm status

Advanced Installation Options

The installer supports additional features:

• Version management - Install, update, or rollback to specific versions
• Configuration wizard - Interactive guided setup with validation
• Health checks - 13-point system validation supporting both iSCSI and NVMe/TCP with consistent 30-character label formatting
• Plugin testing - Integrated 8-test validation of core plugin operations with graceful interrupt handling and health-check style output
• Cluster support - Automatic cluster detection and warnings
• Backup management - Automatic backups with rollback capability

For detailed installation instructions and troubleshooting, see the Installation Guide.

Documentation

Comprehensive documentation is available in the Wiki:

• Installation Guide - Detailed installation steps for both Proxmox and TrueNAS
• Packaging Guide - PACKAGING maintainer workflow for Debian builds, lintian, signing, and APT publishing
• Configuration Reference - Complete parameter reference and examples
• Tools and Utilities - Test suite and cluster deployment scripts
• Troubleshooting Guide - Common issues and solutions
• Advanced Features - Performance tuning, clustering, security
• API Reference - Technical details on TrueNAS API integration
• Minimum API Permissions - Least-privilege TrueNAS role set for the API user
• NVMe Setup Guide - NVMe/TCP transport setup and authentication
• Multi-Tenancy - Sharing TrueNAS across multiple Proxmox clusters
• Testing Guide - Automated test suite for plugin validation
• Known Limitations - Important limitations and workarounds
• Ideas and Roadmap - Feature ideas and development roadmap
• Changelog - Version history and release notes

Important: TrueNAS API Changes

TrueNAS SCALE 25.10+ Required: This plugin requires TrueNAS SCALE 25.10 or later. WebSocket API is the only supported transport method.

Requirements

• Proxmox VE 8.x or later (9.x recommended)
• TrueNAS SCALE 25.10 or later
• Network connectivity between Proxmox nodes and TrueNAS (iSCSI on port 3260, WebSocket API on port 443)

Support

For issues, questions, or contributions:

• Review the Troubleshooting Guide
• Check Known Limitations
• Report bugs or request features at https://github.com/truenas/truenas-proxmox-plugin/issues

License

This project is provided as-is for use with Proxmox VE and TrueNAS SCALE.

---

Version: 2.1.5 Last Updated: June 16, 2026 Compatibility: Proxmox VE 8.x+, TrueNAS SCALE 25.10+