[pve-devel] [PATCH docs 3/3] qm: Add section explaining fs-freeze/thaw QGA option

[Christoph Heiss]

Thanks again, I'll incorporate your suggestions below as appriopriate
for the next spin!

On Thu, Feb 23, 2023 at 12:34:22PM +0100, Thomas Lamprecht wrote:
> Am 01/02/2023 um 13:59 schrieb Christoph Heiss:
> > Signed-off-by: Christoph Heiss <c.heiss at proxmox.com>
> > ---
> >  qm.adoc | 20 ++++++++++++++++++++
> >  1 file changed, 20 insertions(+)
> >
> > diff --git a/qm.adoc b/qm.adoc
> > index 8a49283..f029ceb 100644
> > --- a/qm.adoc
> > +++ b/qm.adoc
> > @@ -1061,6 +1061,26 @@ operations that have the potential to write out zeros to the storage:
> >
> >  On a thin provisioned storage, this can help to free up unused space.
> >
> > +Filesystem freeze/thaw
> > +^^^^^^^^^^^^^^^^^^^^^^
>
> Would title case this and add "on Backup", i.e.: Filesystem Freeze & Thaw on Backup
>
> > +
> > +By default, VM filesystems are synced via the 'fs-freeze' command when a backup
>
> I know we're already in the section, but it might help to remind user
> s/command/QEMU Guest Agent Command/
>
> > +is performed, to provide consistency. On Windows guests, this calls into the VSS
> > +(volume shadow copy) subsystem.
>
> I'd either move the last sentence to the next paragraph or also mention how it's
> done in Linux, as otherwise this IMO reads as it has been put slightly out of place.
>
> > +
> > +There might be cases where this needs to be disabled, e.g. when running
>
> as per our technical writing style guide (see intranet wiki) s/e.g./for example/
>
> > +applications which hook into the Windows VSS subsystem themselves. This has
> > +been observed to be necessary when running SQL Server, which otherwise might
> > +break its own differential backup mode.
>
> I'd reword this a bit, maybe something a long the lines of:
>
> "Some applications handle consistent backups themselves by hooking into the
> Windows VSS layer, a fs-freeze might then interfere with that. For example
> calling fs-freeze whit some SQL Servers triggers VSS to call the SQL Writer
> VSS module in a mode that breaks the SQL backup chain for differential backups.
>
> For such setups 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`, which can
> be also done via the web UI."
>
> Below might be obsolete if (something like) above is adopted, so just commenting
> two minor nits for completeness sake:
>
> > +
> > +This behavior can be turned off using the 'Freeze/thaw filesystems on backup
> > +for consistency' option. With this option disabled, {pve} will skip the
>
> s/skip/skip issuing/
>
> > +'fs-freeze' and 'fs-thaw' commands when running backup jobs.
>
> s/commands/QGA commands/
>
>
> > +
> > +NOTE: Disabling this option can potentially lead to backups with inconsistent
> > +filesystems and should therefore only be changed if you know what you are
>
> s/changed/disabled/
>
> > +doing.
> > +
> >  Troubleshooting
> >  ^^^^^^^^^^^^^^^
> >
>