* [PATCH pve-docs] qm: guest agent: document sync-time-on-resume option
@ 2026-11-19 10:39 Jakob Klocker
2026-11-19 11:45 ` Maximiliano Sandoval
0 siblings, 1 reply; 2+ messages in thread
From: Jakob Klocker @ 2026-11-19 10:39 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>
---
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
^ permalink raw reply related [flat|nested] 2+ messages in thread* Re: [PATCH pve-docs] qm: guest agent: document sync-time-on-resume option
2026-11-19 10:39 [PATCH pve-docs] qm: guest agent: document sync-time-on-resume option Jakob Klocker
@ 2026-11-19 11:45 ` Maximiliano Sandoval
0 siblings, 0 replies; 2+ messages in thread
From: Maximiliano Sandoval @ 2026-11-19 11:45 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>
> ---
> 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
Perhaps it is worth mentioning that this can also happen in certain
scenarios if the last delta of migration takes a long time to be sent.
We had a couple of support cases where that happened. cc @laurentiu
> +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
nit: Perhaps:
With the `sync-time-on-resume` QEMU Guest Agent option enabled, {pve} sets the guest's clock to
it is not clear where to enable it otherwise (this can allow making the
paragraph below a bit leaner).
> +the host's current time via the `guest-set-time` QEMU Guest Agent command right
nit: Perhaps add a link to https://www.qemu.org/docs/master/interop/qemu-ga-ref.html#command-QGA-qapi-schema.guest-get-time.
> +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
> +----
nit: I do not have anything against this, but to me it seems a bit
over-verbose. The documentation rarely explains in such detail how to
set a setting.
> +
> +.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,
nit: And the agent must be running inside of the guest.
> +since the restored VM runs with the hardware configuration of the snapshot.
> +
> Troubleshooting
> ^^^^^^^^^^^^^^^
--
Maximiliano
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2026-11-19 11:45 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-19 10:39 [PATCH pve-docs] qm: guest agent: document sync-time-on-resume option Jakob Klocker
2026-11-19 11:45 ` Maximiliano Sandoval
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.