all lists on lists.proxmox.com
 help / color / mirror / Atom feed
From: Jakob Klocker <j.klocker@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH pve-docs] qm: guest agent: document sync-time-on-resume option
Date: Thu, 19 Nov 2026 11:39:24 +0100	[thread overview]
Message-ID: <20261119103924.156068-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>
---
 qm.adoc | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/qm.adoc b/qm.adoc
index 18a4fbe..6e86b60 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -1660,6 +1660,68 @@ 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. The same applies when
+a VM continues 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 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` option enabled, {pve} sets the guest's clock to
+the host's current time via the `guest-set-time` QEMU 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. To enable it in the GUI, open the 'Options'
+panel of the virtual machine, then the 'QEMU Guest Agent' dialog, and enable
+the 'Synchronize guest clock after resume, snapshot, rollback or migration'
+option. On the command line, add `sync-time-on-resume=1` to the `agent` option,
+keeping any other agent options you have already set, for example:
+
+----
+# 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`). With `1`, the clock is
+synchronized even if the option is disabled; with `0`, it is not
+synchronized even if the option is enabled. For example, to resume a
+VM without synchronizing its clock:
+
+----
+# qm resume <vmid> --sync-time-on-resume 0
+----
+
+Taking a snapshot, 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.
+
 Troubleshooting
 ^^^^^^^^^^^^^^^
 
-- 
2.47.3





             reply	other threads:[~2026-11-19 10:43 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-19 10:39 Jakob Klocker [this message]
2026-11-19 11:45 ` [PATCH pve-docs] qm: guest agent: document sync-time-on-resume option Maximiliano Sandoval

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=20261119103924.156068-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.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal