docs: Note that zero detection on migration sparsifies image only when discard='unmap...

The mirroring job clears the destination to ensure that the guest
visible disk contents are identical to the state on the source. The
image itself is kept sparse only when the disk 'discard' option is set
to 'unmap' (Also the disks would eventually desparsify itself anyways
with disabled discards). Note it in the docs for the user.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Acked-by: Eric Blake <eblake@redhat.com>

diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
index 9b571761b862f039309f0a06eeb52a6c047682b1..a2dab293ad250307110df59eac7b20f59764bee5 100644 (file)
--- a/docs/manpages/virsh.rst
+++ b/docs/manpages/virsh.rst
@@ -3641,8 +3641,9 @@ host. By default only non-shared non-readonly images are transferred. Use
 transfer via the comma separated ``disk-list`` argument.
 The *--migrate-disks-detect-zeroes* option which takes a comma separated list of
 disk target names enables zeroed block detection for the listed migrated disks.
-These blocks are not transferred or allocated on destination, effectively
-sparsifying the disk at the cost of CPU overhead.
+These blocks are not transferred or allocated (requires that 'discard' option
+on given disk is set to 'unmap') on destination, effectively sparsifying the
+disk at the cost of CPU overhead.
 With *--copy-storage-synchronous-writes* flag used the disk data migration will
 synchronously handle guest disk writes to both the original source and the
 destination to ensure that the disk migration converges at the price of possibly

diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 1af504557192cd4cfc347093ebb5dd118923f019..3d05ffc5aaa983a187570db2b6f78c838476666a 100644 (file)
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -1275,10 +1275,11 @@ typedef enum {
  * VIR_MIGRATE_PARAM_MIGRATE_DISKS_DETECT_ZEROES:
  *
  * virDomainMigrate* params multiple field: The multiple values that list
- * the block devices for which zero detection (to avoid transferring zero blocks)
- * is to be enabled. This may increase CPU overhead of the migration. At the
- * moment this is only supported by the QEMU driver but not for the tunnelled
- * migration.
+ * the block devices for which zero detection (to avoid transferring zero blocks,
+ * for storage where it can't be probed) is to be enabled. This may increase CPU
+ * overhead of the migration. Destination image will be sparse only when the
+ * disk 'discard' option is set to 'unmap'. At the moment this is only supported
+ * by the QEMU driver but not for the tunnelled migration.
  *
  * Since: 10.9.0
  */