From nobody Mon Feb 9 00:20:51 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) client-ip=205.139.110.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1586950491; cv=none; d=zohomail.com; s=zohoarc; b=J6unLb/Bv369t29jnHfrQiTOjyH8yQqrg/UxJZskvzuReuH7y6P4sJk/m8A7xDRCxFm5I6fdfcNLlExNOXN1HurQuI/EenGTbSpfEE/bqwl4AQ2nwfERRJZWdkWXgQiZApBmE1zQ5KWDwSdfFO6Z2C/jls3nKlpC2jAqYsHIiFc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1586950491; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=hBua4ZfPFRu54CQmy6VbZI8CklmrT1DBxn/tLksXMp0=; b=O9AE1P5iymVf5j8lkgNEJByvmwcZA20M8vjcym4RZF6sqXdYUxV9SGhSHE6BFCd2ov6Wf9Ujn/Ugnw3qhdOSaDXnBGeAv160uZRFMfTRPIB9G2r3qWdP9h9ghLFVVGI/8mqMG6otzqCN9jH/g0BdCPzXfKdVoC4BoT7p1nLDqtg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by mx.zohomail.com with SMTPS id 1586950491091445.9071291870829; Wed, 15 Apr 2020 04:34:51 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-492-qhKiVrXBObe2_Mv2O25YVw-1; Wed, 15 Apr 2020 07:34:47 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 62EA413FA; Wed, 15 Apr 2020 11:34:42 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 319F26EF92; Wed, 15 Apr 2020 11:34:42 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id CDE9F18089CF; Wed, 15 Apr 2020 11:34:41 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 03FBYNLJ026206 for ; Wed, 15 Apr 2020 07:34:23 -0400 Received: by smtp.corp.redhat.com (Postfix) id 224B2116D9F; Wed, 15 Apr 2020 11:34:23 +0000 (UTC) Received: from localhost.localdomain (ovpn-112-140.ams2.redhat.com [10.36.112.140]) by smtp.corp.redhat.com (Postfix) with ESMTP id ECEFE6EF92; Wed, 15 Apr 2020 11:34:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1586950489; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=hBua4ZfPFRu54CQmy6VbZI8CklmrT1DBxn/tLksXMp0=; b=I9vCLCm3y04894KyFCHkVgsV4qo0sjZH90YPK+cjZZlCBr0mZe4b7JOCiUoofn5aeXRhDl Dq5ROeRBQz8y5S35FScJRmZSxxATC5NJJaFLrkCEi5nPpdL3HvBCKPwDmE1YiaxoiZ6YnQ wl3cTPkAY08g6EQrGXL6i6uKaeZ9oiA= X-MC-Unique: qhKiVrXBObe2_Mv2O25YVw-1 From: Sebastian Mitterle To: libvir-list@redhat.com Subject: [PATCH 2/3] Improve Disk image chains documentation Date: Wed, 15 Apr 2020 11:34:05 +0000 Message-Id: <20200415113406.34823-3-smitterl@redhat.com> In-Reply-To: <20200415113406.34823-1-smitterl@redhat.com> References: <20200415113406.34823-1-smitterl@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Cc: Sebastian Mitterle X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" 1. Use 'setup' consistently as noun, 'set up' as verb 2. Use path variables like '$IMAGE_PATH' consistently like in Troubleshooting to improve readability 3. Remove ':' from field names 4. Change phrasing in sentences I stumbled upon several times to improve readability. 5. Minor grammar/vocab fixes. Signed-off-by: Sebastian Mitterle Reviewed-by: Peter Krempa --- docs/kbase/backing_chains.rst | 36 +++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/kbase/backing_chains.rst b/docs/kbase/backing_chains.rst index af848ccb14..c112f2bc82 100644 --- a/docs/kbase/backing_chains.rst +++ b/docs/kbase/backing_chains.rst @@ -38,13 +38,13 @@ image of the backing chain. This configuration will prompt libvirt to detect the backing image of the = source image and recursively do the same thing until the end of the chain. =20 -Importance of properly setup backing chain ------------------------------------------- +Importance of proper backing chain setup +---------------------------------------- =20 -The disk image locations are used by libvirt to properly setup the security -system used on the host so that the hypervisor can access the files and po= ssibly -also directly to configure the hypervisor to use the appropriate images. T= hus -it's important to properly setup the formats and paths of the backing imag= es. +The disk image locations are used by libvirt to properly set up the securi= ty +system used on the host so that the hypervisor can access the files; it can +also be used to configure the hypervisor to use the appropriate images. Th= us +it's important to properly set up the formats and paths of the backing ima= ges. =20 Any externally created image should always use the -F switch of ``qemu-img= `` to specify the format of the backing file to avoid probing. @@ -60,7 +60,7 @@ explicitly in the XML or the overlay image itself. =20 Libvirt also might lack support for a network disk storage technology and = thus may be unable to visit and detect backing chains on such storage. This may -result in the backing chain present in the live XML to look incomplete or = some +result in the backing chain in the live XML looking incomplete or some operations not being possible. To prevent this it's possible to specify the image metadata explicitly in the XML. =20 @@ -104,7 +104,7 @@ An empty ```` element signals the end of= the chain. Using this will prevent libvirt or qemu from probing the backing chain. =20 Note that it's also possible to partially specify the chain in the XML but= omit -the terminating element. This will result into probing from the last speci= fied +the terminating element. This will result in probing from the last specifi= ed ```` =20 Any image specified explicitly will not be probed for backing file or form= at. @@ -120,10 +120,10 @@ means that the **-F** parameter of ``qemu-img`` must = always be used. =20 :: =20 - qemu-img -f qcow2 -F qcow2 -b /path/to/backing /path/to/overlay + qemu-img -f qcow2 -F qcow2 -b $BACKING_IMAGE_PATH $IMAGE_PATH =20 -Note that if '/path/to/backing' is relative the path is considered relativ= e to -the location of '/path/to/overlay'. +Note that if ``$BACKING_IMAGE_PATH`` is relative the path is considered re= lative to +the location of ``$IMAGE_PATH``. =20 Troubleshooting =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -164,7 +164,7 @@ the image has a backing image format specified: refcount bits: 16 corrupt: false =20 -If the ``backing file format:`` field is missing above the format was not +If the ``backing file format`` field is missing above the format was not specified properly. The image can be fixed by the following command: =20 :: @@ -177,22 +177,22 @@ If relative referencing of the backing image is desir= ed, the path must be relative to the location of image described by ``$IMAGE_PATH``. =20 **Important:** If the ``$BACKING_IMAGE_FORMAT`` is not known it can be que= ried -using ``qemu-img info $BACKING_IMAGE_PATH`` and looking for the ``file for= mat:`` -field, but for security reasons should be used *only* if at least one of t= he -following criteria is met: +using ``qemu-img info $BACKING_IMAGE_PATH`` and looking for the ``file for= mat`` +field, but for security reasons the value should be used *only* if at leas= t one +of the following criteria is met: =20 - ``file format`` is ``raw`` - ``backing file`` is NOT present - ``backing file`` is present AND is correct/trusted =20 -Note that the last criteria may require manual inspection and thus should = not +Note that the last criterion may require manual inspection and thus should= not be scripted unless the trust for the image can be expressed programaticall= y. =20 Also note that the above steps may need to be repeated recursively for any subsequent backing images. =20 -Missing images reported after after moving disk images into a different pa= th ---------------------------------------------------------------------------= -- +Missing images reported after moving disk images into a different path +---------------------------------------------------------------------- =20 The path to the backing image which is recorded in the image metadata often contains a full path to the backing image. This is the default libvirt-cre= ated --=20 2.25.2