all lists on lists.proxmox.com
 help / color / mirror / Atom feed
From: Maximiliano Sandoval <m.sandoval@proxmox.com>
To: Jakob Klocker <j.klocker@proxmox.com>
Cc: pve-devel@lists.proxmox.com
Subject: Re: [PATCH pve-docs] qm: guest agent: document sync-time-on-resume option
Date: Thu, 19 Nov 2026 12:45:50 +0100	[thread overview]
Message-ID: <s8owlq9yrgx.fsf@toolbox> (raw)
In-Reply-To: <20261119103924.156068-1-j.klocker@proxmox.com> (Jakob Klocker's message of "Thu, 19 Nov 2026 11:39:24 +0100")

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




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

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
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 message]

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=s8owlq9yrgx.fsf@toolbox \
    --to=m.sandoval@proxmox.com \
    --cc=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