From: Maximiliano Sandoval <m.sandoval@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH docs] qm: reflect changes in the freeze apis
Date: Fri, 26 Jun 2026 09:51:28 +0200 [thread overview]
Message-ID: <20260626075138.138302-1-m.sandoval@proxmox.com> (raw)
The current docs reference 'fs-freeze' commands, but there are no such
qga commands.
We either refer to the commands by their complete name or informally as
"freeze" and "thaw". A link to the guest agent reference is added, since
it contains interesting information, e.g. that on Windows a thaw is
issued automatically 10s.
The docs for the UI's side are updated to reflect the changes on the
labels and explain where this option is located.
Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
---
qm.adoc | 28 +++++++++++++++++-----------
1 file changed, 17 insertions(+), 11 deletions(-)
diff --git a/qm.adoc b/qm.adoc
index 96ba68b..b9a3529 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -1553,7 +1553,8 @@ For example, the IP addresses in the VM summary panel are fetched via the guest
agent.
Or when starting a backup, the guest is told via the guest agent to sync
-outstanding writes via the 'fs-freeze' and 'fs-thaw' commands.
+outstanding writes via the `guest-fsfreeze-freeze` and `guest-fsfreeze-thaw`
+commands.
For the guest agent to work properly the following steps must be taken:
@@ -1603,10 +1604,14 @@ Filesystem Freeze & Thaw
By default, if the QEMU Guest Agent is enabled in the guest's config and if the
agent is available inside of the guest, then the virtual machine's filesystems
-are synced via the 'fs-freeze' QEMU Guest Agent command when certain operations
-are performed. This is done to provide data consistency.
+are synced via the `guest-fsfreeze-freeze` QEMU Guest Agent command when certain
+operations are performed. This is done to provide data consistency.
-An 'fs-freeze' will be issued for any of the following operations on a VM:
+See the
+https://www.qemu.org/docs/master/interop/qemu-ga-ref.html[QEMU Guest Agent Protocol Reference]
+for more details.
+
+An freeze will be issued for any of the following operations on a VM:
* Performing a backup in snapshot mode
* Creating a clone of a VM while it is running
@@ -1616,9 +1621,9 @@ An 'fs-freeze' will be issued for any of the following operations on a VM:
running guest
On Windows guests, some applications might handle consistent backups themselves
-by hooking into the Windows VSS (Volume Shadow Copy Service) layer, a
-'fs-freeze' then might interfere with that. For example, it has been observed
-that calling 'fs-freeze' with some SQL Servers triggers VSS to call the SQL
+by hooking into the Windows VSS (Volume Shadow Copy Service) layer, a freeze
+then might interfere with that. For example, it has been observed that calling
+`guest-fsfreeze-freeze` with some SQL Servers triggers VSS to call the SQL
Writer VSS module in a mode that breaks the SQL Server backup chain for
differential backups.
@@ -1627,10 +1632,11 @@ There are two options on how to handle such a situation.
1. Configure the QEMU Guest Agent to use a different VSS variant that does not
interfere with other VSS users. The https://pve.proxmox.com/wiki/VM_Backup_Consistency[{pve} wiki]
has more details.
-2. Alternatively, you can configure {pve} to not issue a freeze-and-thaw cycle on
-backup by setting the `freeze-fs-on-backup` QGA option to `0`. This can also be
-done via the GUI with the 'Freeze/thaw guest filesystems on backup for
-consistency' option.
+2. Alternatively, you can configure {pve} to not issue a freeze-and-thaw cycles
+by disabling the `freeze-fs` guest agent option. This can also be done via the
+GUI at the options panel of the virtual machine, then on the 'Freeze/thaw guest
+filesystems during certain operations for consistency' option inside the 'QEMU
+Guest Agent' dialog.
+
IMPORTANT: Disabling this option can potentially lead to backups with
inconsistent filesystems. Therefore, adapting the QEMU Guest Agent
--
2.47.3
reply other threads:[~2026-06-26 7:51 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
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=20260626075138.138302-1-m.sandoval@proxmox.com \
--to=m.sandoval@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.