From: Jakob Klocker <j.klocker@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH pve-docs v2] qm: guest agent: document sync-time-on-resume option
Date: Fri, 20 Nov 2026 10:55:39 +0100 [thread overview]
Message-ID: <20261120095539.59350-1-j.klocker@proxmox.com> (raw)
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
next reply other threads:[~2026-11-20 9:56 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-20 9:55 Jakob Klocker [this message]
2026-11-20 10:29 ` [PATCH pve-docs v2] qm: guest agent: document sync-time-on-resume option Maximiliano Sandoval
2026-11-20 11:21 ` applied: " Thomas Lamprecht
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261120095539.59350-1-j.klocker@proxmox.com \
--to=j.klocker@proxmox.com \
--cc=pve-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.