From nobody Thu Dec 26 11:38:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 172854957137191.96000645416268; Thu, 10 Oct 2024 01:39:31 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 554A613E2; Thu, 10 Oct 2024 04:39:30 -0400 (EDT) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id 5F79413B7; Thu, 10 Oct 2024 04:38:56 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 3882912E9; Thu, 10 Oct 2024 04:38:53 -0400 (EDT) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 701D012C1 for ; Thu, 10 Oct 2024 04:38:52 -0400 (EDT) Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-73-KneU8h9xOAWqOYgd6ckhrQ-1; Thu, 10 Oct 2024 04:38:50 -0400 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D81451955EE9 for ; Thu, 10 Oct 2024 08:38:49 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.45.242.12]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id CFF921955F41 for ; Thu, 10 Oct 2024 08:38:48 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-0.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=3.4.4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1728549532; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=2Txdb26mGB8GV/MEXZuM3OvCo60sFUPLAilmyAe1KTQ=; b=HkfEHGhjM04XAD9LTWlbPnHnFaqSUFHjZh+E7wbD+AT7DE8aFmbFIWQobqFxwNb6b5r2Co gT4veD2KeScpKc3q0jp3YjqdzjcMk8FMbbecfus+nMghHvwBrEdqRCbyJOi1awy4YcoWZW qFEVCuYgysb7FGf0u8iiHY0jas2xGzI= X-MC-Unique: KneU8h9xOAWqOYgd6ckhrQ-1 From: Peter Krempa To: devel@lists.libvirt.org Subject: [PATCH 1/2] docs: Add warning about using a cleared image with VIR_MIGRATE_PARAM_MIGRATE_DISKS_DETECT_ZEROES_ZEROES Date: Thu, 10 Oct 2024 10:38:43 +0200 Message-ID: <1371dbcfb5cc35a4bbf5b76f590511fb2d3f5cee.1728549495.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: RJPJXTJLGJVRTCGDCQ3OAXNEED45TPNH X-Message-ID-Hash: RJPJXTJLGJVRTCGDCQ3OAXNEED45TPNH X-MailFrom: pkrempa@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1728549572643116600 Content-Type: text/plain; charset="utf-8" The migration parameter causes zero detection to be enabled and zero blocks are *not* transferred to the destination. This means that users must provide pre-cleared images that read all zero, otherwise the non-zero blocks on destination which reside in places where the source has zero blocks would be kept intact corrupting the image. As not transferring and overwriting the zero blocks is what the feature is supposed to do the users need to provide the proper environment. Document the requirement, both in API and in the virsh man page for the '--migrate-disks-detect-zeroes' option. Signed-off-by: Peter Krempa --- docs/manpages/virsh.rst | 4 +++- include/libvirt/libvirt-domain.h | 5 ++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst index 6665d46497..6776ea53d0 100644 --- a/docs/manpages/virsh.rst +++ b/docs/manpages/virsh.rst @@ -3425,7 +3425,9 @@ transfer via the comma separated ``disk-list`` argume= nt. The *--migrate-disks-detect-zeroes* option which takes a comma separated l= ist of disk target names enables zeroed block detection for the listed migrated d= isks. These blocks are not transferred or allocated on destination, effectively -sparsifying the disk at the cost of CPU overhead. +sparsifying the disk at the cost of CPU overhead. Users must ensure that a= ny +pre-created storage source is cleared and thus reads all-zeroes before usi= ng +this option as otherwise the destination image may become corrupted. 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 po= ssibly diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-dom= ain.h index 6d4cc69c5d..9232ce2e6b 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -1245,7 +1245,10 @@ 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. This may increase CPU overhead of the migration. At t= he + * 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 t= his + * feature, otherwise the destination image may become corrupted. + * This may increase CPU overhead of the migration. At the * moment this is only supported by the QEMU driver but not for the tunnel= led * migration. * --=20 2.47.0