From nobody Mon Sep 8 17:06:06 2025 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=pass(p=reject dis=none) header.from=lists.libvirt.org ARC-Seal: i=1; a=rsa-sha256; t=1756303837; cv=none; d=zohomail.com; s=zohoarc; b=X4ZYsW+8GcKuqWq58hU/qFQlVOih0D3Cb1Ml5iUEgAhrWRqSeoqtUcaqNEiMOeVdMs0mOrtzNRV/9O66tAPjxj5wwox9qcLjoPD8VAn1dXYOQP7vZqAuH3xxsToQCUkH+rCYB6bXV3z5c53i2XSFchUv09+YxSOQYcV3lp3Qg/k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1756303837; h=Content-Type:Content-Transfer-Encoding:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Owner:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:Reply-To:References:Subject:Subject:To:To:Message-Id:Cc; bh=weW5dLlMR3gUk3m5J+rUr1plCmTbgd6AjzoNzaA7GD8=; b=FLF3WZFJrzZL0YfV8WbJ1vswLvBIWdopJRRFFKXPEeHS1tbOna6uDtax+oClXEWTB0Gm1fEjxtHkbiwFhxsgxnHUQq/rK5IvXaf1cetweFsiVop+YLFPhAcsva7LG6ec3Lyvb3+NM2ZkmGCNUTiKXp7QVrfeSrnsrFCpEMogOT0= ARC-Authentication-Results: i=1; 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=pass header.from= (p=reject dis=none) Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 175630383751421.377278263718154; Wed, 27 Aug 2025 07:10:37 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 993) id 6C07044068; Wed, 27 Aug 2025 10:10:36 -0400 (EDT) Received: from [172.19.199.3] (lists.libvirt.org [8.43.85.245]) by lists.libvirt.org (Postfix) with ESMTP id 829504417F; Wed, 27 Aug 2025 09:51:38 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 993) id 6F3CF4405B; Wed, 27 Aug 2025 09:51:23 -0400 (EDT) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (3072 bits) server-digest SHA256) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 42BCD43F8D for ; Wed, 27 Aug 2025 09:51:19 -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-271-iLKxdzbPPdap-BBGnhYedg-1; Wed, 27 Aug 2025 09:51:16 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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 009D7195608D for ; Wed, 27 Aug 2025 13:51:16 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.44.22.3]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 3CBD118003FC for ; Wed, 27 Aug 2025 13:51:15 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 4.0.1 (2024-03-26) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-1.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, MAILING_LIST_MULTI,RCVD_IN_DNSWL_LOW, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_PASS autolearn=unavailable autolearn_force=no version=4.0.1 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1756302678; 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=weW5dLlMR3gUk3m5J+rUr1plCmTbgd6AjzoNzaA7GD8=; b=gjS/n17rhZmeRQY9bzhYwt5qgj4Tn32tyg0pEp67zp1oTrycsupjXDHOqWLU6sBFDCAYdN eZLQNLl9LigCwH+eueWksDacKqr+UzUKEbI0iy2vKu1uRi8LGgViko9aWQUH+m9pV0WdCI DI36zNQDSLtC2dXE6VRjrx7GAjvDPlw= X-MC-Unique: iLKxdzbPPdap-BBGnhYedg-1 X-Mimecast-MFC-AGG-ID: iLKxdzbPPdap-BBGnhYedg_1756302676 To: devel@lists.libvirt.org Subject: [PATCH 4/4] kbase: live_full_disk_backup: Improve the document Date: Wed, 27 Aug 2025 15:51:08 +0200 Message-ID: <5b121a55c955ce35ddcb093e0e2dc31b3aef09fc.1756302563.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: n_tWKQbOHsWSV61bn8wSxXt1Cty5CSk5HvfGImQZmdg_1756302676 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: OVZYZ6RJS2KJHUF25IW4PG2EDWUCMODM X-Message-ID-Hash: OVZYZ6RJS2KJHUF25IW4PG2EDWUCMODM X-MailFrom: pkrempa@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; header-match-devel.lists.libvirt.org-0; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: From: Peter Krempa via Devel Reply-To: Peter Krempa X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1756303840323124100 Content-Type: text/plain; charset="utf-8" From: Peter Krempa Changes: - fixed emphasis on the API name and some operations - fixed the output example of some commands - added warning to avoid the snapshot+copy+commit approach as it's a bit dangerous - added --no-metadata to avoid creating snapshot XML Signed-off-by: Peter Krempa --- docs/kbase/live_full_disk_backup.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/kbase/live_full_disk_backup.rst b/docs/kbase/live_full_di= sk_backup.rst index c545aa3009..be95d9d2e2 100644 --- a/docs/kbase/live_full_disk_backup.rst +++ b/docs/kbase/live_full_disk_backup.rst @@ -13,7 +13,7 @@ that using libvirt's APIs. This method involves concepts= : the notion of `backing chains `_, `QCOW2 overlays `_, -and a special operation called "active block-commit", which allows +and a special operation called *active block-commit*, which allows live-merging an overlay disk image into its backing file. Two kinds of backup: "push" and "pull" @@ -43,7 +43,7 @@ This document covers only the full backups using the "pus= h" mode. Full disk backup using "push" mode =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -The below approach uses the modern backup API, virDomainBackupBegin(). +The below approach uses the modern backup API, ``virDomainBackupBegin()``. This requires libvirt-7.2.0 and QEMU-4.2, or higher versions. #. Start the guest:: @@ -92,8 +92,13 @@ This is the alternative in case you cannot use libvirt-7= .2.0 and QEMU-4.2 for some reason. But this assumes you're using *at least* QEMU 2.1 and libvirt-1.2.9. +.. warning:: + We strongly suggest that the backup api (``virsh backup-begin``) is used + as it doesn't require deleting files as deleting a wrong file can lead + to data loss. + This backup approach is slightly more involved, and predates the -virDomainBackupBegin() API: Assuming a guest with a single disk image, +``virDomainBackupBegin()`` API: Assuming a guest with a single disk image, create a temporary live QCOW2 overlay (commonly called as "external snapshot") to track the live guest writes. Then backup the original disk image while the guest (live QEMU) keeps writing to the temporary @@ -120,7 +125,7 @@ it. $ virsh snapshot-create-as --domain vm1 overlay1 \ --diskspec vda,file=3D/var/lib/libvirt/images/overlay1.qcow2 \ - --disk-only + --disk-only --no-metadata The disk image chain looks as follows:: @@ -141,8 +146,7 @@ it. #. Now, take a backup the original image, ``base.raw``, to a different location using ``cp`` or ``rsync``:: - $ cp /var/lib/libvirt/images/base.raw - /export/backups/copy1_base.raw + $ cp /var/lib/libvirt/images/base.raw /export/backups/copy1_base.raw # Or: @@ -156,7 +160,7 @@ it. $ virsh domblklist vm1 Target Source ------------------------------------------------ - vda vda,file=3D/var/lib/libvirt/images/overlay1.qcow2 + vda /var/lib/libvirt/images/overlay1.qcow2 #. Once the backup of the original image completes, now perform the "active block-commit" to live-merge the contents of --=20 2.51.0