# thegrandwazoo/freenas-proxmox architecture

> Architecture diagram of the GitHub repository thegrandwazoo/freenas-proxmox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thegrandwazoo/freenas-proxmox
- Repository: https://github.com/thegrandwazoo/freenas-proxmox

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Repository Configuration"
        LICENSE["LICENSE"]:::config
        README["README.md"]:::config
        GITHUB[".github/"]:::config
    end
    click LICENSE "https://github.com/thegrandwazoo/freenas-proxmox/tree/master/LICENSE"
    click README "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/README.md"
    click GITHUB "https://github.com/thegrandwazoo/freenas-proxmox/tree/master/.github/"

    subgraph "Stable Branch Snapshots"
        SB_PLUGINS["ZFSPlugin-*.pm.patch"]:::config
        SB_FREENAS["LunCmd/FreeNAS.pm"]:::config
        SB_UI["pvemanagerlib-*.js.patch"]:::config
        SB_DOC["apidoc-*.js.patch"]:::config
    end
    click SB_PLUGINS "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/stable-*/perl5/PVE/Storage/ZFSPlugin-*.pm.patch"
    click SB_FREENAS "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/stable-*/perl5/PVE/Storage/LunCmd/FreeNAS.pm"
    click SB_UI "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/stable-*/pve-manager/js/pvemanagerlib-*.js.patch"
    click SB_DOC "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/stable-*/pve-docs/api-viewer/apidoc-*.js.patch"

    subgraph "Frontend Layer"
        UI["Proxmox VE Web UI<br>(pve-manager/js patches)"]:::frontend
    end
    click UI "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/pve-manager/js/pvemanagerlib.js.patch"

    subgraph "Backend Layer"
        API["Proxmox VE API Server<br>(Perl pvedaemon)"]:::backend
        SCHED["Scheduler (pvescheduler)"]:::backend
    end

    subgraph "Storage Plugin Layer"
        PLUGIN["ZFS-iSCSI Plugin<br>(ZFSPlugin*.pm.patch)"]:::plugin
        SSHTOOL["SSH / iscsiadm CLI"]:::plugin
        FREENAS["Legacy FreeNAS SSH Backend<br>(FreeNAS.pm)"]:::plugin
        CLIENT["TrueNAS REST API Client<br>(REST/Client.pm)"]:::plugin
    end
    click PLUGIN "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/perl5/PVE/Storage/ZFSPlugin.pm.patch"
    click FREENAS "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/perl5/PVE/Storage/LunCmd/FreeNAS.pm"
    click CLIENT "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/perl5/REST/Client.pm"

    subgraph "Documentation"
        DOCS["API Documentation Patches<br>(pve-docs/api-viewer)"]:::docs
    end
    click DOCS "https://github.com/thegrandwazoo/freenas-proxmox/blob/master/pve-docs/api-viewer/apidoc.js.patch"

    subgraph "TrueNAS Host"
        TR_HOST["TrueNAS Host<br>(REST API + iSCSI)"]:::external
    end

    UI -->|"HTTPS API call"| API
    API -->|"dispatch to plugin"| PLUGIN
    PLUGIN -->|"SSH calls"| SSHTOOL
    PLUGIN -->|"SSH-based discovery"| FREENAS
    PLUGIN -->|"REST API calls"| CLIENT
    CLIENT -->|"HTTP"| TR_HOST
    FREENAS -->|"SSH"| TR_HOST
    SSHTOOL -->|"iscsiadm"| TR_HOST
    TR_HOST -->|"response"| CLIENT
    TR_HOST -->|"response"| FREENAS
    PLUGIN -->|"return data"| API
    API -->|"API response"| UI
    PLUGIN -->|".trigger maintenance"| SCHED
    SCHED -.->|"periodic tasks"| PLUGIN

    classDef frontend fill:#cce5ff,stroke:#003366,color:#003366;
    classDef backend fill:#e6f2ff,stroke:#0059b3,color:#0059b3;
    classDef plugin fill:#e6ffe6,stroke:#339933,color:#339933;
    classDef external fill:#ffe6cc,stroke:#cc6600,color:#cc6600;
    classDef docs fill:#fff0e6,stroke:#ff9966,color:#ff9966;
    classDef config fill:#f2f2f2,stroke:#999999,color:#333333;
```
