Bug 2001315

Summary: doc: Missing manual for option data-file,data-file-raw in qemu-img
Product: Red Hat Enterprise Linux 9 Reporter: John Ferlan <jferlan>
Component: qemu-kvmAssignee: John Ferlan <jferlan>
qemu-kvm sub component: qcow2 QA Contact: Tingting Mao <timao>
Status: CLOSED CURRENTRELEASE Docs Contact:
Severity: low    
Priority: low CC: coli, hhan, jinzhao, juzhang, timao, virt-maint, xuwei
Version: 9.0Keywords: Documentation, EasyFix, ManPageChange, Triaged
Target Milestone: rc   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: 1763105 Environment:
Last Closed: 2021-09-17 08:25:52 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:
Bug Depends On: 1763105, 1997408    
Bug Blocks:    

Description John Ferlan 2021-09-05 13:49:12 UTC 
+++ This bug was initially created as a clone of Bug #1763105 +++

Description of problem:
As subject

Version-Release number of selected component (if applicable):
qemu-kvm-4.1.0-13.module+el8.1.0+4313+ef76ec61.x86_64

How reproducible:
100%

Steps to Reproduce:
# man qemu-img|grep data-file

Nothing got.

Actual results:


Expected results:


Additional info:

--- Additional comment from Han Han on 2019-10-18 09:14:12 UTC ---

These two options are introduce since qemu 4.0:
https://github.com/qemu/qemu/commit/9b890bdcb6ec11868da92c1daeb51c69d9483da8

--- Additional comment from Han Han on 2019-10-21 01:20:57 UTC ---

Patches: https://lists.nongnu.org/archive/html/qemu-block/2019-10/msg01254.html

--- Additional comment from Ademar Reis on 2020-02-05 23:07:26 UTC ---

QEMU has been recently split into sub-components and as a one-time operation to avoid breakage of tools, we are setting the QEMU sub-component of this BZ to "General". Please review and change the sub-component if necessary the next time you review this BZ. Thanks

--- Additional comment from Ademar Reis on 2020-02-26 16:45:59 UTC ---

We should get this upstream and then inherit it in a rebase.

--- Additional comment from RHEL Program Management on 2020-11-05 19:09:50 UTC ---

pm_ack is no longer used for this product. The flag has been reset.

See https://issues.redhat.com/browse/PTT-1821 for additional details or contact lmiksik if you have any questions.

--- Additional comment from RHEL Program Management on 2021-01-06 00:01:27 UTC ---

Interal Target Release is empty so release+ was unset

--- Additional comment from Connor Kuehl on 2021-03-01 17:39:31 UTC ---

I've resubmitted this change upstream: https://lists.gnu.org/archive/html/qemu-devel/2021-03/msg00280.html

I think the test case in the opening comment could be updated to something like this:

$ man qemu-img | grep data_file

Since it appears the options are documented with underscores.

--- Additional comment from John Ferlan on 2021-03-06 15:52:47 UTC ---

Extend stale date +6 months since patches are upstream and should make next release which will be rebased into RHEL-AV 8.5.0

--- Additional comment from Connor Kuehl on 2021-05-18 13:44:12 UTC ---

This is now included in upstream as commit: d65173f924 "Document qemu-img options data_file and data_file_raw"

--- Additional comment from John Ferlan on 2021-09-05 13:47:57 UTC ---

Move to RHEL since RHEL-AV will only be a rebuild of RHEL starting w/ 8.6.0

Added the RHEL rebase bz to depends on list
Comment 2 Tingting Mao 2021-09-17 08:25:52 UTC 
Verified this bug as below.


Tested with:
qemu-kvm-6.1.0-2.el9
kernel-5.14.0-0.rc7.54.el9.x86_64


Steps:
# man qemu-img
......
......
          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 con‐
                 sistent 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 by‐
                 pass 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 arbi‐
                 trary 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  for‐
                 warded  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.
.......