[pve-devel] [RFC docs 13/13] vzdump: add section about backup fleecing

[Fiona Ebner <f.ebner@proxmox.com>]

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---
 vzdump.adoc | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/vzdump.adoc b/vzdump.adoc
index 24a3e80..eb67141 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -136,6 +136,34 @@ not included in backups. For volume mount points you can set the *Backup* option
 to include the mount point in the backup. Device and bind mounts are never
 backed up as their content is managed outside the {pve} storage library.
 
+VM Backup Fleecing
+~~~~~~~~~~~~~~~~~~
+
+WARNING: Backup fleecing is still being worked on (also in upstream QEMU) and is
+currently only a technology preview.
+
+When a backup for a VM is started, QEMU will install a "copy-before-write"
+filter in its block layer. This filter ensures that upon new guest writes, old
+data still needed for the backup is sent to the backup target first. The guest
+write blocks until this operation is finished so guest IO to not-yet-backed-up
+sectors will be limited by the speed of the backup target.
+
+With backup fleecing, such old data is cached in a fleecing image rather than
+sent directly to the backup target. This can help guest IO performance and even
+prevent hangs in certain scenarios, at the cost of requiring more storage space.
+Use e.g. `vzdump 123 --fleecing enabled=1,storage=local-zfs` to enable backup
+fleecing, with fleecing images created on the storage `local-zfs`. If no storage
+is specified, the fleecing image will be created on the same storage as the
+original image.
+
+WARNING: Theoretically, the fleecing image can grow to the same size as the
+original image, e.g. if the guest re-writes a whole disk while the backup is
+busy with another disk.
+
+Parts of the fleecing image that have been backed up will be discarded to try
+and keep the space usage low.
+
+
 Backup File Names
 -----------------
 
-- 
2.39.2