How thegrandwazoo/freenas-proxmox works
Project Type and Purpose
• This is an open-source Proxmox VE plugin that extends the built-in ZFS-over-iSCSI storage plugin to talk to TrueNAS (and legacy FreeNAS) hosts.
• Key artifacts:
• perl5/PVE/Storage/ZFSPlugin*.pm.patch and LunCmd/FreeNAS.pm – backend plugin logic
• perl5/REST/Client.pm – HTTP client for TrueNAS API calls
• pve-manager/js/pvemanagerlib*.js.patch – front-end UI extensions to expose the new storage type
• pve-docs/api-viewer – API documentation patches
File Structure Analysis
• Top-level: packaging and repo config (.github, LICENSE, README, _config.yml)
• perl5/PVE/Storage – contains Perl modules and patches for:
• ZFSPlugin.pm (core plugin hooks into Proxmox storage layer)
• LunCmd/FreeNAS.pm (legacy command set for FreeNAS over SSH)
• ZFSPlugin-<version>.pm.patch (versioned upstream-patch bundles)
• perl5/REST/Client.pm – HTTP client dependency (used for TrueNAS API)
• pve-manager/js – front-end JavaScript patches to add “TrueNAS ZFS-iSCSI” UI entry
• pve-docs/api-viewer – updates to API docs to reflect the new storage backend
• stable-*/ – versioned snapshots of the same structure for Proxmox stable branches
a. Main Components
• Proxmox VE Web UI (pve-manager/js)
• Proxmox VE API Server (Perl “pvedaemon” + REST endpoints)
• Storage Plugin Layer (Perl modules under PVE::Storage: ZFSPlugin, LunCmd)
• SSH Interface (calls to ssh / iscsiadm binaries)
• TrueNAS Host(s)
• TrueNAS REST API endpoint
• ZFS pools + iSCSI target service
b. Relationships and Data Flows
1. User invokes “Add Storage → TrueNAS ZFS-iSCSI” in Proxmox VE Web UI
2. Web UI JavaScript calls Proxmox backend API over HTTPS
3. Proxmox API dispatches to PVE::Storage::ZFSPlugin plugin methods
4. Plugin uses either:
• SSH (via ssh + iscsiadm) to query ZFS pools and LUNs on the TrueNAS host
• REST::Client HTTP calls to TrueNAS API for pool/LUN metadata
5. Plugin returns list of available iSCSI targets and device paths
6. Proxmox configures local iSCSI session (iscsiadm), exposes the disk to VMs
7. Optionally, scheduler service (pvescheduler) picks up maintenance tasks
c. Architectural Patterns & Design Principles
• Plugin architecture: clean separation between core Proxmox storage framework and third-party plugin logic
• Patch-based extensibility: upstream Proxmox code is patched via versioned .pm.patch files
• Dual-mode discovery: SSH‐based fallback (LunCmd/FreeNAS) and REST API approach (TrueNAS)
• Standard HTTP/SSH protocols and existing Perl modules (REST::Client) to minimize new dependencies
d. Technologies, Frameworks, Libraries
• Perl 5 (PVE modules, REST::Client)
• JavaScript (pve-managerlib)
• Linux CLI tools: ssh, iscsiadm
• Proxmox VE API and scheduler services
• TrueNAS REST API
Essential Architectural Elements to Capture
• The overlay/patch mechanism (how existing PVE::Storage code is modified)
• Dual discovery mechanisms: SSH-based vs. REST API
• Interaction sequence: UI → API → plugin → TrueNAS → plugin → Proxmox kernel (iSCSI) → VMs
• The role of the scheduler/maintenance (e.g., post-install systemctl restart pvescheduler.service)