all lists on lists.proxmox.com
 help / color / mirror / Atom feed
* [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.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal