[PATCH qemu-server v2 6/7] agent: fs freeze: harmonize checks for guest fs freeze

Fiona Ebner
2026-04-23T12:41:16Z

Puts the logic inside the agent module, rather than duplicating it in
three different places.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---

Changes in v2:
* Adapt to new should_fs_freeze() function.
* Use subroutine signature.
* Rename guest_fsfreeze_applicable() to guest_fs_freeze_applicable().
* Simplify log function (usage) in guest_fsfreeze_applicable().
* Drop $is_backup argument from guest_fs_freeze_applicable() now that
there is no backup-specific option anymore (is an alias for the
general one).

src/PVE/QemuConfig.pm | 14 ++++++--------
src/PVE/QemuServer/Agent.pm | 31 +++++++++++++++++++++++++++++++
src/PVE/QemuServer/BlockJob.pm | 11 ++---------
src/PVE/VZDump/QemuServer.pm | 20 +++++++-------------
4 files changed, 46 insertions(+), 30 deletions(-)

diff --git a/src/PVE/QemuConfig.pm b/src/PVE/QemuConfig.pm
index eedb34f9..5feae68d 100644
--- a/src/PVE/QemuConfig.pm
+++ b/src/PVE/QemuConfig.pm
@@ -292,17 +292,15 @@ sub __snapshot_check_running {
sub __snapshot_check_freeze_needed {
my ($class, $vmid, $config, $save_vmstate) = @_;

+ my $freeze_needed = 0;
my $running = $class->__snapshot_check_running($vmid);
+
if (!$save_vmstate) {
- return (
- $running,
- $running
- && PVE::QemuServer::Agent::should_fs_freeze($config->{agent})
- && PVE::QemuServer::Agent::qga_check_running($vmid),
- );
- } else {
- return ($running, 0);
+ $freeze_needed =
+ PVE::QemuServer::Agent::guest_fs_freeze_applicable($config->{agent}, $vmid);
}
+
+ return ($running, $freeze_needed);
}

sub __snapshot_freeze {
diff --git a/src/PVE/QemuServer/Agent.pm b/src/PVE/QemuServer/Agent.pm
index e63b09f2..c8cd334f 100644
--- a/src/PVE/QemuServer/Agent.pm
+++ b/src/PVE/QemuServer/Agent.pm
@@ -276,4 +276,35 @@ sub guest_fs_thaw($vmid) {
return;
}

+=head3 guest_fs_freeze_applicable
+
+ if (guest_fs_freeze_applicable($agent_str, $vmid, $logfunc)) {
+ guest_fs_freeze($vmid);
+ }
+
+Check if the file systems of the guest C<$vmid> should be frozen according to the guest agent
+property string C<$agent_str> and if freezing is actionable in practice, i.e. guest agent running.
+Logs a message if skipped. Using a custom log function via C<$logfunc> is supported. Otherwise,
+C<print()> and C<warn()> will be used.
+
+=cut
+
+sub guest_fs_freeze_applicable($agent_str, $vmid, $logfunc = undef) {
+ $logfunc //= sub($msg, $level = 'info') {
+ $level eq 'info' ? print("$msg\n") : warn("$msg\n");
+ };
+
+ if (!should_fs_freeze($agent_str)) {
+ $logfunc->("skipping guest filesystem freeze - disabled in VM options");
+ return;
+ }
+
+ if (!qga_check_running($vmid, 1)) {
+ $logfunc->("skipping guest filesystem freeze - agent configured but not running?");
+ return;
+ }
+
+ return 1;
+}
+
1;
diff --git a/src/PVE/QemuServer/BlockJob.pm b/src/PVE/QemuServer/BlockJob.pm
index 93a1ce60..3fc5af3b 100644
--- a/src/PVE/QemuServer/BlockJob.pm
+++ b/src/PVE/QemuServer/BlockJob.pm
@@ -162,20 +162,13 @@ sub monitor {
last if $completion eq 'skip' || $completion eq 'auto';

if ($vmiddst && $vmiddst != $vmid) {
- my $freeze_enabled = PVE::QemuServer::Agent::should_fs_freeze($qga);
- my $should_fsfreeze = $freeze_enabled && qga_check_running($vmid);
+ my $should_fsfreeze =
+ PVE::QemuServer::Agent::guest_fs_freeze_applicable($qga, $vmid);
if ($should_fsfreeze) {
print "issuing guest agent 'guest-fsfreeze-freeze' command\n";
eval { PVE::QemuServer::Agent::guest_fs_freeze($vmid); };
warn $@ if $@;
} else {
- if (!$freeze_enabled) {
- print "skipping guest-agent 'guest-fsfreeze-freeze', disabled in VM"
- . " options\n";
- } else {
- print "skipping guest agent 'guest-fsfreeze-freeze' command: the"
- . " agent is not running inside of the guest\n";
- }
print "suspend vm\n";
eval { PVE::QemuServer::RunState::vm_suspend($vmid, 1); };
warn $@ if $@;
diff --git a/src/PVE/VZDump/QemuServer.pm b/src/PVE/VZDump/QemuServer.pm
index 9952cff1..86909d28 100644
--- a/src/PVE/VZDump/QemuServer.pm
+++ b/src/PVE/VZDump/QemuServer.pm
@@ -1098,20 +1098,14 @@ sub qga_fs_freeze {
|| !$self->{vm_was_running}
|| $self->{vm_was_paused};

- my $conf = $self->{vmlist}->{$vmid};
+ my $agent_str = $self->{vmlist}->{$vmid}->{agent};

- if (!PVE::QemuServer::Agent::get_qga_key($conf, 'enabled')) {
- $self->loginfo("skipping guest-agent 'fs-freeze', agent not configured in VM options");
- return;
- }
-
- if (!PVE::QemuServer::Agent::qga_check_running($vmid, 1)) {
- $self->loginfo("skipping guest-agent 'fs-freeze', agent configured but not running?");
- return;
- }
-
- if (!PVE::QemuServer::Agent::should_fs_freeze($conf->{agent})) {
- $self->loginfo("skipping guest-agent 'fs-freeze', disabled in VM options");
+ my $logfunc = sub {
+ my ($msg, $level) = @_; # Note that msg and level are swapped intentionally here.
+ $level //= 'info';
+ $self->log($level, $msg);
+ };
+ if (!PVE::QemuServer::Agent::guest_fs_freeze_applicable($agent_str, $vmid, $logfunc)) {
return;
}

--
2.47.3