qcow2: Deprecate use of qemu-img amend to change backing file

The use of 'qemu-img amend' to change qcow2 backing files is not
tested very well.  In particular, our implementation has a bug where
if a new backing file is provided without a format, then the prior
format is blindly reused, even if this results in data corruption, but
this is not caught by iotests.

There are also situations where amending other options needs access to
the original backing file (for example, on a downgrade to a v2 image,
knowing whether a v3 zero cluster must be allocated or may be left
unallocated depends on knowing whether the backing file already reads
as zero), but the command line does not have a nice way to tell us
both the backing file to use for opening the image as well as the
backing file to install after the operation is complete.

Even if we do allow changing the backing file, it is redundant with
the existing ability to change backing files via 'qemu-img rebase -u'.
It is time to deprecate this support (leaving the existing behavior
intact, even if it is buggy), and at a point in the future, require
the use of only 'qemu-img rebase' for adjusting backing chain
relations, saving 'qemu-img amend' for changes unrelated to the
backing chain.

Signed-off-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200706203954.341758-8-eblake@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>

diff --git a/block/qcow2.c b/block/qcow2.c
index ea33673c552c57091e62e950e38701d71300a06c..f3fc2707cdcf7497dfe1dba26276e77aa4891c9e 100644 (file)
--- a/block/qcow2.c
+++ b/block/qcow2.c
@@ -5511,6 +5511,11 @@ static int qcow2_amend_options(BlockDriverState *bs, QemuOpts *opts,
     }
 
     if (backing_file || backing_format) {
+        if (g_strcmp0(backing_file, s->image_backing_file) ||
+            g_strcmp0(backing_format, s->image_backing_format)) {
+            warn_report("Deprecated use of amend to alter the backing file; "
+                        "use qemu-img rebase instead");
+        }
         ret = qcow2_change_backing_file(bs,
                     backing_file ?: s->image_backing_file,
                     backing_format ?: s->image_backing_format);

diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
index c014e049c3188516af2dbdf90d9d723d14590cd5..c1f019b9d204de76e5e60d65fbd5de12ed2515a8 100644 (file)
--- a/docs/system/deprecated.rst
+++ b/docs/system/deprecated.rst
@@ -427,6 +427,18 @@ kernel in 2018, and has also been dropped from glibc.
 Related binaries
 ----------------
 
+qemu-img amend to adjust backing file (since 5.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''
+
+The use of ``qemu-img amend`` to modify the name or format of a qcow2
+backing image is deprecated; this functionality was never fully
+documented or tested, and interferes with other amend operations that
+need access to the original backing image (such as deciding whether a
+v3 zero cluster may be left unallocated when converting to a v2
+image).  Rather, any changes to the backing chain should be performed
+with ``qemu-img rebase -u`` either before or after the remaining
+changes being performed by amend, as appropriate.
+
 Backwards compatibility
 -----------------------
 

diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst
index e33f5575e35d8cc5ca1c8d8ecb6ed69dc1d08d85..c35bd6482203d32f2a54b5b72d9bb8aa2d1de7c4 100644 (file)
--- a/docs/tools/qemu-img.rst
+++ b/docs/tools/qemu-img.rst
@@ -258,6 +258,10 @@ Command description:
   Amends the image format specific *OPTIONS* for the image file
   *FILENAME*. Not all file formats support this operation.
 
+  The set of options that can be amended are dependent on the image
+  format, but note that amending the backing chain relationship should
+  instead be performed with ``qemu-img rebase``.
+
   --force allows some unsafe operations. Currently for -f luks, it allows to
   erase the last encryption key, and to overwrite an active encryption key.
 

diff --git a/tests/qemu-iotests/061.out b/tests/qemu-iotests/061.out
index b0f8befe30cdf015a8960335473a4a804ccb3cbe..44e3c624f940f245d03ca607bfad72647cf7a922 100644 (file)
--- a/tests/qemu-iotests/061.out
+++ b/tests/qemu-iotests/061.out
@@ -370,6 +370,7 @@ wrote 131072/131072 bytes at offset 0
 128 KiB, X ops; XX:XX:XX.X (XXX YYY/sec and XXX ops/sec)
 read 131072/131072 bytes at offset 0
 128 KiB, X ops; XX:XX:XX.X (XXX YYY/sec and XXX ops/sec)
+qemu-img: warning: Deprecated use of amend to alter the backing file; use qemu-img rebase instead
 read 131072/131072 bytes at offset 0
 128 KiB, X ops; XX:XX:XX.X (XXX YYY/sec and XXX ops/sec)
 No errors were found on the image.

diff --git a/tests/qemu-iotests/082.out b/tests/qemu-iotests/082.out
index f7b3d54b28420b1ff34f0b2356907f5f5ca1ba6c..a38a26fc5797cc25ded159d74cee52a0012388c1 100644 (file)
--- a/tests/qemu-iotests/082.out
+++ b/tests/qemu-iotests/082.out
@@ -783,10 +783,12 @@ Amend options for 'qcow2':
   size=<size>            - Virtual disk size
 
 Testing: amend -f qcow2 -o backing_file=TEST_DIR/t.qcow2,,help TEST_DIR/t.qcow2
+qemu-img: warning: Deprecated use of amend to alter the backing file; use qemu-img rebase instead
 
 Testing: rebase -u -b  -f qcow2 TEST_DIR/t.qcow2
 
 Testing: amend -f qcow2 -o backing_file=TEST_DIR/t.qcow2,,? TEST_DIR/t.qcow2
+qemu-img: warning: Deprecated use of amend to alter the backing file; use qemu-img rebase instead
 
 Testing: rebase -u -b  -f qcow2 TEST_DIR/t.qcow2