[PATCH 0/2] docs: Fix docs for VIR_MIGRATE_PARAM_MIGRATE_DISKS_DETECT_ZEROES_ZEROES
Remove note about needing a pre-cleared image and document need to enable discards to obtain a sparse image. Peter Krempa (2): Revert "docs: Add warning about using a cleared image with VIR_MIGRATE_PARAM_MIGRATE_DISKS_DETECT_ZEROES_ZEROES" docs: Note that zero detection on migration sparsifies image only when discard='unmap' is set docs/manpages/virsh.rst | 7 +++---- include/libvirt/libvirt-domain.h | 12 +++++------- 2 files changed, 8 insertions(+), 11 deletions(-) -- 2.49.0
From: Peter Krempa <pkrempa@redhat.com> QEMU clears the images even when sparse mode is required so asking the users to do so is not needed. Remove the docs. This reverts commit 332ee4931a84ec23e7f6fcb963083318c1307dc7 Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/manpages/virsh.rst | 4 +--- include/libvirt/libvirt-domain.h | 5 +---- 2 files changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst index 895a905b08..9b571761b8 100644 --- a/docs/manpages/virsh.rst +++ b/docs/manpages/virsh.rst @@ -3642,9 +3642,7 @@ 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. Users must ensure that any -pre-created storage source is cleared and thus reads all-zeroes before using -this option as otherwise the destination image may become corrupted. +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 ac5daf7d0c..1af5045571 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -1276,10 +1276,7 @@ typedef enum { * * 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. Users must ensure that any pre-created storage source on - * the destination will be cleared and thus read all-zeroes before using this - * feature, otherwise the destination image may become corrupted. - * This may increase CPU overhead of the migration. At the + * 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. * -- 2.49.0
From: Peter Krempa <pkrempa@redhat.com> 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> --- docs/manpages/virsh.rst | 5 +++-- include/libvirt/libvirt-domain.h | 9 +++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst index 9b571761b8..a2dab293ad 100644 --- 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 1af5045571..3d05ffc5aa 100644 --- 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 */ -- 2.49.0
On Thu, Jun 05, 2025 at 03:22:03PM +0200, Peter Krempa via Devel wrote:
Remove note about needing a pre-cleared image and document need to enable discards to obtain a sparse image.
Peter Krempa (2): Revert "docs: Add warning about using a cleared image with VIR_MIGRATE_PARAM_MIGRATE_DISKS_DETECT_ZEROES_ZEROES" docs: Note that zero detection on migration sparsifies image only when discard='unmap' is set
docs/manpages/virsh.rst | 7 +++---- include/libvirt/libvirt-domain.h | 12 +++++------- 2 files changed, 8 insertions(+), 11 deletions(-)
Series: Acked-by: Eric Blake <eblake@redhat.com> -- Eric Blake, Principal Software Engineer Red Hat, Inc. Virtualization: qemu.org | libguestfs.org
participants (2)
-
Eric Blake -
Peter Krempa