* [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA
@ 2026-11-17 12:39 Jakob Klocker
2026-11-17 12:39 ` [PATCH pve-guest-common v7 1/3] AbstractConfig: allow passing options to snapshot_rollback Jakob Klocker
` (3 more replies)
0 siblings, 4 replies; 7+ messages in thread
From: Jakob Klocker @ 2026-11-17 12:39 UTC (permalink / raw)
To: pve-devel
This series adds a new agent option 'sync-time-on-resume' to
automatically synchronize the guest clock via the QEMU Guest Agent
after operations that can leave the guest time stale. The option is
disabled by default and only takes effect when the QEMU Guest Agent is
enabled.
When a VM resumes with a restored RAM state (waking from hibernation or
rolling back to a snapshot that includes RAM), the guest clock
continues from the point the state was saved and no longer matches
wall-clock time. Skew also appears whenever the guest is briefly
frozen and resumed - after creating a snapshot, an
ordinary pause/resume, the resume step of a live migration, or a
vzdump in suspend mode.
When enabled, the option triggers a guest-set-time call:
* after resuming from hibernation (suspend-to-disk)
* after rolling back to a snapshot that includes RAM
* after a live migration
* after an ordinary pause/resume
* after taking a snapshot
* after a vzdump backup in suspend mode
The start, resume and rollback API endpoints also accept a
'sync-time-on-resume' parameter that overrides the configured value for
a single operation.
The option can also be toggled per VM in the GUI.
Changes since v6 (thanks @Fiona):
* rebased on current master
* rollback with RAM: check whether the agent is enabled against the
restored config, only carry over the pre-rollback sync preference
* api: clarify that the start parameter only applies to hibernated VMs,
fix the resume endpoint descriptions, drop redundant sentence from
the short descriptions, rewrap verbose descriptions to 100 columns
* ui: reword the checkbox label to list the triggering operations
* migration: use a regular if block for the sync log message and
clarify that it only reports the request
* vm_resume: check the 'prelaunch' and 'shutdown' states explicitly
* vm_start_nolock: drop stray '1' in eval
* guest-common: rename $opts to $vm_start_opts
* POD fixes, sort imports
Changes since v5:
* drop the migration version check (covered by the strict config check
series and the same-version cluster requirement)
* vzdump: sync the guest clock after resuming from a suspend mode backup;
snapshot mode doesn't pause the vCPUs and stop mode boots the guest
fresh, so neither needs a sync
* vm_resume: skip the sync when resuming from 'prelaunch' (e.g. a VM
started paused for a backup) or after a reset, the guest boots fresh in
both cases
* guest_set_time: return whether the time was actually set
* rebased on current master
Changes since v4:
* rebased on current master
* no functional changes
Link: https://bugzilla.proxmox.com/show_bug.cgi?id=5032
pve-guest-common:
Jakob Klocker (1):
AbstractConfig: allow passing options to snapshot_rollback
src/PVE/AbstractConfig.pm | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
pve-manager:
Jakob Klocker (1):
fix #5032: ui: qemu agent: add sync-time-on-resume option
www/manager6/form/AgentFeatureSelector.js | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
qemu-server:
Jakob Klocker (1):
fix #5032: agent: sync guest time via QGA when the clock falls behind
src/PVE/API2/Qemu.pm | 74 ++++++++++++++++++++++++++++++++--
src/PVE/CLI/qm.pm | 2 +-
src/PVE/QemuConfig.pm | 14 ++++++-
src/PVE/QemuMigrate.pm | 6 +++
src/PVE/QemuServer.pm | 17 +++++++-
src/PVE/QemuServer/Agent.pm | 63 +++++++++++++++++++++++++++++
src/PVE/QemuServer/RunState.pm | 16 +++++++-
src/PVE/VZDump/QemuServer.pm | 25 +++++++++++-
8 files changed, 207 insertions(+), 10 deletions(-)
Summary over all repositories:
10 files changed, 229 insertions(+), 12 deletions(-)
--
Generated by murpp 0.12.0
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH pve-guest-common v7 1/3] AbstractConfig: allow passing options to snapshot_rollback
2026-11-17 12:39 [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA Jakob Klocker
@ 2026-11-17 12:39 ` Jakob Klocker
2026-11-17 12:39 ` [PATCH pve-manager v7 2/3] fix #5032: ui: qemu agent: add sync-time-on-resume option Jakob Klocker
` (2 subsequent siblings)
3 siblings, 0 replies; 7+ messages in thread
From: Jakob Klocker @ 2026-11-17 12:39 UTC (permalink / raw)
To: pve-devel
Thread an optional $vm_start_opts hashref through snapshot_rollback to
__snapshot_rollback_vm_start, so callers can pass per-rollback options
down to the VM start. Used by qemu-server to let the API override the
guest time sync for a single rollback; other options can be added
without further signature changes.
Signed-off-by: Jakob Klocker <j.klocker@proxmox.com>
---
src/PVE/AbstractConfig.pm | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/src/PVE/AbstractConfig.pm b/src/PVE/AbstractConfig.pm
index 7bcae19..c035f04 100644
--- a/src/PVE/AbstractConfig.pm
+++ b/src/PVE/AbstractConfig.pm
@@ -1125,7 +1125,8 @@ my $rollback_remove_replication_snapshots = sub {
# Rolls back to a given snapshot.
sub snapshot_rollback {
- my ($class, $vmid, $snapname) = @_;
+ my ($class, $vmid, $snapname, $vm_start_opts) = @_;
+ $vm_start_opts //= {};
my $prepare = 1;
@@ -1197,7 +1198,8 @@ sub snapshot_rollback {
$class->write_config($vmid, $conf);
if (!$prepare && $snap->{vmstate}) {
- $class->__snapshot_rollback_vm_start($vmid, $snap->{vmstate}, $data);
+ $class->__snapshot_rollback_vm_start($vmid, $snap->{vmstate}, $data,
+ $vm_start_opts);
}
};
--
2.47.3
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH pve-manager v7 2/3] fix #5032: ui: qemu agent: add sync-time-on-resume option
2026-11-17 12:39 [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA Jakob Klocker
2026-11-17 12:39 ` [PATCH pve-guest-common v7 1/3] AbstractConfig: allow passing options to snapshot_rollback Jakob Klocker
@ 2026-11-17 12:39 ` Jakob Klocker
2026-11-17 12:39 ` [PATCH qemu-server v7 3/3] fix #5032: agent: sync guest time via QGA when the clock falls behind Jakob Klocker
2026-11-18 14:22 ` applied: [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA Thomas Lamprecht
3 siblings, 0 replies; 7+ messages in thread
From: Jakob Klocker @ 2026-11-17 12:39 UTC (permalink / raw)
To: pve-devel
Expose the new agent configuration option `sync-time-on-resume`
in the VM configuration GUI.
This allows enabling/disabling automatic guest clock
synchronization after clock-stalling operations.
Signed-off-by: Jakob Klocker <j.klocker@proxmox.com>
---
www/manager6/form/AgentFeatureSelector.js | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/www/manager6/form/AgentFeatureSelector.js b/www/manager6/form/AgentFeatureSelector.js
index 3cae4194..d1377f71 100644
--- a/www/manager6/form/AgentFeatureSelector.js
+++ b/www/manager6/form/AgentFeatureSelector.js
@@ -45,6 +45,20 @@ Ext.define('PVE.form.AgentFeatureSelector', {
hidden: '{freeze_fs.checked}',
},
},
+ {
+ xtype: 'proxmoxcheckbox',
+ boxLabel: gettext(
+ 'Synchronize guest clock after resume, snapshot, rollback or migration',
+ ),
+ name: 'sync-time-on-resume',
+ reference: 'sync_time_on_resume',
+ bind: {
+ disabled: '{!enabled.checked}',
+ },
+ disabled: true,
+ uncheckedValue: '0',
+ defaultValue: '0',
+ },
{
xtype: 'displayfield',
userCls: 'pmx-hint',
@@ -75,6 +89,10 @@ Ext.define('PVE.form.AgentFeatureSelector', {
delete values['freeze-fs'];
}
+ if (!PVE.Parser.parseBoolean(values['sync-time-on-resume'])) {
+ delete values['sync-time-on-resume'];
+ }
+
const agentstr = PVE.Parser.printPropertyString(values, 'enabled');
return { agent: agentstr };
},
--
2.47.3
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH qemu-server v7 3/3] fix #5032: agent: sync guest time via QGA when the clock falls behind
2026-11-17 12:39 [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA Jakob Klocker
2026-11-17 12:39 ` [PATCH pve-guest-common v7 1/3] AbstractConfig: allow passing options to snapshot_rollback Jakob Klocker
2026-11-17 12:39 ` [PATCH pve-manager v7 2/3] fix #5032: ui: qemu agent: add sync-time-on-resume option Jakob Klocker
@ 2026-11-17 12:39 ` Jakob Klocker
2026-11-18 14:22 ` applied: [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA Thomas Lamprecht
3 siblings, 0 replies; 7+ messages in thread
From: Jakob Klocker @ 2026-11-17 12:39 UTC (permalink / raw)
To: pve-devel
Add a 'sync-time-on-resume' agent config property (default off) that,
when enabled, issues the guest-set-time QGA command to set the guest
clock to the host's current time after operations that leave the clock
behind:
- resuming from hibernation (suspend-to-disk)
- resuming from pause/suspend
- rolling back to a snapshot that includes RAM
- live migration
- taking a snapshot, during which the guest is briefly frozen
- vzdump backup in suspend mode
The start, resume and rollback API endpoints gain a
'sync-time-on-resume' parameter (e.g. 'qm start <vmid>
--sync-time-on-resume 0') that overrides the configured agent value for
a single operation, forcing the sync on or off regardless of config.
guest_set_time prints a confirmation line to stdout on success. During
live migration the resume step runs over the migration tunnel, which
also uses stdout, so an unconditional print corrupts the tunnel
protocol. vm_resume therefore takes a 'quiet' parameter to suppress the
print on the migration path; the migration code logs that a sync was
requested instead.
For vzdump, only suspend mode needs a sync: snapshot mode never pauses
the vCPUs, and in stop mode the guest boots fresh. For the same reason,
vm_resume skips the sync when resuming from 'prelaunch' (e.g. a VM
started paused for a backup) or after a reset of a VM that shut down
during a backup.
For a rollback to a snapshot with RAM, whether the agent is enabled is
taken from the restored snapshot config, since that determines whether
the restored VM has a guest agent device. The sync preference itself is
taken from the config before the rollback, as the snapshot may have
been taken before the option was enabled. If the agent was disabled
before the rollback, the snapshot's preference is used instead. An
explicit API parameter takes precedence over both.
Signed-off-by: Jakob Klocker <j.klocker@proxmox.com>
---
src/PVE/API2/Qemu.pm | 74 ++++++++++++++++++++++++++++++++--
src/PVE/CLI/qm.pm | 2 +-
src/PVE/QemuConfig.pm | 14 ++++++-
src/PVE/QemuMigrate.pm | 6 +++
src/PVE/QemuServer.pm | 17 +++++++-
src/PVE/QemuServer/Agent.pm | 63 +++++++++++++++++++++++++++++
src/PVE/QemuServer/RunState.pm | 16 +++++++-
src/PVE/VZDump/QemuServer.pm | 25 +++++++++++-
8 files changed, 207 insertions(+), 10 deletions(-)
diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
index 6d67c5f0..cc768a66 100644
--- a/src/PVE/API2/Qemu.pm
+++ b/src/PVE/API2/Qemu.pm
@@ -3607,6 +3607,24 @@ __PACKAGE__->register_method({
description => 'Whether to migrate conntrack entries for running VMs.',
},
'nets-host-mtu' => get_standard_option('pve-qm-nets-host-mtu'),
+ 'sync-time-on-resume' => {
+ type => 'boolean',
+ description =>
+ "Override the 'sync-time-on-resume' setting from the VM's guest agent (QGA)"
+ . " config for this start only. Controls whether the guest's clock is"
+ . " synchronized when starting a hibernated VM. No effect on a regular start.",
+ verbose_description =>
+ "Override the 'sync-time-on-resume' setting from the VM's guest agent (QGA)"
+ . " config for this start only. When enabled, the 'guest-set-time' QEMU guest"
+ . " agent command is issued to synchronize the guest's clock to the host's"
+ . " current time after the RAM state is restored, which happens here when"
+ . " starting a VM that was hibernated (suspended to disk). Without"
+ . " synchronization the guest's clock may still reflect the time from when the"
+ . " VM was hibernated. The time is only synchronized when the QEMU Guest Agent"
+ . " option is enabled in the guest's configuration and the agent is running"
+ . " inside of the guest.",
+ optional => 1,
+ },
},
},
returns => {
@@ -3622,6 +3640,7 @@ __PACKAGE__->register_method({
my $vmid = extract_param($param, 'vmid');
my $timeout = extract_param($param, 'timeout');
my $machine = extract_param($param, 'machine');
+ my $sync_time = extract_param($param, 'sync-time-on-resume');
my $get_root_param = sub {
my $value = extract_param($param, $_[0]);
@@ -3728,6 +3747,7 @@ __PACKAGE__->register_method({
timeout => $timeout,
forcecpu => $force_cpu,
'nets-host-mtu' => $nets_host_mtu,
+ 'sync-time-on-resume' => $sync_time,
};
PVE::QemuServer::vm_start($storecfg, $vmid, $params, $migrate_opts);
@@ -4212,6 +4232,23 @@ __PACKAGE__->register_method({
description => "Do not check whether the VM is running, used"
. " internally during migration. Only root may use this option.",
},
+ 'sync-time-on-resume' => {
+ type => 'boolean',
+ description =>
+ "Override the 'sync-time-on-resume' setting from the VM's guest agent (QGA)"
+ . " config for this resume only. Controls whether the guest's clock is"
+ . " synchronized after resuming the VM.",
+ verbose_description =>
+ "Override the 'sync-time-on-resume' setting from the VM's guest agent (QGA)"
+ . " config for this resume only. When enabled, the 'guest-set-time' QEMU guest"
+ . " agent command is issued to synchronize the guest's clock to the host's"
+ . " current time after resuming the VM from a paused or hibernated state."
+ . " Without synchronization the guest's clock may still reflect the time from"
+ . " when the VM was paused or hibernated. The time is only synchronized when"
+ . " the QEMU Guest Agent option is enabled in the guest's configuration and"
+ . " the agent is running inside of the guest.",
+ optional => 1,
+ },
},
},
returns => {
@@ -4228,6 +4265,8 @@ __PACKAGE__->register_method({
my $vmid = extract_param($param, 'vmid');
+ my $sync_time = extract_param($param, 'sync-time-on-resume');
+
my $skiplock = extract_param($param, 'skiplock');
raise_param_exc({ skiplock => "Only root may use this option." })
if $skiplock && $authuser ne 'root@pam';
@@ -4258,10 +4297,14 @@ __PACKAGE__->register_method({
syslog('info', "resume VM $vmid: $upid\n");
if (!$to_disk_suspended) {
- PVE::QemuServer::RunState::vm_resume($vmid, $skiplock, $nocheck);
+ PVE::QemuServer::RunState::vm_resume($vmid, $skiplock, $nocheck, $sync_time);
} else {
my $storecfg = PVE::Storage::config();
- PVE::QemuServer::vm_start($storecfg, $vmid, { skiplock => $skiplock });
+ PVE::QemuServer::vm_start(
+ $storecfg,
+ $vmid,
+ { skiplock => $skiplock, 'sync-time-on-resume' => $sync_time },
+ );
}
return;
@@ -6474,6 +6517,23 @@ __PACKAGE__->register_method({
optional => 1,
default => 0,
},
+ 'sync-time-on-resume' => {
+ type => 'boolean',
+ description =>
+ "Override the 'sync-time-on-resume' setting from the VM's guest agent (QGA)"
+ . " config for this rollback only. Controls whether the guest's clock is"
+ . " synchronized after the RAM state is restored.",
+ verbose_description =>
+ "Override the 'sync-time-on-resume' setting from the VM's guest agent (QGA)"
+ . " config for this rollback only. When enabled, the 'guest-set-time' QEMU"
+ . " guest agent command is issued to synchronize the guest's clock to the"
+ . " host's current time after rolling back to a snapshot that includes RAM."
+ . " Without synchronization the guest's clock may still reflect the time from"
+ . " when the snapshot was taken. The time is only synchronized when the QEMU"
+ . " Guest Agent option is enabled in the guest's configuration and the agent"
+ . " is running inside of the guest.",
+ optional => 1,
+ },
},
},
returns => {
@@ -6493,6 +6553,8 @@ __PACKAGE__->register_method({
my $snapname = extract_param($param, 'snapname');
+ my $sync_time = extract_param($param, 'sync-time-on-resume');
+
my $conf = PVE::QemuConfig->load_config($vmid);
my $snap = $conf->{snapshots}->{$snapname};
die "snapshot '$snapname' does not exist\n" if !defined($snap);
@@ -6510,7 +6572,11 @@ __PACKAGE__->register_method({
my $realcmd = sub {
PVE::Cluster::log_msg('info', $authuser, "rollback snapshot VM $vmid: $snapname");
- PVE::QemuConfig->snapshot_rollback($vmid, $snapname);
+ PVE::QemuConfig->snapshot_rollback(
+ $vmid,
+ $snapname,
+ { 'sync-time-on-resume' => $sync_time },
+ );
if ($param->{start} && !PVE::QemuServer::Helpers::vm_running_locally($vmid)) {
PVE::API2::Qemu->vm_start({ vmid => $vmid, node => $node });
@@ -7166,7 +7232,7 @@ __PACKAGE__->register_method({
},
'resume' => sub {
if (PVE::QemuServer::Helpers::vm_running_locally($state->{vmid})) {
- PVE::QemuServer::RunState::vm_resume($state->{vmid}, 1, 1);
+ PVE::QemuServer::RunState::vm_resume($state->{vmid}, 1, 1, undef, 1);
} else {
die "VM $state->{vmid} not running\n";
}
diff --git a/src/PVE/CLI/qm.pm b/src/PVE/CLI/qm.pm
index c8b352d6..c69559a1 100755
--- a/src/PVE/CLI/qm.pm
+++ b/src/PVE/CLI/qm.pm
@@ -474,7 +474,7 @@ __PACKAGE__->register_method({
if (PVE::QemuServer::Helpers::vm_running_locally($vmid)) {
# vm_resume with nocheck, since local node might not have processed config
# move/rename yet
- eval { PVE::QemuServer::RunState::vm_resume($vmid, 1, 1); };
+ eval { PVE::QemuServer::RunState::vm_resume($vmid, 1, 1, undef, 1); };
if ($@) {
$tunnel_write->("ERR: resume failed - $@");
} else {
diff --git a/src/PVE/QemuConfig.pm b/src/PVE/QemuConfig.pm
index d89a62e6..cc8b8250 100644
--- a/src/PVE/QemuConfig.pm
+++ b/src/PVE/QemuConfig.pm
@@ -401,6 +401,11 @@ sub __snapshot_create_vol_snapshots_hook {
next;
}
}
+ my $conf = $class->load_config($vmid);
+ if (PVE::QemuServer::Agent::should_sync_time_on_resume($conf->{agent})) {
+ eval { PVE::QemuServer::Agent::guest_set_time($vmid); };
+ warn "could not sync guest time after snapshot - $@" if $@;
+ }
}
}
}
@@ -486,6 +491,11 @@ sub __snapshot_rollback_hook {
if ($prepare) {
# we save the machine of the current config
$data->{oldmachine} = $conf->{machine};
+ # use the current 'sync-time-on-resume' preference, as the snapshot may have been taken
+ # before the option was enabled. With the agent disabled now, the snapshot's value applies.
+ my $agent = PVE::QemuServer::Agent::parse_guest_agent($conf->{agent});
+ $data->{'sync-time-on-resume'} = $agent->{'sync-time-on-resume'} // 0
+ if $agent->{enabled};
} else {
# if we have a 'runningmachine' entry in the snapshot we use that
# for the forcemachine parameter, else we use the old logic
@@ -549,7 +559,7 @@ sub __snapshot_rollback_vm_stop {
}
sub __snapshot_rollback_vm_start {
- my ($class, $vmid, $vmstate, $data) = @_;
+ my ($class, $vmid, $vmstate, $data, $opts) = @_;
my $storecfg = PVE::Storage::config();
my $params = {
@@ -557,6 +567,8 @@ sub __snapshot_rollback_vm_start {
forcemachine => $data->{forcemachine},
forcecpu => $data->{forcecpu},
'nets-host-mtu' => $data->{'nets-host-mtu'},
+ 'sync-time-on-resume' => $opts->{'sync-time-on-resume'}
+ // $data->{'sync-time-on-resume'},
};
PVE::QemuServer::vm_start($storecfg, $vmid, $params);
}
diff --git a/src/PVE/QemuMigrate.pm b/src/PVE/QemuMigrate.pm
index a3a6b665..e8df8584 100644
--- a/src/PVE/QemuMigrate.pm
+++ b/src/PVE/QemuMigrate.pm
@@ -1787,6 +1787,12 @@ sub phase3_cleanup {
$self->{errors} = 1;
}
}
+ if (
+ !$self->{errors}
+ && PVE::QemuServer::Agent::should_sync_time_on_resume($conf->{agent})
+ ) {
+ $self->log('info', "guest clock sync via guest agent was requested on target");
+ }
}
if (
diff --git a/src/PVE/QemuServer.pm b/src/PVE/QemuServer.pm
index 638afd80..b0d3d4f7 100644
--- a/src/PVE/QemuServer.pm
+++ b/src/PVE/QemuServer.pm
@@ -5082,7 +5082,10 @@ sub vmconfig_update_agent {
die "skip\n" if !$conf->{$opt};
- my $hotplug_options = { fstrim_cloned_disks => 1 };
+ my $hotplug_options = {
+ fstrim_cloned_disks => 1,
+ 'sync-time-on-resume' => 1,
+ };
my $old_agent = parse_guest_agent($conf->{agent});
my $agent = parse_guest_agent($value);
@@ -5951,6 +5954,18 @@ sub vm_start_nolock {
);
}
+ # $resume = hibernation resume, $statefile = rollback with RAM. For rollback, $conf is already
+ # the restored config and params carry the API override or the pre-rollback sync preference.
+ if ($resume || ($statefile && !$migratedfrom)) {
+ if (PVE::QemuServer::Agent::should_sync_time_on_resume(
+ $conf->{agent},
+ $params->{'sync-time-on-resume'},
+ )) {
+ eval { PVE::QemuServer::Agent::guest_set_time($vmid); };
+ warn "could not sync guest time after resume from saved state - $@" if $@;
+ }
+ }
+
return $res;
}
diff --git a/src/PVE/QemuServer/Agent.pm b/src/PVE/QemuServer/Agent.pm
index be6df443..577da218 100644
--- a/src/PVE/QemuServer/Agent.pm
+++ b/src/PVE/QemuServer/Agent.pm
@@ -4,6 +4,8 @@ use v5.36;
use JSON;
use MIME::Base64 qw(decode_base64 encode_base64);
+use POSIX qw(strftime);
+use Time::HiRes qw(time);
use PVE::JSONSchema;
@@ -52,6 +54,25 @@ our $agent_fmt = {
optional => 1,
default => 1,
},
+ # FIXME: MAJOR VERSION: 10.0.0 - reconsider setting option on as default
+ 'sync-time-on-resume' => {
+ description =>
+ "Synchronize the guest's clock through QGA after operations that can leave"
+ . " the guest's clock behind.",
+ verbose_description =>
+ "Whether to issue the 'guest-set-time' QEMU guest agent command to synchronize the"
+ . " guest's clock to the host's current time after operations that can leave the"
+ . " guest's clock behind. This happens when resuming from hibernation, resuming from a"
+ . " paused state, taking a snapshot, after a live migration, after a backup in suspend"
+ . " mode, and after rolling back to a snapshot that includes RAM. In these cases the"
+ . " guest's clock may still reflect an earlier time. The time is only synchronized"
+ . " when the QEMU Guest Agent option is enabled in the guest's configuration and the"
+ . " agent is running inside of the guest. For resume, hibernation resume and snapshot"
+ . " rollback, the synchronization can be overridden per operation.",
+ type => 'boolean',
+ optional => 1,
+ default => 0,
+ },
type => {
description => "Select the agent type",
type => 'string',
@@ -332,4 +353,46 @@ sub guest_fs_freeze_applicable($agent_str, $vmid, $logfunc = undef) {
return 1;
}
+=head3 should_sync_time_on_resume
+
+Returns whether the guest's clock should be synchronized to the host's via the QEMU Guest Agent
+after operations that can leave the guest's clock behind. Returns 0 if the agent is not enabled. An
+explicit C<$override> (from an API parameter) takes precedence over the C<sync-time-on-resume> agent
+config property when defined; otherwise the config value is used (defaulting to off). Does B<not>
+check whether the agent is actually running.
+
+=cut
+
+sub should_sync_time_on_resume($agent_str, $override = undef) {
+ my $agent = parse_guest_agent($agent_str);
+ return 0 if !$agent->{enabled};
+ return $override ? 1 : 0 if defined($override);
+ return $agent->{'sync-time-on-resume'} // 0;
+}
+
+=head3 guest_set_time
+
+Sets the guest's clock to the current host time via the QEMU Guest Agent's C<guest-set-time>
+command. The host time is passed explicitly (as nanoseconds since the UNIX epoch) because the
+argument-less form reads the time from the guest's RTC, which isn't supported on all platforms
+(e.g. Windows); passing the value directly works regardless of guest OS.
+
+Returns 1 if the time was set, 0 if it was skipped because the agent is not running. Dies if the
+agent returns an error.
+
+=cut
+
+sub guest_set_time($vmid, $quiet = undef) {
+ if (!qga_check_running($vmid, 1)) {
+ print "skipping guest time sync - agent configured but not running?\n" if !$quiet;
+ return 0;
+ }
+ my $time_ns = time() * 1_000_000_000;
+ my $res = PVE::QemuServer::Monitor::mon_cmd($vmid, 'guest-set-time', time => int($time_ns));
+ check_agent_error($res, "unable to set guest time");
+ my $time_str = strftime("%F %T", localtime($time_ns / 1_000_000_000));
+ print "synced guest clock via guest agent to $time_str\n" if !$quiet;
+ return 1;
+}
+
1;
diff --git a/src/PVE/QemuServer/RunState.pm b/src/PVE/QemuServer/RunState.pm
index 889ddd28..caba403e 100644
--- a/src/PVE/QemuServer/RunState.pm
+++ b/src/PVE/QemuServer/RunState.pm
@@ -131,7 +131,7 @@ sub vm_suspend($vmid, $skiplock = undef, $includestate = undef, $statestorage =
# $nocheck is set when called as part of a migration - in this context the
# location of the config file (source or target node) is not deterministic,
# since migration cannot wait for pmxcfs to process the rename
-sub vm_resume($vmid, $skiplock = undef, $nocheck = undef) {
+sub vm_resume($vmid, $skiplock = undef, $nocheck = undef, $sync_time = undef, $quiet = undef) {
PVE::QemuConfig->lock_config(
$vmid,
@@ -183,6 +183,20 @@ sub vm_resume($vmid, $skiplock = undef, $nocheck = undef) {
if $resume_cmd eq 'cont';
mon_cmd($vmid, $resume_cmd);
+
+ # A VM in 'prelaunch' never ran, and a VM that shut down during a backup is reset
+ # above. Both boot fresh, so the clock is not behind and the agent is not up yet.
+ my $status = $res->{status} // '';
+ my $guest_was_running = $status ne 'prelaunch' && $status ne 'shutdown';
+ if (
+ $resume_cmd eq 'cont'
+ && $guest_was_running
+ && PVE::QemuServer::Agent::should_sync_time_on_resume($conf->{agent},
+ $sync_time)
+ ) {
+ eval { PVE::QemuServer::Agent::guest_set_time($vmid, $quiet); };
+ warn "could not sync guest time after resume - $@" if $@;
+ }
},
);
}
diff --git a/src/PVE/VZDump/QemuServer.pm b/src/PVE/VZDump/QemuServer.pm
index 1584fbd7..b6437901 100644
--- a/src/PVE/VZDump/QemuServer.pm
+++ b/src/PVE/VZDump/QemuServer.pm
@@ -1185,20 +1185,41 @@ sub enforce_vm_running_for_backup {
die $@ if $@;
}
+my sub sync_guest_time_after_resume {
+ my ($self, $vmid) = @_;
+
+ my $agent_str = $self->{vmlist}->{$vmid}->{agent};
+ return if !PVE::QemuServer::Agent::should_sync_time_on_resume($agent_str);
+
+ my $synced = eval { PVE::QemuServer::Agent::guest_set_time($vmid, 1) };
+ if (my $err = $@) {
+ $self->log('warn', "could not sync guest time - $err");
+ } elsif ($synced) {
+ $self->loginfo("synced guest clock via guest agent");
+ } else {
+ $self->loginfo("skipping guest time sync - agent configured but not running?");
+ }
+}
+
# resume VM again once in a clear state (stop mode backup of running VM)
sub resume_vm_after_job_start {
my ($self, $task, $vmid) = @_;
return if !$self->{vm_was_running} || $self->{vm_was_paused};
- if (my $stoptime = $task->{vmstoptime}) {
- my $delay = time() - $task->{vmstoptime};
+ my $stoptime = $task->{vmstoptime};
+ if ($stoptime) {
+ my $delay = time() - $stoptime;
$task->{vmstoptime} = undef; # avoid printing 'online after ..' twice
$self->loginfo("resuming VM again after $delay seconds");
} else {
$self->loginfo("resuming VM again");
}
mon_cmd($vmid, 'cont', timeout => 45);
+
+ # only after a real vCPU pause: in stop mode the guest just booted, and $stoptime is
+ # cleared after the first call, so the error path does not sync twice
+ sync_guest_time_after_resume($self, $vmid) if $stoptime && $task->{mode} eq 'suspend';
}
# stop again if VM was not running before
--
2.47.3
^ permalink raw reply related [flat|nested] 7+ messages in thread
* applied: [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA
2026-11-17 12:39 [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA Jakob Klocker
` (2 preceding siblings ...)
2026-11-17 12:39 ` [PATCH qemu-server v7 3/3] fix #5032: agent: sync guest time via QGA when the clock falls behind Jakob Klocker
@ 2026-11-18 14:22 ` Thomas Lamprecht
2026-11-19 6:36 ` Jakob Klocker
3 siblings, 1 reply; 7+ messages in thread
From: Thomas Lamprecht @ 2026-11-18 14:22 UTC (permalink / raw)
To: pve-devel, Jakob Klocker
On Tue, 17 Nov 2026 13:39:29 +0100, Jakob Klocker wrote:
> This series adds a new agent option 'sync-time-on-resume' to
> automatically synchronize the guest clock via the QEMU Guest Agent
> after operations that can leave the guest time stale. The option is
> disabled by default and only takes effect when the QEMU Guest Agent is
> enabled.
>
> When a VM resumes with a restored RAM state (waking from hibernation or
> rolling back to a snapshot that includes RAM), the guest clock
> continues from the point the state was saved and no longer matches
> wall-clock time. Skew also appears whenever the guest is briefly
> frozen and resumed - after creating a snapshot, an
> ordinary pause/resume, the resume step of a live migration, or a
> vzdump in suspend mode.
>
> [...]
Applied, thanks!
I adapted a few things while/on applying, mainly:
- ui: the agent editor now loads a value of 'yes' or 'on' for the new
option as checked. Before, it showed such a value as unchecked, so
saving any other agent setting dropped the option.
- qemu-server: reworded the FIXME about enabling the option by default
and dropped its version number, like the other major version markers.
- guest-common, qemu-server: wrapped two calls with their arguments as
one block, as proxmox-perltidy keeps that form.
On top, I added a qemu-server commit with tests for which setting
decides the sync after a rollback with RAM and for
should_sync_time_on_resume():
tests: cover the guest time sync decision, also for snapshot rollback
https://git.proxmox.com/?p=qemu-server.git;a=commitdiff;h=7cf9da59d92f31c7eb00b97dcb17cfa0d7e0c2b6
Two things are still missing and could be nice as follow-ups:
- the agent section of the admin guide (qm.adoc) does not document the
new option yet.
- the Yew agent editor in proxmox-yew-comp, as used by the mobile UI and
PDM, drops the option on save, as pve-api-types does not know it yet.
That needs a regeneration of pve-api-types and a checkbox there.
[pve-guest-common] applied to pve-guest-common.git (master)
[1/1] AbstractConfig: allow passing options to snapshot_rollback
https://git.proxmox.com/?p=pve-guest-common.git;a=commitdiff;h=c40393975da1c910dccbd7f395526a7b8d10256c
[pve-manager] applied to pve-manager.git (master)
[1/1] fix #5032: ui: qemu agent: add sync-time-on-resume option
https://git.proxmox.com/?p=pve-manager.git;a=commitdiff;h=a9c7e78dd99b7fbede101c7074f6c1f682737950
[qemu-server] applied to qemu-server.git (master)
[1/1] fix #5032: agent: sync guest time via QGA when the clock falls behind
https://git.proxmox.com/?p=qemu-server.git;a=commitdiff;h=a78800b9dea016f853af0edde033a5201da62b1b
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: applied: [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA
2026-11-18 14:22 ` applied: [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA Thomas Lamprecht
@ 2026-11-19 6:36 ` Jakob Klocker
2026-11-19 8:52 ` Thomas Lamprecht
0 siblings, 1 reply; 7+ messages in thread
From: Jakob Klocker @ 2026-11-19 6:36 UTC (permalink / raw)
To: Thomas Lamprecht, pve-devel
On Wed Nov 18, 2026 at 3:22 PM CET, Thomas Lamprecht wrote:
>> [snip]
>
> Applied, thanks!
>
> I adapted a few things while/on applying, mainly:
>
> - ui: the agent editor now loads a value of 'yes' or 'on' for the new
> option as checked. Before, it showed such a value as unchecked, so
> saving any other agent setting dropped the option.
> - qemu-server: reworded the FIXME about enabling the option by default
> and dropped its version number, like the other major version markers.
> - guest-common, qemu-server: wrapped two calls with their arguments as
> one block, as proxmox-perltidy keeps that form.
>
> On top, I added a qemu-server commit with tests for which setting
> decides the sync after a rollback with RAM and for
> should_sync_time_on_resume():
>
> tests: cover the guest time sync decision, also for snapshot rollback
> https://git.proxmox.com/?p=qemu-server.git;a=commitdiff;h=7cf9da59d92f31c7eb00b97dcb17cfa0d7e0c2b6
>
> Two things are still missing and could be nice as follow-ups:
>
> - the agent section of the admin guide (qm.adoc) does not document the
> new option yet.
> - the Yew agent editor in proxmox-yew-comp, as used by the mobile UI and
> PDM, drops the option on save, as pve-api-types does not know it yet.
> That needs a regeneration of pve-api-types and a checkbox there.
>
Thanks for the improvements. I'll add the follow-ups to my
backlog.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: applied: [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA
2026-11-19 6:36 ` Jakob Klocker
@ 2026-11-19 8:52 ` Thomas Lamprecht
0 siblings, 0 replies; 7+ messages in thread
From: Thomas Lamprecht @ 2026-11-19 8:52 UTC (permalink / raw)
To: Jakob Klocker, pve-devel
Am 19.11.26 um 07:36 schrieb Jakob Klocker:
>> Two things are still missing and could be nice as follow-ups:
>>
>> - the agent section of the admin guide (qm.adoc) does not document the
>> new option yet.
>> - the Yew agent editor in proxmox-yew-comp, as used by the mobile UI and
>> PDM, drops the option on save, as pve-api-types does not know it yet.
>> That needs a regeneration of pve-api-types and a checkbox there.
>>
> Thanks for the improvements. I'll add the follow-ups to my
> backlog.
Docs would be especially nice to have to make this actually complete,
hard to know about or find such features without any documentation.
Yew is currently defused as we do not offer edit for it, in mobile
UI we render it only and so does PDM - so not pressing, but it is a
time bomb, so lets try not to forget it.
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2026-11-19 8:52 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-17 12:39 [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA Jakob Klocker
2026-11-17 12:39 ` [PATCH pve-guest-common v7 1/3] AbstractConfig: allow passing options to snapshot_rollback Jakob Klocker
2026-11-17 12:39 ` [PATCH pve-manager v7 2/3] fix #5032: ui: qemu agent: add sync-time-on-resume option Jakob Klocker
2026-11-17 12:39 ` [PATCH qemu-server v7 3/3] fix #5032: agent: sync guest time via QGA when the clock falls behind Jakob Klocker
2026-11-18 14:22 ` applied: [PATCH guest-common/manager/qemu-server v7 0/3] fix #5032: add guest time sync via QGA Thomas Lamprecht
2026-11-19 6:36 ` Jakob Klocker
2026-11-19 8:52 ` Thomas Lamprecht
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.