truenas/truenas-proxmox-plugin v2.1.23-beta8

on GitHub

Runtime plugin fixes

• fix(#88): path() fast-fail + deterministic by-path fallback.
  PVE's destroy_vm → foreach_volume_full closure at
  QemuServer.pm:1839 calls path() → remove_owned_drive → vdisk_free → free_image; when path() died, the closure exited
  before free_image ran and TrueNAS state leaked (zvol, iSCSI
  extent, and target-extent mapping stayed behind forever). The old
  path() called _device_for_lun with the default 600-retry
  budget (60 s), longer than the destroy hold, so any node that
  never activated the disk locally (cross-node destroy of an
  orphan, destroy after a leaked config-migrate, or destroy on a
  node whose iSCSI session was down) aborted destroy_vm before
  free_image ran. Now: retries=5 (500 ms) at the path() call
  site, deterministic /dev/disk/by-path/ip-<portal>-iscsi-<iqn>-lun-<N>
  string fallback for callers that don't need a live device, and die
  only if LUN + portal + IQN are all missing. Verified with a
  two-scenario timing test: same-node destroy 11.5 s, cross-node
  destroy with iSCSI session logged out on destroying node 15.6 s;
  TN state cleaned in both. Pre-fix the cross-node case hung ~60 s
  and leaked. Closes #88.

• fix: iSCSI extent blocksize=4096 pblocksize=true to satisfy
  the QEMU 10.1 alignment check. QEMU 10.1's stricter permission
  / alignment negotiation refuses to attach a scsi-hd whose
  backing image reports the mismatch shape that TrueNAS's default
  extent config produces: logical_block_size=512 alongside
  physical_block_size=16384 (inferred from the zvol's 16K
  volblocksize). qm start on any iSCSI-backed disk dies with:
  kvm: -device scsi-hd,...,write-cache=on: Cannot get 'write' permission without 'resize': Image size is not a multiple of request alignment. Now every iscsi.extent.create payload
  (_tn_extent_create, _alloc_image_iscsi, _clone_image_iscsi)
  sends blocksize=4096 and pblocksize=true, so TN reports
  lbs=4096 pbs=4096 to the initiator and QEMU's check passes.
  Existing extents are unchanged; older VMs that already fail to
  start under QEMU 10.1 need their extents updated in place
  (midclt call iscsi.extent.update <id> '{"blocksize": 4096, "pblocksize": true}') or refreshed via a clone. Verified: 2G
  / 3G / 4G disks previously refused by qm start now start on
  the same QEMU/PVE combination.

Install.sh fixes (closes #118, #119)

• install.sh scfg field names. The installer's embedded Perl
  tn_api_call / tn_api_call_write / execute_provisioning
  helpers now build their scfg hash with the current tn_*
  field names (tn_api_host, tn_api_key, tn_api_insecure,
  tn_api_port, tn_dataset, tn_target_iqn,
  tn_discovery_portal). Prior installers used the pre-2.1.19
  legacy keys and failed every API-key probe even with a valid
  key. Closes #118.

• install.sh pre-release version pattern. The release-tag
  validator now accepts [-~](alpha|beta|rc)[0-9] as a
  pre-release suffix. The old vX.Y.Z / vX.Y.Z-debN
  regex rejected every beta we've shipped. Closes #119.

Docs

• docs(#117): README.md and wiki/Installation.md walk through
  Base Name, Portal, and Target group bindings in order (verify
  Base Name under Target Global Configuration; create/verify
  Portal with ID; create Target with Portal Group ID + Initiator
  Group ID bindings and Authentication Method set explicitly).
  Callout: without those group bindings the target exists but is
  not exposed on the network, and iscsiadm --mode discovery
  from Proxmox returns empty — the exact failure mode from
  issue #117. Refs #117.

• docs(#120): The temporary /alpha/install.sh redirect on
  main (September 18 workaround for #118 + #119) has been
  flipped back to /main/install.sh now that main carries the
  fixed installer. Closes #120.

Verification

Live on the 3-node PVE cluster (pve / proxmox2 / pvevm1,
PVE 10.x, TrueNAS SCALE):

• Regression sweep: 16 assertions OK on core lifecycle (create,
  resize, native snapshot, delsnapshot with TN cascade, VM
  start/stop, full clone, template, linked clone, pvesm list,
  pvesm status, destroy with TN cleanup).
• Two-scenario #88 destroy-cascade timing test: 4/4 OK, same-node
  11.5 s and cross-node-with-iSCSI-down 15.6 s; TN state cleaned
  in both.
• PBS backup+restore roundtrip on a fresh 1 GiB LUN: marker
  survived write → vzdump → qmrestore → read; backup at
  pbs:backup/vm/9970/2026-09-30T22:16:04Z visible on all three
  cluster nodes.

Closed

Closes #88, #117, #118, #119, #120.