From 33faf6eb346d16f21a8b4a7849fec84fee2c480a Mon Sep 17 00:00:00 2001 From: Kevin Adams Date: Sat, 23 May 2026 19:55:59 -0400 Subject: [PATCH] =?UTF-8?q?chore:=20v3.0=20packaging=20cleanup=20=E2=80=94?= =?UTF-8?q?=20no=20patches,=20one=20.pm=20file?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename Custom/FreeNAS.pm → Custom/TrueNAS.pm (matches package name) - Rewrite postinst: copy TrueNAS.pm + restart pveproxy (no patch logic) - Rewrite postrm: remove TrueNAS.pm + restart (no restore-orig logic) - Delete triggers: nothing to watch (no ZFSPlugin/pvemanagerlib/apidoc) - Drop 'patch' dep, add 'open-iscsi'; update package description - Delete patch-generation runbook (obsolete) Co-Authored-By: Claude Sonnet 4.6 --- ...-001-generate-patch-for-new-pve-version.md | 70 ------- packaging/DEBIAN/control.j2 | 11 +- packaging/DEBIAN/postinst | 197 ++---------------- packaging/DEBIAN/postrm | 86 +------- packaging/DEBIAN/triggers | 7 - .../Storage/Custom/{FreeNAS.pm => TrueNAS.pm} | 0 6 files changed, 31 insertions(+), 340 deletions(-) delete mode 100644 .claude/cos/runbooks/runbook-001-generate-patch-for-new-pve-version.md delete mode 100644 packaging/DEBIAN/triggers rename perl5/PVE/Storage/Custom/{FreeNAS.pm => TrueNAS.pm} (100%) diff --git a/.claude/cos/runbooks/runbook-001-generate-patch-for-new-pve-version.md b/.claude/cos/runbooks/runbook-001-generate-patch-for-new-pve-version.md deleted file mode 100644 index 09743e8..0000000 --- a/.claude/cos/runbooks/runbook-001-generate-patch-for-new-pve-version.md +++ /dev/null @@ -1,70 +0,0 @@ -# Runbook: Generate a Patch for a New Proxmox VE Version - -When Proxmox VE releases an update that breaks the existing patches, follow these steps. - -## Prerequisites - -- A Proxmox VE node (or VM) running the new version -- SSH access to that node -- The current `FreeNAS.pm` changes you want to apply - -## Steps - -### 1. Copy the original files from the PVE node - -```bash -# On your dev machine -PVE_HOST=your-proxmox-node -PVE_VER=$(ssh root@$PVE_HOST "dpkg-query --showformat='\${Version}' --show pve-manager") - -mkdir -p stable-8/originals - -scp root@$PVE_HOST:/usr/share/perl5/PVE/Storage/ZFSPlugin.pm \ - stable-8/perl5/PVE/Storage/ZFSPlugin.pm.orig - -scp root@$PVE_HOST:/usr/share/pve-manager/js/pvemanagerlib.js \ - stable-8/pve-manager/js/pvemanagerlib.js.orig - -scp root@$PVE_HOST:/usr/share/pve-docs/api-viewer/apidoc.js \ - stable-8/pve-docs/api-viewer/apidoc.js.orig -``` - -### 2. Apply the desired modifications - -Work on copies of the `.orig` files: - -```bash -cp stable-8/perl5/PVE/Storage/ZFSPlugin.pm.orig /tmp/ZFSPlugin.pm -# ... make your changes manually or apply the known modifications ... -``` - -### 3. Generate the patch - -```bash -diff -u stable-8/perl5/PVE/Storage/ZFSPlugin.pm.orig /tmp/ZFSPlugin.pm \ - > stable-8/perl5/PVE/Storage/ZFSPlugin-${PVE_VER}.pm.patch - -# Do the same for the other files -``` - -### 4. Test the patch - -```bash -# On the PVE node or a copy: -patch --dry-run -p0 /usr/share/perl5/PVE/Storage/ZFSPlugin.pm \ - < stable-8/perl5/PVE/Storage/ZFSPlugin-${PVE_VER}.pm.patch -``` - -### 5. Update the postinst version map - -In `packaging/DEBIAN/postinst`, update the version-to-patch-file mapping to include the new PVE version. - -### 6. Update the default `.patch` symlink or file - -The `postinst` selects a patch file based on the installed PVE version. Make sure the new patch is in the version map. - -## Notes - -- The JS files are large (pvemanagerlib.js is several MB); patches are usually small diffs around the iSCSI provider section -- Use `--ignore-whitespace` with patch to handle indentation differences -- Test with `patch --dry-run` before committing diff --git a/packaging/DEBIAN/control.j2 b/packaging/DEBIAN/control.j2 index f63fba0..08bd020 100644 --- a/packaging/DEBIAN/control.j2 +++ b/packaging/DEBIAN/control.j2 @@ -2,14 +2,15 @@ Package: freenas-proxmox Version: ${VERSION} Architecture: all Maintainer: KSA Technologies, LLC -Depends: librest-client-perl, patch +Depends: librest-client-perl, open-iscsi Section: perl Priority: optional Homepage: https://github.com/TheGrandWazoo/freenas-proxmox -Description: TrueNAS ZFS-over-iSCSI Plugin for Proxmox VE - Manages iSCSI LUNs on TrueNAS (CORE and SCALE) via the TrueNAS REST API. - Supports Bearer Token and username/password authentication. - No SSH-based LUN management required. +Description: TrueNAS Custom Storage Plugin for Proxmox VE + Native PVE::Storage::Custom plugin for managing TrueNAS ZFS volumes over iSCSI. + Discovered automatically by Proxmox VE — no patches to PVE system files required. + Supports TrueNAS CORE and SCALE via the TrueNAS REST API with Bearer Token auth. + No SSH keys required. . Licensed under the GNU Affero General Public License v3 (AGPL-3.0). Copyright (c) 2020 KSA Technologies, LLC. diff --git a/packaging/DEBIAN/postinst b/packaging/DEBIAN/postinst index 17d0d81..5eb3c16 100644 --- a/packaging/DEBIAN/postinst +++ b/packaging/DEBIAN/postinst @@ -1,212 +1,43 @@ #!/bin/bash -# postinst: freenas-proxmox install/upgrade/trigger script -# Applies patches to Proxmox VE system files and installs the TrueNAS API plugin. -# No internet access required — all files are bundled in the package. +# postinst: freenas-proxmox v3.x install/upgrade script +# Installs the TrueNAS custom storage plugin for Proxmox VE. +# No patches, no internet access required. set -e -INSTALL_DIR="/usr/share/freenas-proxmox" -LIB_PATH="/usr/share" +PLUGIN_SRC="/usr/share/freenas-proxmox/TrueNAS.pm" +PLUGIN_DST="/usr/share/perl5/PVE/Storage/Custom/TrueNAS.pm" LOG_FILE="/var/log/freenas-proxmox-install.log" -ZFSPLUGIN_PATH="/perl5/PVE/Storage/ZFSPlugin.pm" -PVEMANAGER_PATH="/pve-manager/js/pvemanagerlib.js" -APIDOC_PATH="/pve-docs/api-viewer/apidoc.js" -FREENAS_PM_PATH="/perl5/PVE/Storage/LunCmd/FreeNAS.pm" -REST_CLIENT_PATH="/perl5/REST/Client.pm" - log() { echo "[freenas-proxmox] $*" | tee -a "$LOG_FILE" } -# Detect installed Proxmox VE major version (e.g. "8" from "8.4.19") -detect_pve_major() { - local ver - ver=$(dpkg-query --showformat='${Version}' --show proxmox-ve 2>/dev/null || echo "0") - echo "${ver%%.*}" -} - -# Detect pve-manager major.minor (e.g. "8.4" from "8.4.19"). -# Used to select minor-version-specific patches within a major series. -detect_pve_manager_minor() { - local ver - ver=$(dpkg-query -W -f '${Version}' pve-manager 2>/dev/null || echo "0.0.0") - echo "${ver%.*}" -} - -# Find the best bundled patch for a given component and PVE version. -# Tries {minor}.patch (e.g. 8.4.patch) first, then walks down {major}.patch, -# {major-1}.patch, ... until a match is found. -find_patch() { - local component="$1" - local major="$2" - local minor="$3" # e.g. "8.4" — may be empty - local patch_dir="${INSTALL_DIR}/patches/${component}" - - # Minor-version-specific patch takes priority (e.g. pvemanagerlib/8.4.patch) - if [ -n "$minor" ] && [ -f "${patch_dir}/${minor}.patch" ]; then - echo "${patch_dir}/${minor}.patch" - return 0 - fi - - # Fall back to major-version patch, walking down until one is found - local ver="$major" - while [ "$ver" -ge 5 ]; do - if [ -f "${patch_dir}/${ver}.patch" ]; then - echo "${patch_dir}/${ver}.patch" - return 0 - fi - ver=$(( ver - 1 )) - done - - log "WARNING: No bundled patch found for ${component} on Proxmox VE ${major}.x" - return 1 -} - -# Apply a patch to a target file idempotently. -# Creates a .orig backup (via patch --backup) on first application. -apply_patch() { - local target_rel="$1" - local patch_file="$2" - local label="$3" - local target="${LIB_PATH}${target_rel}" - - [ -f "$target" ] || { log "ERROR: Target not found: ${target}"; return 1; } - [ -f "$patch_file" ] || { log "Skipping ${label}: patch file missing"; return 0; } - - if grep -q "freenas" "$target" 2>/dev/null; then - log "${label} is already patched — skipping" - return 0 - fi - - log "Patching ${target} ..." - if patch --backup --ignore-whitespace "$target" < "$patch_file" >> "$LOG_FILE" 2>&1; then - log "${label} patched successfully" - else - log "ERROR: Failed to patch ${label} — see ${LOG_FILE} for details" - return 1 - fi -} - -install_files() { - log "Installing ${LIB_PATH}${FREENAS_PM_PATH}" - mkdir -p "$(dirname "${LIB_PATH}${FREENAS_PM_PATH}")" - cp "${INSTALL_DIR}/FreeNAS.pm" "${LIB_PATH}${FREENAS_PM_PATH}" - - log "Installing ${LIB_PATH}${REST_CLIENT_PATH}" - mkdir -p "$(dirname "${LIB_PATH}${REST_CLIENT_PATH}")" - cp "${INSTALL_DIR}/REST-Client.pm" "${LIB_PATH}${REST_CLIENT_PATH}" +install_plugin() { + log "Installing ${PLUGIN_DST}" + mkdir -p "$(dirname "$PLUGIN_DST")" + cp "$PLUGIN_SRC" "$PLUGIN_DST" + log "Plugin installed" } restart_pve_services() { log "Restarting Proxmox VE services ..." - pvedaemon restart && log "pvedaemon restarted" - pveproxy restart && log "pveproxy restarted" - pvestatd restart && log "pvestatd restarted" - systemctl restart pvescheduler.service && log "pvescheduler restarted" + pvedaemon restart && log "pvedaemon restarted" + pveproxy restart && log "pveproxy restarted" log "Done. Refresh your Proxmox browser tab to load the updated UI." } -# Warn the user if their PVE version is outside the supported range for this -# plugin version. Exits non-zero (aborting the install) only for versions so -# old that no patches exist (< 7). -check_pve_version() { - local major="$1" - - if [ "$major" -lt 7 ]; then - log "ERROR: Proxmox VE ${major}.x is not supported by this plugin." - log " PVE 5 and 6 reached end-of-life in 2019 and 2022 respectively." - log " Please upgrade your Proxmox VE installation before installing this plugin." - exit 1 - fi - - if [ "$major" -eq 7 ]; then - log "WARNING: *** Proxmox VE 7 — Important Notice ***" - log "WARNING: v2.x is the LAST release series that supports Proxmox VE 7." - log "WARNING: PVE 7 support is best-effort only; no new patches will be" - log "WARNING: developed for it." - log "WARNING: When v3.0 is released, DO NOT upgrade to it — v3.0 requires" - log "WARNING: Proxmox VE 8 or later. Stay on the latest v2.x release." - fi - - if [ "$major" -eq 8 ]; then - log "INFO: Proxmox VE 8 reaches end-of-life on 2026-08-31." - log "INFO: Plan your upgrade to PVE 9 and migration to v3.0 before that date." - fi - - if [ "$major" -ge 9 ]; then - log "WARNING: *** Proxmox VE ${major}.x — Not Supported by v2.x ***" - log "WARNING: This plugin (v2.x) is not supported on Proxmox VE 9 or later." - log "WARNING: Patches may fail to apply or the UI may not work correctly." - log "WARNING: Please use v3.0 of this plugin, which is designed for PVE 9+." - log "WARNING: See: https://github.com/TheGrandWazoo/freenas-proxmox/releases" - log "WARNING: Continuing anyway — but expect problems." - fi -} - -# ── Entry point ────────────────────────────────────────────────────────────── - -major=$(detect_pve_major) -pve_mgr_minor=$(detect_pve_manager_minor) -log "Proxmox VE major version: ${major}, pve-manager: ${pve_mgr_minor}" -check_pve_version "$major" - case "$1" in - - triggered) - # dpkg fired us because one of the watched PVE files was updated. - log "Triggered by package update — re-applying patches for: $2" - - for fullpath in $2; do - filename=$(basename "$fullpath") - filename="${filename%.*}" # strip extension - case "$filename" in - ZFSPlugin) - patch_file=$(find_patch "ZFSPlugin" "$major" "$pve_mgr_minor" || true) - apply_patch "$ZFSPLUGIN_PATH" "$patch_file" "ZFSPlugin.pm" - ;; - pvemanagerlib) - patch_file=$(find_patch "pvemanagerlib" "$major" "$pve_mgr_minor" || true) - apply_patch "$PVEMANAGER_PATH" "$patch_file" "pvemanagerlib.js" - ;; - apidoc) - patch_file=$(find_patch "apidoc" "$major" "$pve_mgr_minor" || true) - apply_patch "$APIDOC_PATH" "$patch_file" "apidoc.js" - ;; - esac - done - - install_files - exit 0 - ;; - configure) log "Configuring freenas-proxmox (previous version: ${2:-none})" - CHANGED="no" - - patch_file=$(find_patch "ZFSPlugin" "$major" "$pve_mgr_minor" || true) - apply_patch "$ZFSPLUGIN_PATH" "$patch_file" "ZFSPlugin.pm" && CHANGED="yes" - - patch_file=$(find_patch "pvemanagerlib" "$major" "$pve_mgr_minor" || true) - apply_patch "$PVEMANAGER_PATH" "$patch_file" "pvemanagerlib.js" && CHANGED="yes" - - patch_file=$(find_patch "apidoc" "$major" "$pve_mgr_minor" || true) - apply_patch "$APIDOC_PATH" "$patch_file" "apidoc.js" && CHANGED="yes" - - install_files - CHANGED="yes" - - [ "$CHANGED" = "yes" ] && restart_pve_services - exit 0 + install_plugin + restart_pve_services ;; - abort-upgrade|abort-remove|abort-deconfigure) ;; - *) echo "$0: called with unknown argument '$1'" >&2 exit 0 ;; - esac exit 0 diff --git a/packaging/DEBIAN/postrm b/packaging/DEBIAN/postrm index f48c9d2..c0a2e1c 100644 --- a/packaging/DEBIAN/postrm +++ b/packaging/DEBIAN/postrm @@ -1,104 +1,40 @@ #!/bin/bash -# postrm: freenas-proxmox removal script -# Reverses patches applied to Proxmox VE system files and removes installed plugin files. +# postrm: freenas-proxmox v3.x removal script +# Removes the TrueNAS custom storage plugin for Proxmox VE. set -e -LIB_PATH="/usr/share" +PLUGIN_DST="/usr/share/perl5/PVE/Storage/Custom/TrueNAS.pm" LOG_FILE="/var/log/freenas-proxmox-install.log" -ZFSPLUGIN_PATH="/perl5/PVE/Storage/ZFSPlugin.pm" -PVEMANAGER_PATH="/pve-manager/js/pvemanagerlib.js" -APIDOC_PATH="/pve-docs/api-viewer/apidoc.js" -FREENAS_PM_PATH="/perl5/PVE/Storage/LunCmd/FreeNAS.pm" -INSTALL_DIR="/usr/share/freenas-proxmox" - log() { echo "[freenas-proxmox] $*" | tee -a "$LOG_FILE" } -# Restore a file from the .orig backup that patch --backup created. -restore_orig() { - local target_rel="$1" - local label="$2" - local target="${LIB_PATH}${target_rel}" - local orig="${target}.orig" - - if ! grep -q "freenas" "$target" 2>/dev/null; then - log "${label} does not appear to be patched — skipping restore" - return 0 - fi - - if [ -f "$orig" ]; then - log "Restoring ${label} from .orig backup" - cp "$orig" "$target" && rm -f "$orig" - log "${label} restored" - else - log "WARNING: No .orig backup found for ${label} — Proxmox VE reinstall may be needed" - log " Run: apt install --reinstall pve-manager libpve-storage-perl pve-docs" - fi -} - -remove_plugin_files() { - if [ -f "${LIB_PATH}${FREENAS_PM_PATH}" ]; then - log "Removing ${LIB_PATH}${FREENAS_PM_PATH}" - rm -f "${LIB_PATH}${FREENAS_PM_PATH}" - fi - # REST/Client.pm is owned by librest-client-perl; do not remove it here. -} - restart_pve_services() { log "Restarting Proxmox VE services ..." - pvedaemon restart && log "pvedaemon restarted" - pveproxy restart && log "pveproxy restarted" - pvestatd restart && log "pvestatd restarted" - systemctl restart pvescheduler.service && log "pvescheduler restarted" + pvedaemon restart && log "pvedaemon restarted" + pveproxy restart && log "pveproxy restarted" } -# ── Entry point ────────────────────────────────────────────────────────────── - case "$1" in - remove) - log "Removing freenas-proxmox — restoring Proxmox VE files ..." - - restore_orig "$ZFSPLUGIN_PATH" "ZFSPlugin.pm" - restore_orig "$PVEMANAGER_PATH" "pvemanagerlib.js" - restore_orig "$APIDOC_PATH" "apidoc.js" - remove_plugin_files + log "Removing freenas-proxmox ..." + rm -f "$PLUGIN_DST" + log "Plugin removed" restart_pve_services - log "freenas-proxmox removed. Refresh your Proxmox browser tab." - exit 0 ;; - - upgrade) - # On upgrade the new package's postinst will re-apply everything. - # Just restore the originals cleanly so the new patch applies to a fresh file. - log "Preparing for upgrade — restoring unpatched Proxmox VE files ..." - - restore_orig "$ZFSPLUGIN_PATH" "ZFSPlugin.pm" - restore_orig "$PVEMANAGER_PATH" "pvemanagerlib.js" - restore_orig "$APIDOC_PATH" "apidoc.js" - remove_plugin_files - - exit 0 - ;; - purge) log "Purging freenas-proxmox ..." - rm -rf "$INSTALL_DIR" - rm -f "$LOG_FILE" - exit 0 + rm -f "$PLUGIN_DST" + rm -f "$LOG_FILE" ;; - - failed-upgrade|disappear|abort-upgrade|abort-remove|abort-deconfigure) + upgrade|failed-upgrade|disappear|abort-upgrade|abort-remove|abort-deconfigure) ;; - *) echo "$0: called with unknown argument '$1'" >&2 exit 0 ;; - esac exit 0 diff --git a/packaging/DEBIAN/triggers b/packaging/DEBIAN/triggers deleted file mode 100644 index 7d09e90..0000000 --- a/packaging/DEBIAN/triggers +++ /dev/null @@ -1,7 +0,0 @@ -# dpkg trigger file for freenas-proxmox -# -# When Proxmox VE updates replace any of these three files, dpkg automatically -# re-fires the postinst script so patches are re-applied without manual action. -interest /usr/share/perl5/PVE/Storage/ZFSPlugin.pm -interest /usr/share/pve-manager/js/pvemanagerlib.js -interest /usr/share/pve-docs/api-viewer/apidoc.js diff --git a/perl5/PVE/Storage/Custom/FreeNAS.pm b/perl5/PVE/Storage/Custom/TrueNAS.pm similarity index 100% rename from perl5/PVE/Storage/Custom/FreeNAS.pm rename to perl5/PVE/Storage/Custom/TrueNAS.pm