External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-23 06:05:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

kbase: improve disk image chains documentation

Browse Source 
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 <smitterl@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
This commit is contained in:
Sebastian Mitterle 2020-04-15 11:34:05 +00:00 committed by Peter Krempa
parent dc432f4ab7
commit 3ea711b9ec
1 changed files with 18 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/kbase/backing_chains.rst
View File

@ -38,13 +38,13 @@ image of the backing chain.
This configuration will prompt libvirt to detect the backing image of the source 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. image and recursively do the same thing until the end of the chain.
Importance of properly setup backing chain Importance of proper backing chain setup
------------------------------------------ ----------------------------------------
The disk image locations are used by libvirt to properly setup the security The disk image locations are used by libvirt to properly set up the security
system used on the host so that the hypervisor can access the files and possibly system used on the host so that the hypervisor can access the files; it can
also directly to configure the hypervisor to use the appropriate images. Thus also be used to configure the hypervisor to use the appropriate images. Thus
it's important to properly setup the formats and paths of the backing images. it's important to properly set up the formats and paths of the backing images.
Any externally created image should always use the -F switch of ``qemu-img`` Any externally created image should always use the -F switch of ``qemu-img``
to specify the format of the backing file to avoid probing. to specify the format of the backing file to avoid probing.
@ -60,7 +60,7 @@ explicitly in the XML or the overlay image itself.
Libvirt also might lack support for a network disk storage technology and thus 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 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 operations not being possible. To prevent this it's possible to specify the
image metadata explicitly in the XML. image metadata explicitly in the XML.
@ -104,7 +104,7 @@ An empty ``<backingStore/>`` element signals the end of the chain. Using this
will prevent libvirt or qemu from probing the backing chain. will prevent libvirt or qemu from probing the backing chain.
Note that it's also possible to partially specify the chain in the XML but omit 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 specified the terminating element. This will result in probing from the last specified
``<backingStore>`` ``<backingStore>``
Any image specified explicitly will not be probed for backing file or format. Any image specified explicitly will not be probed for backing file or format.
@ -120,10 +120,10 @@ means that the **-F** parameter of ``qemu-img`` must always be used.
:: ::
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
Note that if '/path/to/backing' is relative the path is considered relative to Note that if ``$BACKING_IMAGE_PATH`` is relative the path is considered relative to
the location of '/path/to/overlay'. the location of ``$IMAGE_PATH``.
Troubleshooting Troubleshooting
=============== ===============
@ -164,7 +164,7 @@ the image has a backing image format specified:
refcount bits: 16 refcount bits: 16
corrupt: false corrupt: false
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: specified properly. The image can be fixed by the following command:
:: ::
@ -177,22 +177,22 @@ If relative referencing of the backing image is desired, the path must be
relative to the location of image described by ``$IMAGE_PATH``. relative to the location of image described by ``$IMAGE_PATH``.
**Important:** If the ``$BACKING_IMAGE_FORMAT`` is not known it can be queried **Important:** If the ``$BACKING_IMAGE_FORMAT`` is not known it can be queried
using ``qemu-img info $BACKING_IMAGE_PATH`` and looking for the ``file format:`` using ``qemu-img info $BACKING_IMAGE_PATH`` and looking for the ``file format``
field, but for security reasons should be used *only* if at least one of the field, but for security reasons the value should be used *only* if at least one
following criteria is met: of the following criteria is met:
- ``file format`` is ``raw`` - ``file format`` is ``raw``
- ``backing file`` is NOT present - ``backing file`` is NOT present
- ``backing file`` is present AND is correct/trusted - ``backing file`` is present AND is correct/trusted
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 programatically. be scripted unless the trust for the image can be expressed programatically.
Also note that the above steps may need to be repeated recursively for any Also note that the above steps may need to be repeated recursively for any
subsequent backing images. subsequent backing images.
Missing images reported after after moving disk images into a different path Missing images reported after moving disk images into a different path
---------------------------------------------------------------------------- ----------------------------------------------------------------------
The path to the backing image which is recorded in the image metadata often 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-created contains a full path to the backing image. This is the default libvirt-created