From c9dff84c1ee71e1301312ff84298c60a45de8997 Mon Sep 17 00:00:00 2001 From: Kevin Adams Date: Tue, 2 Jun 2026 16:12:00 -0400 Subject: [PATCH] docs: remove SSH references and update install URLs to GitHub Pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit v3.0 requires no SSH — QEMU connects directly via iscsi://. README "How It Works" and troubleshooting sections had v2.x SSH carryover. Compatibility matrix now shows v3.x as stable with PVE 9 confirmed. All install instructions updated from Cloudsmith to the GitHub Pages apt repo (thegrandwazoo.github.io/freenas-proxmox, v3 dist track). Cloudsmith testing channel retained for beta builds only. architecture.md updated to reflect ADR-010 and the live GitHub Pages publish step in CI. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 30 ++++++++++-------------------- docs/architecture.md | 16 +++++++++------- docs/getting-started.md | 11 +++++------ docs/migrating-from-v2.md | 11 +++++++++-- 4 files changed, 33 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index e267b9f..08842d8 100644 --- a/README.md +++ b/README.md @@ -30,14 +30,12 @@ A Proxmox VE storage plugin that manages ZFS-over-iSCSI volumes on TrueNAS (CORE ## How It Works -Proxmox VE's built-in ZFS-over-iSCSI storage type uses SSH to manage LUNs on the storage server. This plugin replaces that SSH-based management layer with direct calls to the **TrueNAS REST API**, giving you: +This plugin is a native `PVE::Storage::Custom` type — Proxmox discovers it automatically and treats it like any other storage backend. When you create a VM disk, the plugin calls the **TrueNAS REST API** to provision a ZFS volume (zvol) and a dedicated per-VM iSCSI target, then hands Proxmox an `iscsi://` path. QEMU opens that path directly — no SSH, no `iscsiadm`, no kernel iSCSI sessions on the Proxmox host. -- API token (Bearer) or username/password authentication -- Automatic TrueNAS API version detection (v1 and v2) -- Support for both TrueNAS CORE and TrueNAS SCALE -- Proper rollback when operations fail (no dangling iSCSI extents) - -> **Note:** Proxmox still uses `iscsiadm` to connect and disconnect the iSCSI session on the Proxmox host itself — that part is handled by the core Proxmox code and does not require SSH. The SSH keys documented in the [Proxmox ZFS-over-iSCSI wiki](https://pve.proxmox.com/wiki/Storage:_ZFS_over_iSCSI) are still required for the ZFS pool listing step. +- Bearer Token (API key) authentication — no username/password, no SSH keys +- Per-VM iSCSI targets (`proxmox-vm-`) — removing one disk never affects other VMs +- Automatic rollback when operations fail (no dangling iSCSI extents) +- Supports TrueNAS CORE 13.x and TrueNAS SCALE 24.10–25.10 --- @@ -47,8 +45,7 @@ Proxmox VE's built-in ZFS-over-iSCSI storage type uses SSH to manage LUNs on the | Plugin Version | Proxmox VE | TrueNAS CORE | TrueNAS SCALE | Status | |:--------------:|:----------:|:------------:|:-------------:|:------:| -| **3.x** *(beta)* | 8.4.x ✅ | 13.0-U6+ ✅ | Electric Eel (24.10) ✅, Fangtooth (25.04) ✅, Goldeye (25.10) ✅ | Beta — active development | -| **3.x** *(planned)* | 9.x ⏳ | 13.0-U6+ | Electric Eel (24.10)+, Goldeye (25.10)+ | v3.1.0 — in progress | +| **3.x** *(stable)* | 8.4.x ✅, 9.x ✅ | 13.0-U6+ ✅ | Electric Eel (24.10) ✅, Fangtooth (25.04) ✅, Goldeye (25.10) ✅ | Stable | | **2.x** *(stable)* | 7.x ⚠️, 8.0–8.3 ✅, 8.4.x ✅ | 11.3+ | 22.02+ | Active | | **1.x** *(legacy)* | 5.x, 6.x | 11.x | — | Unsupported | @@ -335,27 +332,20 @@ iscsiadm: No active sessions. **Layer 3 — Proxmox core storage stack** -Errors from PVE's own storage subsystem — ZFSPlugin.pm, pvedaemon, pool listing via SSH, or storage.cfg parsing. These exist regardless of which iSCSI plugin you use. +Errors from PVE's own storage subsystem — pvedaemon, pvestatd, or storage.cfg parsing. Common causes: -- SSH keys not configured between Proxmox and TrueNAS (required for ZFS pool listing — see [Prerequisites](#prerequisites)) -- `storage.cfg` syntax error +- `storage.cfg` syntax error or stale config keys (especially after migrating from v2.x — see [migration guide](docs/migrating-from-v2.md)) - `pvedaemon` or `pvestatd` service crashed -Example log line: -``` -unable to run command '/usr/bin/ssh ... zfs list ...': exit code 255 -``` - **Quick triage:** | Symptom | Likely layer | First check | |---------|-------------|-------------| | Disk creation fails, API error in task log | Plugin (Layer 1) | API key, SSL setting, TrueNAS API reachable | -| Disk created on TrueNAS but Proxmox reports error | Plugin (Layer 1) | syslog for `freenas-proxmox:` lines | +| Disk created on TrueNAS but Proxmox reports error | Plugin (Layer 1) | syslog for `truenas-proxmox:` lines | | VM won't start, iSCSI session error | iSCSI/QEMU (Layer 2) | TrueNAS iSCSI service, initiator group ACL | -| Storage shows unavailable, pool listing fails | Proxmox core (Layer 3) | SSH key setup, `pvedaemon` service | -| Kernel errors after disk deletion (v2.x) | iSCSI/Proxmox (Layer 2/3) | `iscsiadm -m session -R` to rescan | +| Storage shows unavailable | Proxmox core (Layer 3) | `pvedaemon` service, storage.cfg | --- diff --git a/docs/architecture.md b/docs/architecture.md index 3a126a6..8ae4088 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -360,16 +360,17 @@ lint → build → security → publish **Job 4: Publish** - Skipped for PRs and branches with `channel=none` -- Cloudsmith `deb` push to the resolved repo +- Cloudsmith `deb` push to the resolved repo (parallel channel, transitional) +- GitHub Pages apt repo update: `.deb` added to `pool/v{major}/`, `Packages.gz` and signed `InRelease` regenerated for the relevant dist tracks, committed to `gh-pages` branch - On tagged releases: creates a draft GitHub Release with the `.deb` attached ### Version String Logic -| Git ref | Debian version string | Channel | Cloudsmith repo | -|---|---|---|---| -| `refs/tags/v3.0.0` | `3.0.0-1` | stable | `truenas-proxmox` | -| `refs/heads/master` or `refs/heads/release/3.x` | `3.0.0~beta+abc1234` | testing | `truenas-proxmox-testing` | -| `refs/heads/release/*` (other) | `3.0.0~alpha+abc1234` | development | `truenas-proxmox-snapshots` | +| Git ref | Debian version string | Channel | Cloudsmith repo | GitHub Pages dist | +|---|---|---|---|---| +| `refs/tags/v3.0.0` | `3.0.0-1` | stable | `truenas-proxmox` | `v3` | +| `refs/heads/master` or `refs/heads/release/3.x` | `3.0.0~beta+abc1234` | testing | `truenas-proxmox-testing` | — | +| `refs/heads/release/*` (other) | `3.0.0~alpha+abc1234` | development | `truenas-proxmox-snapshots` | — | | feature branches, PRs | `3.0.0~dev+abc1234` | none | not published | The tilde (`~`) in the Debian version sorts below the base version in `dpkg`, guaranteeing pre-release builds never auto-upgrade over a stable release. @@ -598,7 +599,8 @@ Major design decisions live in `.claude/cos/adrs/`. Check before making changes |---|---| | ADR-001 | Consolidate build pipeline into this repo; no install-time git clone | | ADR-002 | Full `PVE::Storage::Custom` plugin; no ZFSPlugin.pm or pvemanagerlib.js patches | -| ADR-003 | Transition from Cloudsmith to GitHub Pages apt repo (accepted, not yet implemented) | +| ADR-003 | Superseded by ADR-010 | +| ADR-010 | GitHub Pages apt repo with per-major-version dist tracks (`v3`, `main`/`v2` for backward compat) | | ADR-004 | `eval {}` rollback pattern for all multi-step TrueNAS operations | | ADR-005 | Bearer token (API key) as primary auth; basic auth removed in v3.0 | | ADR-006 | `$VERSION` in `TrueNAS.pm` is the single source of truth for package versioning | diff --git a/docs/getting-started.md b/docs/getting-started.md index f1e35b4..f9dc27e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -77,18 +77,17 @@ Run all of these commands on **each Proxmox node** in your cluster, or on your s ### Step 1 — Import the GPG Signing Key ```bash -curl -fsSL https://dl.cloudsmith.io/public/ksatechnologies/truenas-proxmox/gpg.284C106104A8CE6D.key \ +curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \ | gpg --dearmor \ - | tee /usr/share/keyrings/ksatechnologies-truenas-proxmox-keyring.gpg > /dev/null + | tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null ``` ### Step 2 — Add the Package Repository ```bash -cat > /etc/apt/sources.list.d/ksatechnologies-repo.list << 'EOF' -deb [signed-by=/usr/share/keyrings/ksatechnologies-truenas-proxmox-keyring.gpg] \ - https://dl.cloudsmith.io/public/ksatechnologies/truenas-proxmox/deb/debian any-version main -EOF +echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \ +https://thegrandwazoo.github.io/freenas-proxmox v3 main" \ + | tee /etc/apt/sources.list.d/truenas-proxmox.list ``` ### Step 3 — Install the Package diff --git a/docs/migrating-from-v2.md b/docs/migrating-from-v2.md index f930f59..1ae45db 100644 --- a/docs/migrating-from-v2.md +++ b/docs/migrating-from-v2.md @@ -76,8 +76,15 @@ Before you do anything else, check if any of your VMs have a TPM state disk. QEM Run this on **every node in the cluster** before adding the new storage: ```bash -# Add the Cloudsmith repo (if not already added) -curl -1sLf 'https://dl.cloudsmith.io/public/ksatechnologies/truenas-proxmox/setup.deb.sh' | bash +# Import the GPG key +curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \ + | gpg --dearmor \ + | tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null + +# Add the v3 repository track +echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \ +https://thegrandwazoo.github.io/freenas-proxmox v3 main" \ + | tee /etc/apt/sources.list.d/truenas-proxmox.list # Install apt update && apt install truenas-proxmox