[PATCH qemu-server 2/4] agent: treat freeze-fs-on-backup as alias for guest-fsfreeze

[Thomas Lamprecht <t.lamprecht@proxmox.com>]

Alias the deprecated key to 'guest-fsfreeze' through the JSONSchema
alias key support so consumers see a single, consistent value.
Previously only the backup code path fell back to it, while snapshots,
replications, clones and imports silently ignored it.

Note that while alias support for top-level JSON schema has a bug [0],
the one for property strings - which this here is - works out fine.

[0]: https://lore.proxmox.com/all/20251205100317.1101549-1-d.csapak@proxmox.com/

The key stays in the schema indefinitely for old backup restore
compatibility rather than being removed in a future major release.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/QemuServer/Agent.pm  | 15 ++++++---------
 src/PVE/VZDump/QemuServer.pm |  7 +------
 2 files changed, 7 insertions(+), 15 deletions(-)

diff --git a/src/PVE/QemuServer/Agent.pm b/src/PVE/QemuServer/Agent.pm
index 4bc7cfa1..c0315a03 100644
--- a/src/PVE/QemuServer/Agent.pm
+++ b/src/PVE/QemuServer/Agent.pm
@@ -35,25 +35,21 @@ our $agent_fmt = {
         optional => 1,
         default => 0,
     },
-    # TODO Remove for Proxmox VE 10
     'freeze-fs-on-backup' => {
-        description => "Deprecated: Use 'guest-fsfreeze' instead.\n\n"
-            . "Freeze/thaw guest filesystems on backup for consistency.",
         type => 'boolean',
         optional => 1,
-        default => 1,
+        alias => 'guest-fsfreeze', # keep for old backup restore compatibility
     },
     'guest-fsfreeze' => {
-        description =>
-            "Whether to issue the guest-fsfreeze-freeze and guest-fsfreeze-thaw QEMU guest agent"
-            . " commands.",
+        description => "Freeze guest filesystems through QGA for consistent disk state on"
+            . " operations such as snapshots, backups, replications and clones.",
         verbose_description =>
             "Whether to issue the guest-fsfreeze-freeze and guest-fsfreeze-thaw QEMU guest agent"
             . " commands. Backups in snapshot mode, clones, snapshots without RAM, importing"
             . " disks from a running guest, and replications normally issue a guest-fsfreeze-freeze"
             . " and a respective thaw command when the QEMU Guest agent option is enabled in the"
-            . " guest's configuration and the agent is running inside of the guest.\n\nWhen set, it"
-            . " will take precedence over 'freeze-fs-on-backup'.",
+            . " guest's configuration and the agent is running inside of the guest.\n\nThe deprecated"
+            . " 'freeze-fs-on-backup' setting is treated as an alias for this setting.",
         type => 'boolean',
         optional => 1,
         default => 1,
@@ -77,6 +73,7 @@ sub parse_guest_agent {
 
     # if the agent is disabled ignore the other potentially set properties
     return {} if !$res->{enabled};
+
     return $res;
 }
 
diff --git a/src/PVE/VZDump/QemuServer.pm b/src/PVE/VZDump/QemuServer.pm
index 55fb6dc4..925172f4 100644
--- a/src/PVE/VZDump/QemuServer.pm
+++ b/src/PVE/VZDump/QemuServer.pm
@@ -1102,12 +1102,7 @@ sub qga_fs_freeze {
         return;
     }
 
-    my $freeze = PVE::QemuServer::Agent::get_qga_key($self->{vmlist}->{$vmid}, 'guest-fsfreeze');
-    $freeze //=
-        PVE::QemuServer::Agent::get_qga_key($self->{vmlist}->{$vmid}, 'freeze-fs-on-backup');
-    $freeze //= 1;
-
-    if (!$freeze) {
+    if (!PVE::QemuServer::Agent::should_fs_freeze($self->{vmlist}->{$vmid})) {
         $self->loginfo("skipping guest-agent 'fs-freeze', disabled in VM options");
         return;
     }
-- 
2.47.3