[pve-devel] [PATCH docs] qm, vzdump: add notes regarding backups of windows and VSS

[pve-devel] [PATCH docs] qm, vzdump: add notes regarding backups of windows and VSS

[Aaron Lauterer]

VSS in windows guests with additional backup software in the guest can
cause problems. By now the guest agent does support to use a different
VSS option. This way, one can switch to one that does not interfere with
other backup solutions.

Mention it in the docs and link to the wiki article that explains it.

Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
---
 qm.adoc     | 13 +++++++++----
 vzdump.adoc |  4 ++++
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/qm.adoc b/qm.adoc
index 4bb8f2c..660047a 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -1355,14 +1355,19 @@ that calling 'fs-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.
 
-For such setups you can configure {pve} to not issue a freeze-and-thaw cycle on
+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.
 
-IMPORTANT: Disabling this option can potentially lead to backups with inconsistent
-filesystems and should therefore only be disabled if you know what you are
-doing.
+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.
 
 Troubleshooting
 ^^^^^^^^^^^^^^^
diff --git a/vzdump.adoc b/vzdump.adoc
index aecb353..0708d07 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -96,6 +96,10 @@ a background QEMU process, a stopped VM will appear as running for a
 short amount of time while the VM disks are being read by QEMU.
 However the VM itself is not booted, only its disk(s) are read.
 
+NOTE: On Windows guests it is necessary to configure the guest agent if another
+backup software is used within the guest. See xref:qm_qga_fsfreeze[Freeze & Thaw]
+in the guest agent section for more details.
+
 .Backup modes for Containers:
 
 `stop` mode::
-- 
2.39.5



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH docs] qm, vzdump: add notes regarding backups of windows and VSS

[Alexander Zeidler]

On Mon Jan 20, 2025 at 3:35 PM CET, Aaron Lauterer wrote:
> VSS in windows guests with additional backup software in the guest can
> cause problems. By now the guest agent does support to use a different
> VSS option. This way, one can switch to one that does not interfere with
> other backup solutions.
>
> Mention it in the docs and link to the wiki article that explains it.
>
> Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
> ---
Two formatting suggestions inline, otherwise consider this:
Reviewed-by: Alexander Zeidler <a.zeidler@proxmox.com>

>  qm.adoc     | 13 +++++++++----
>  vzdump.adoc |  4 ++++
>  2 files changed, 13 insertions(+), 4 deletions(-)
>
> diff --git a/qm.adoc b/qm.adoc
> index 4bb8f2c..660047a 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -1355,14 +1355,19 @@ that calling 'fs-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.
>  
> -For such setups you can configure {pve} to not issue a freeze-and-thaw cycle on
> +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.
>  
> -IMPORTANT: Disabling this option can potentially lead to backups with inconsistent
> -filesystems and should therefore only be disabled if you know what you are
> -doing.
> +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.
Since there is now a numbered list, it may make sense to move the
modified "Important" admonition to option 2 (so indented).

>  
>  Troubleshooting
>  ^^^^^^^^^^^^^^^
> diff --git a/vzdump.adoc b/vzdump.adoc
> index aecb353..0708d07 100644
> --- a/vzdump.adoc
> +++ b/vzdump.adoc
> @@ -96,6 +96,10 @@ a background QEMU process, a stopped VM will appear as running for a
>  short amount of time while the VM disks are being read by QEMU.
>  However the VM itself is not booted, only its disk(s) are read.
>  
> +NOTE: On Windows guests it is necessary to configure the guest agent if another
> +backup software is used within the guest. See xref:qm_qga_fsfreeze[Freeze & Thaw]
> +in the guest agent section for more details.
For me it seems more appropriate to put the new note under "snapshot
mode" (so indented), since it is only relevant there.

> +
>  .Backup modes for Containers:
>  
>  `stop` mode::



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH docs] qm, vzdump: add notes regarding backups of windows and VSS

[Aaron Lauterer]

On  2025-01-21  13:08, Alexander Zeidler wrote:
> On Mon Jan 20, 2025 at 3:35 PM CET, Aaron Lauterer wrote:
>> VSS in windows guests with additional backup software in the guest can
>> cause problems. By now the guest agent does support to use a different
>> VSS option. This way, one can switch to one that does not interfere with
>> other backup solutions.
>>
>> Mention it in the docs and link to the wiki article that explains it.
>>
>> Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
>> ---
> Two formatting suggestions inline, otherwise consider this:
> Reviewed-by: Alexander Zeidler <a.zeidler@proxmox.com>
> 
>>   qm.adoc     | 13 +++++++++----
>>   vzdump.adoc |  4 ++++
>>   2 files changed, 13 insertions(+), 4 deletions(-)
>>
>> diff --git a/qm.adoc b/qm.adoc
>> index 4bb8f2c..660047a 100644
>> --- a/qm.adoc
>> +++ b/qm.adoc
>> @@ -1355,14 +1355,19 @@ that calling 'fs-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.
>>   
>> -For such setups you can configure {pve} to not issue a freeze-and-thaw cycle on
>> +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.
>>   
>> -IMPORTANT: Disabling this option can potentially lead to backups with inconsistent
>> -filesystems and should therefore only be disabled if you know what you are
>> -doing.
>> +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.
> Since there is now a numbered list, it may make sense to move the
> modified "Important" admonition to option 2 (so indented).

Do you have a suggestion how we can get it indented? I tried getting it 
into the list item, but that didn't work and I am currenlty not aware 
how to indent a Note/warning etc.

> 
>>   
>>   Troubleshooting
>>   ^^^^^^^^^^^^^^^
>> diff --git a/vzdump.adoc b/vzdump.adoc
>> index aecb353..0708d07 100644
>> --- a/vzdump.adoc
>> +++ b/vzdump.adoc
>> @@ -96,6 +96,10 @@ a background QEMU process, a stopped VM will appear as running for a
>>   short amount of time while the VM disks are being read by QEMU.
>>   However the VM itself is not booted, only its disk(s) are read.
>>   
>> +NOTE: On Windows guests it is necessary to configure the guest agent if another
>> +backup software is used within the guest. See xref:qm_qga_fsfreeze[Freeze & Thaw]
>> +in the guest agent section for more details.
> For me it seems more appropriate to put the new note under "snapshot
> mode" (so indented), since it is only relevant there.
> 
>> +
>>   .Backup modes for Containers:
>>   
>>   `stop` mode::
> 
> 
> 
> _______________________________________________
> pve-devel mailing list
> pve-devel@lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
> 
> 



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH docs] qm, vzdump: add notes regarding backups of windows and VSS

[Alexander Zeidler]

On Tue Jan 21, 2025 at 3:46 PM CET, Aaron Lauterer wrote:
>
>
> On  2025-01-21  13:08, Alexander Zeidler wrote:
>> On Mon Jan 20, 2025 at 3:35 PM CET, Aaron Lauterer wrote:
>>> VSS in windows guests with additional backup software in the guest can
>>> cause problems. By now the guest agent does support to use a different
>>> VSS option. This way, one can switch to one that does not interfere with
>>> other backup solutions.
>>>
>>> Mention it in the docs and link to the wiki article that explains it.
>>>
>>> Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
>>> ---
>> Two formatting suggestions inline, otherwise consider this:
>> Reviewed-by: Alexander Zeidler <a.zeidler@proxmox.com>
>> 
>>>   qm.adoc     | 13 +++++++++----
>>>   vzdump.adoc |  4 ++++
>>>   2 files changed, 13 insertions(+), 4 deletions(-)
>>>
>>> diff --git a/qm.adoc b/qm.adoc
>>> index 4bb8f2c..660047a 100644
>>> --- a/qm.adoc
>>> +++ b/qm.adoc
>>> @@ -1355,14 +1355,19 @@ that calling 'fs-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.
>>>   
>>> -For such setups you can configure {pve} to not issue a freeze-and-thaw cycle on
>>> +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.
>>>   
>>> -IMPORTANT: Disabling this option can potentially lead to backups with inconsistent
>>> -filesystems and should therefore only be disabled if you know what you are
>>> -doing.
>>> +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.
>> Since there is now a numbered list, it may make sense to move the
>> modified "Important" admonition to option 2 (so indented).
>
> Do you have a suggestion how we can get it indented? I tried getting it 
> into the list item, but that didn't work and I am currenlty not aware 
> how to indent a Note/warning etc.
Sorry! Yes, you can use:
2. [...]
+
IMPORTANT: [...]

>
>> 
>>>   
>>>   Troubleshooting
>>>   ^^^^^^^^^^^^^^^
>>> diff --git a/vzdump.adoc b/vzdump.adoc
>>> index aecb353..0708d07 100644
>>> --- a/vzdump.adoc
>>> +++ b/vzdump.adoc
>>> @@ -96,6 +96,10 @@ a background QEMU process, a stopped VM will appear as running for a
>>>   short amount of time while the VM disks are being read by QEMU.
>>>   However the VM itself is not booted, only its disk(s) are read.
>>>   
>>> +NOTE: On Windows guests it is necessary to configure the guest agent if another
>>> +backup software is used within the guest. See xref:qm_qga_fsfreeze[Freeze & Thaw]
>>> +in the guest agent section for more details.
>> For me it seems more appropriate to put the new note under "snapshot
>> mode" (so indented), since it is only relevant there.
>> 
>>> +
>>>   .Backup modes for Containers:
>>>   
>>>   `stop` mode::
>> 
>> 
>> 
>> _______________________________________________
>> pve-devel mailing list
>> pve-devel@lists.proxmox.com
>> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
>> 
>> 



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] applied: [PATCH docs] qm, vzdump: add notes regarding backups of windows and VSS

[Aaron Lauterer]

On  2025-01-20  15:35, Aaron Lauterer wrote:
> VSS in windows guests with additional backup software in the guest can
> cause problems. By now the guest agent does support to use a different
> VSS option. This way, one can switch to one that does not interfere with
> other backup solutions.
> 
> Mention it in the docs and link to the wiki article that explains it.
> 
> Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
> ---
>   qm.adoc     | 13 +++++++++----
>   vzdump.adoc |  4 ++++
>   2 files changed, 13 insertions(+), 4 deletions(-)
> 
>

applied with the suggestions incorporated and the R-B tags added.


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel