[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 10/19] Document qemu-img options data_file and data_file_raw
From: |
Max Reitz |
Subject: |
[PULL 10/19] Document qemu-img options data_file and data_file_raw |
Date: |
Fri, 14 May 2021 18:45:05 +0200 |
From: Connor Kuehl <ckuehl@redhat.com>
The contents of this patch were initially developed and posted by Han
Han[1], however, it appears the original patch was not applied. Since
then, the relevant documentation has been moved and adapted to a new
format.
I've taken most of the original wording and tweaked it according to
some of the feedback from the original patch submission. I've also
adapted it to restructured text, which is the format the documentation
currently uses.
[1] https://lists.nongnu.org/archive/html/qemu-block/2019-10/msg01253.html
Fixes: https://bugzilla.redhat.com/1763105
Signed-off-by: Han Han <hhan@redhat.com>
Suggested-by: Max Reitz <mreitz@redhat.com>
[ Max: provided description of data_file_raw behavior ]
Signed-off-by: Connor Kuehl <ckuehl@redhat.com>
Message-Id: <20210505195512.391128-1-ckuehl@redhat.com>
Signed-off-by: Max Reitz <mreitz@redhat.com>
---
docs/tools/qemu-img.rst | 31 +++++++++++++++++++++++++++++++
1 file changed, 31 insertions(+)
diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst
index c9efcfaefc..cfe1147879 100644
--- a/docs/tools/qemu-img.rst
+++ b/docs/tools/qemu-img.rst
@@ -866,6 +866,37 @@ Supported image file formats:
issue ``lsattr filename`` to check if the NOCOW flag is set or not
(Capital 'C' is NOCOW flag).
+ ``data_file``
+ Filename where all guest data will be stored. If this option is used,
+ the qcow2 file will only contain the image's metadata.
+
+ Note: Data loss will occur if the given filename already exists when
+ using this option with ``qemu-img create`` since ``qemu-img`` will create
+ the data file anew, overwriting the file's original contents. To simply
+ update the reference to point to the given pre-existing file, use
+ ``qemu-img amend``.
+
+ ``data_file_raw``
+ If this option is set to ``on``, QEMU will always keep the external data
+ file consistent as a standalone read-only raw image.
+
+ It does this by forwarding all write accesses to the qcow2 file through to
+ the raw data file, including their offsets. Therefore, data that is visible
+ on the qcow2 node (i.e., to the guest) at some offset is visible at the
same
+ offset in the raw data file. This results in a read-only raw image. Writes
+ that bypass the qcow2 metadata may corrupt the qcow2 metadata because the
+ out-of-band writes may result in the metadata falling out of sync with the
+ raw image.
+
+ If this option is ``off``, QEMU will use the data file to store data in an
+ arbitrary manner. The file’s content will not make sense without the
+ accompanying qcow2 metadata. Where data is written will have no relation to
+ its offset as seen by the guest, and some writes (specifically zero writes)
+ may not be forwarded to the data file at all, but will only be handled by
+ modifying qcow2 metadata.
+
+ This option can only be enabled if ``data_file`` is set.
+
``Other``
QEMU also supports various other image file formats for
--
2.31.1
- [PULL 06/19] qemu-iotests: allow passing unittest.main arguments to the test scripts, (continued)
- [PULL 06/19] qemu-iotests: allow passing unittest.main arguments to the test scripts, Max Reitz, 2021/05/14
- [PULL 05/19] qemu-iotests: do not buffer the test output, Max Reitz, 2021/05/14
- [PULL 09/19] qemu-iotests: fix case of SOCK_DIR already in the environment, Max Reitz, 2021/05/14
- [PULL 07/19] qemu-iotests: move command line and environment handling from TestRunner to TestEnv, Max Reitz, 2021/05/14
- [PULL 03/19] monitor: hmp_qemu_io: acquire aio contex, fix crash, Max Reitz, 2021/05/14
- [PULL 08/19] qemu-iotests: let "check" spawn an arbitrary test command, Max Reitz, 2021/05/14
- [PULL 12/19] qemu-iotests: fix pylint 2.8 consider-using-with error, Max Reitz, 2021/05/14
- [PULL 11/19] block/copy-on-read: use bdrv_drop_filter() and drop s->active, Max Reitz, 2021/05/14
- [PULL 10/19] Document qemu-img options data_file and data_file_raw,
Max Reitz <=
- [PULL 14/19] block: drop write notifiers, Max Reitz, 2021/05/14
- [PULL 13/19] block/write-threshold: don't use write notifiers, Max Reitz, 2021/05/14
- [PULL 15/19] test-write-threshold: rewrite test_threshold_(not_)trigger tests, Max Reitz, 2021/05/14
- [PULL 16/19] block/write-threshold: drop extra APIs, Max Reitz, 2021/05/14
- [PULL 17/19] test-write-threshold: drop extra tests, Max Reitz, 2021/05/14
- [PULL 18/19] test-write-threshold: drop extra TestStruct structure, Max Reitz, 2021/05/14
- [PULL 19/19] write-threshold: deal with includes, Max Reitz, 2021/05/14
- Re: [PULL 00/19] Block patches, Peter Maydell, 2021/05/17