Skip to content

wiki

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

wiki

README.md

TrueNAS Proxmox VE Storage Plugin - Documentation Wiki

Comprehensive documentation for the TrueNAS Proxmox VE Storage Plugin.

Official repository: https://github.com/truenas/truenas-proxmox-plugin

Official wiki home: https://github.com/truenas/truenas-proxmox-plugin/wiki

Documentation Index

Getting Started

  • Installation Guide - Complete installation instructions for Proxmox VE and TrueNAS SCALE, including single-node and cluster deployments

Configuration

  • Configuration Reference - Complete reference for all configuration parameters with examples for different use cases

Testing and Validation

  • Testing Guide - Comprehensive guide for using the automated test suite to validate plugin functionality
  • Tools and Utilities - Test suite and cluster deployment script documentation

Operations

Advanced Topics

  • Advanced Features - Performance tuning, cluster configuration, security hardening, and enterprise features
  • Multi-Tenancy / Shared TrueNAS - Safely sharing a single TrueNAS system across multiple Proxmox clusters
  • API Reference - Technical details on TrueNAS API integration, endpoints, and error handling

Development

Important Information

  • Known Limitations - Critical limitations, restrictions, and workarounds you should know

Quick Links

Common Tasks

Installation:

Development / Maintainers:

Testing:

Tools:

Configuration:

Troubleshooting:

Performance:

Multi-Tenancy:

Security:

Documentation Structure

wiki/
├── README.md                   # This file - documentation index
├── Installation.md             # Installation and setup guide
├── Configuration.md            # Configuration reference
├── Testing.md                  # Test suite usage and validation
├── Tools.md                    # Tools and utilities (test suite, health check, diagnostics bundle, orphan cleanup, cluster deployment)
├── Troubleshooting.md          # Common issues and solutions
├── Advanced-Features.md        # Performance, clustering, security
├── Multi-Tenancy.md            # Sharing TrueNAS across multiple clusters
├── API-Reference.md            # TrueNAS API technical details
├── Ideas.md                    # Feature ideas and development roadmap
├── Changelog.md                # Version history and release notes
└── Known-Limitations.md        # Important limitations

Documentation Conventions

Code Blocks

Bash Commands:

# Commands to run on Proxmox nodes
pvesm status

Configuration Files:

# /etc/pve/storage.cfg
truenasplugin: storage-name
    api_host 192.168.1.100

Example Output:

Expected output from commands

Admonitions

✅ Recommended: Best practices and recommended approaches

❌ Not Recommended: Approaches to avoid

⚠️ Warning: Important warnings and cautions

💡 Tip: Helpful tips and tricks

File Paths

Absolute paths are shown for all files:

  • Proxmox: /etc/pve/storage.cfg, /usr/share/perl5/PVE/Storage/Custom/
  • TrueNAS: /var/log/middlewared.log, /mnt/tank/proxmox

Placeholders

Replace these placeholders with your actual values:

  • YOUR_TRUENAS_IP - Your TrueNAS IP address
  • YOUR_API_KEY - Your TrueNAS API key
  • VMID - Proxmox VM ID number
  • your-storage-name - Your storage identifier

Contributing to Documentation

Found an error or want to improve documentation?

  1. Check existing content for accuracy
  2. Ensure examples are tested and working
  3. Follow existing formatting conventions
  4. Keep explanations clear and concise

Support

For issues not covered in documentation:

  1. Review all relevant documentation sections
  2. Check Known Limitations
  3. Search existing GitHub issues at https://github.com/truenas/truenas-proxmox-plugin/issues
  4. Create a new GitHub issue with detailed information

Version Information

Version: 2.0.3 Last Updated: February 8, 2026 Compatibility: Proxmox VE 8.x+, TrueNAS SCALE 25.10+