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

[Thomas Lamprecht]

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
>  ^^^^^^^^^^^^^^^
>