1763105 – doc: Missing manual for option data-file,data-file-raw in qemu-img

RHEL Engineering is moving the tracking of its product development work on RHEL 6 through RHEL 9 to Red Hat Jira (issues.redhat.com). If you're a Red Hat customer, please continue to file support cases via the Red Hat customer portal. If you're not, please head to the "RHEL project" in Red Hat Jira and file new tickets here. Individual Bugzilla bugs in the statuses "NEW", "ASSIGNED", and "POST" are being migrated throughout September 2023. Bugs of Red Hat partners with an assigned Engineering Partner Manager (EPM) are migrated in late September as per pre-agreed dates. Bugs against components "kernel", "kernel-rt", and "kpatch" are only migrated if still in "NEW" or "ASSIGNED". If you cannot log in to RH Jira, please consult article #7032570. That failing, please send an e-mail to the RH Jira admins at rh-issues@redhat.com to troubleshoot your issue as a user management inquiry. The email creates a ServiceNow ticket with Red Hat. Individual Bugzilla bugs that are migrated will be moved to status "CLOSED", resolution "MIGRATED", and set with "MigratedToJIRA" in "Keywords". The link to the successor Jira issue will be found under "Links", have a little "two-footprint" icon next to it, and direct you to the "RHEL project" in Red Hat Jira (issue links are of type "https://issues.redhat.com/browse/RHEL-XXXX", where "X" is a digit). This same link will be available in a blue banner at the top of the page informing you that that bug has been migrated.

Bug 1763105 - doc: Missing manual for option data-file,data-file-raw in qemu-img

Summary: doc: Missing manual for option data-file,data-file-raw in qemu-img

Keywords:
Status:	CLOSED CURRENTRELEASE
Alias:	None
Product:	Red Hat Enterprise Linux 8
Classification:	Red Hat
Component:	qemu-kvm
Sub Component:
Version:	---
Hardware:	Unspecified
OS:	Unspecified
Priority:	low
Severity:	low
Target Milestone:	rc
Target Release:	8.6
Assignee:	John Ferlan
QA Contact:	Tingting Mao
Docs Contact:
URL:
Whiteboard:
Depends On:	1997410
Blocks:	2001315
TreeView+	depends on / blocked

Reported:	2019-10-18 09:12 UTC by Han Han
Modified:	2021-12-07 22:45 UTC (History)
CC List:	5 users (show)
Fixed In Version:
Doc Type:	If docs needed, set a value
Doc Text:
Clone Of:
Clones:	2001315 (view as bug list)
Environment:
Last Closed:	2021-09-17 08:06:57 UTC
Type:	Bug
Target Upstream Version:
Embargoed:
Dependent Products:

Attachments	(Terms of Use)

Description Han Han 2019-10-18 09:12:09 UTC

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:

Comment 1 Han Han 2019-10-18 09:14:12 UTC

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

Comment 2 Han Han 2019-10-21 01:20:57 UTC

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

Comment 3 Ademar Reis 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

Comment 7 Connor Kuehl 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.

Comment 9 Connor Kuehl 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"

Comment 10 John Ferlan 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 12 Tingting Mao 2021-09-17 08:06:57 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.
.......

Comment 13 Tingting Mao 2021-09-17 11:28:00 UTC

(In reply to Tingting Mao from comment #12)
> Verified this bug as below.
> 
> 
> Tested with:
> qemu-kvm-6.1.0-2.el9
> kernel-5.14.0-0.rc7.54.el9.x86_64
> 
Sorry. The env should be:
qemu-kvm-6.1.0-1.module+el8.6.0+12648+6ede71a5
kernel-4.18.0-342.el8.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.
> .......

Note You need to log in before you can comment on or make changes to this bug.