diff options
Diffstat (limited to 'docs/system/deprecated.rst')
| -rw-r--r-- | docs/system/deprecated.rst | 58 |
1 files changed, 50 insertions, 8 deletions
diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst index 58a9aeb..971b65b 100644 --- a/docs/system/deprecated.rst +++ b/docs/system/deprecated.rst @@ -427,13 +427,37 @@ kernel in 2018, and has also been dropped from glibc. Related binaries ---------------- -``qemu-img convert -n -o`` (since 4.2.0) -'''''''''''''''''''''''''''''''''''''''' +qemu-img amend to adjust backing file (since 5.1) +''''''''''''''''''''''''''''''''''''''''''''''''' -All options specified in ``-o`` are image creation options, so -they have no effect when used with ``-n`` to skip image creation. -Silently ignored options can be confusing, so this combination of -options will be made an error in future versions. +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. + +qemu-img backing file without format (since 5.1) +'''''''''''''''''''''''''''''''''''''''''''''''' + +The use of ``qemu-img create``, ``qemu-img rebase``, or ``qemu-img +convert`` to create or modify an image that depends on a backing file +now recommends that an explicit backing format be provided. This is +for safety: if QEMU probes a different format than what you thought, +the data presented to the guest will be corrupt; similarly, presenting +a raw image to a guest allows a potential security exploit if a future +probe sees a non-raw image based on guest writes. + +To avoid the warning message, or even future refusal to create an +unsafe image, you must pass ``-o backing_fmt=`` (or the shorthand +``-F`` during create) to specify the intended backing format. You may +use ``qemu-img rebase -u`` to retroactively add a backing format to an +existing image. However, be aware that there are already potential +security risks to blindly using ``qemu-img info`` to probe the format +of an untrusted backing image, when deciding what format to add into +an existing image. Backwards compatibility ----------------------- @@ -540,8 +564,8 @@ spec you can use the ``-cpu rv64gcsu,priv_spec=v1.10.0`` command line argument. Related binaries ---------------- -``qemu-nbd --partition`` (removed in 5.0.0) -''''''''''''''''''''''''''''''''''''''''''' +``qemu-nbd --partition`` (removed in 5.0) +''''''''''''''''''''''''''''''''''''''''' The ``qemu-nbd --partition $digit`` code (also spelled ``-P``) could only handle MBR partitions, and never correctly handled logical @@ -557,6 +581,24 @@ can be rewritten as:: qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2 +``qemu-img convert -n -o`` (removed in 5.1) +''''''''''''''''''''''''''''''''''''''''''' + +All options specified in ``-o`` are image creation options, so +they are now rejected when used with ``-n`` to skip image creation. + + +``qemu-img create -b bad file $size`` (removed in 5.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +When creating an image with a backing file that could not be opened, +``qemu-img create`` used to issue a warning about the failure but +proceed with the image creation if an explicit size was provided. +However, as the ``-u`` option exists for this purpose, it is safer to +enforce that any failure to open the backing image (including if the +backing file is missing or an incorrect format was specified) is an +error when ``-u`` is not used. + Command line options -------------------- |