all lists on lists.proxmox.com
 help / color / mirror / Atom feed
* [PATCH pve-docs v2] qm: guest agent: document sync-time-on-resume option
@ 2026-11-20  9:55 Jakob Klocker
  2026-11-20 10:29 ` Maximiliano Sandoval
  2026-11-20 11:21 ` applied: " Thomas Lamprecht
  0 siblings, 2 replies; 3+ messages in thread
From: Jakob Klocker @ 2026-11-20  9:55 UTC (permalink / raw)
  To: pve-devel

Add a section about the new 'sync-time-on-resume' agent option to the
QEMU Guest Agent docs.

Signed-off-by: Jakob Klocker <j.klocker@proxmox.com>
---
Thanks a lot to @Maximiliano for helping me word this more precisely!

 qm.adoc | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/qm.adoc b/qm.adoc
index 18a4fbe..2c66411 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -1660,6 +1660,64 @@ IMPORTANT: Disabling this option can potentially lead to backups with
 inconsistent filesystems. Therefore, adapting the QEMU Guest Agent
 configuration in the guest is the preferred option.
 
+[[qm_qga_time_sync]]
+Guest Clock Synchronization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While a VM is paused, the guest's clock does not advance. A similar problem
+occurs when restoring a VM from a previously saved state, for example after
+hibernation or after rolling back to a snapshot that includes RAM. Once the VM
+runs again, the guest's clock lags behind the host's time. A live migration can
+have the same effect if transferring the final part of the VM's state takes a
+long time, because the VM is paused during that phase. A time synchronization
+service in the guest, such as NTP, may correct a large offset only slowly or
+not at all, depending on its configuration. Until then, time-sensitive services
+can misbehave.
+
+With the `sync-time-on-resume` QEMU Guest Agent option enabled, {pve} sets the
+guest's clock to the host's current time via the
+https://www.qemu.org/docs/master/interop/qemu-ga-ref.html#command-QGA-qapi-schema.guest-set-time[`guest-set-time`]
+guest agent command right after the following operations:
+
+* resuming a paused VM
+* resuming a hibernated VM
+* rolling back to a snapshot that includes RAM
+* taking a snapshot of a running VM
+* live migrating a VM to another node
+* performing a backup in suspend mode
+
+The option is disabled by default. You can enable it in the 'QEMU Guest Agent'
+dialog in the VM's 'Options' panel, or with
+`qm set <vmid> --agent 1,sync-time-on-resume=1`.
+
+.Overriding the Option for a Single Operation
+For a single operation, the configured value can be overridden with the
+`--sync-time-on-resume` parameter. This is supported when resuming a paused or
+hibernated VM (`qm resume`), starting a hibernated VM (`qm start`), and rolling
+back to a snapshot with RAM (`qm rollback`). For example, to resume a VM
+without synchronizing its clock:
+
+----
+# qm resume <vmid> --sync-time-on-resume 0
+----
+
+Snapshots, live migrations and backups always use the configured value.
+
+.Rolling Back to a Snapshot
+When rolling back to a snapshot with RAM, {pve} decides whether to synchronize
+the clock as follows:
+
+* If the `--sync-time-on-resume` parameter is given, its value is used.
+* Otherwise, if the guest agent is enabled in the configuration before the
+  rollback, its `sync-time-on-resume` setting is used (disabled if not set).
+  This way, the current setting also applies to snapshots taken before the
+  option was enabled.
+* Otherwise, the `sync-time-on-resume` setting stored in the snapshot is used.
+
+In any case, the guest agent must be enabled in the snapshot's configuration,
+since the restored VM runs with the hardware configuration of the snapshot. The
+agent must also be running inside the guest.
+
 Troubleshooting
 ^^^^^^^^^^^^^^^
 
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 3+ messages in thread

* Re: [PATCH pve-docs v2] qm: guest agent: document sync-time-on-resume option
  2026-11-20  9:55 [PATCH pve-docs v2] qm: guest agent: document sync-time-on-resume option Jakob Klocker
@ 2026-11-20 10:29 ` Maximiliano Sandoval
  2026-11-20 11:21 ` applied: " Thomas Lamprecht
  1 sibling, 0 replies; 3+ messages in thread
From: Maximiliano Sandoval @ 2026-11-20 10:29 UTC (permalink / raw)
  To: Jakob Klocker; +Cc: pve-devel

Jakob Klocker <j.klocker@proxmox.com> writes:

> Add a section about the new 'sync-time-on-resume' agent option to the
> QEMU Guest Agent docs.
>
> Signed-off-by: Jakob Klocker <j.klocker@proxmox.com>
> ---
> [...]

Looks good to me.

Reviewed-by: Maximiliano Sandoval <m.sandoval@proxmox.com>

-- 
Maximiliano




^ permalink raw reply	[flat|nested] 3+ messages in thread

* applied: [PATCH pve-docs v2] qm: guest agent: document sync-time-on-resume option
  2026-11-20  9:55 [PATCH pve-docs v2] qm: guest agent: document sync-time-on-resume option Jakob Klocker
  2026-11-20 10:29 ` Maximiliano Sandoval
@ 2026-11-20 11:21 ` Thomas Lamprecht
  1 sibling, 0 replies; 3+ messages in thread
From: Thomas Lamprecht @ 2026-11-20 11:21 UTC (permalink / raw)
  To: pve-devel, Jakob Klocker

On Fri, 20 Nov 2026 10:55:39 +0100, Jakob Klocker wrote:
> Add a section about the new 'sync-time-on-resume' agent option to the
> QEMU Guest Agent docs.

Applied, thanks!

[1/1] qm: guest agent: document sync-time-on-resume option
      https://git.proxmox.com/?p=pve-docs.git;a=commitdiff;h=6bb1b848dc1ab3b6a27806c6b5776c7e8e788c01




^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2026-11-20 11:22 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-20  9:55 [PATCH pve-docs v2] qm: guest agent: document sync-time-on-resume option Jakob Klocker
2026-11-20 10:29 ` Maximiliano Sandoval
2026-11-20 11:21 ` applied: " 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.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal