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 1494210 - Document image locking in the qemu-img manpage
Summary: Document image locking in the qemu-img manpage
Keywords:
Status: CLOSED ERRATA
Alias: None
Product: Red Hat Enterprise Linux 7
Classification: Red Hat
Component: qemu-kvm-rhev
Version: 7.5
Hardware: Unspecified
OS: Unspecified
medium
medium
Target Milestone: rc
: ---
Assignee: Fam Zheng
QA Contact: Tingting Mao
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2017-09-21 16:47 UTC by Ademar Reis
Modified: 2018-11-01 11:01 UTC (History)
11 users (show)

Fixed In Version: qemu-kvm-rhev-2.12.0-1.el7
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2018-11-01 11:01:10 UTC
Target Upstream Version:
Embargoed:

Attachments (Terms of Use)

Description Ademar Reis 2017-09-21 16:47:50 UTC 
There's no documentation about image locking in the qemu-img manpage. The only commit I see in the image locking series is the update of -U option, but there's no documentation for --force-share and, perhaps more importantly, the man page contains this warning in the very beginning:

       Warning: Never use qemu-img to modify images in use by a running
       virtual machine or any other process; this may destroy the image.
       Also, be aware that querying an image that is being modified by
       another process may encounter inconsistent state.

I believe this text should be updated to reflect the introduction of locks which are enabled by default.

I also anticipate people looking at the manpage if something breaks, so perhaps there should be a section about how the lock works, the reasons for it and how to bypass it.

There's nothing about image locking in qemu(1) either.
Comment 1 Ping Li 2017-11-22 08:09:31 UTC 
qemu-img could get information from a raw format image, even if it is opened by QEMU. Fam gave the explanation as below. I think it should also be added in the qemu-img manpage, which will make a better understanding for users. Thanks

Because it is "safe" to get these information, so qemu-img doesn't need to acquire lock the same as qcow2. Operation "info" doesn't do I/O. The reason qcow2 is not allowed is because metadata has to be read from the image file, and it is not safe if the image is being used by the VM, because it may update metadata while we read it, resulting in inconsistent or wrong output.
Comment 2 yilzhang 2017-11-24 02:52:40 UTC 
Add one more:
qemu-img could get information from an iSCSI backend image, even if it is opened by QEMU. I think this should also be added in qemu-img manpage.
Comment 3 Fam Zheng 2017-11-24 03:17:02 UTC 
Proposed document change upstream:

https://lists.gnu.org/archive/html/qemu-devel/2017-11/msg04421.html

Yiling, please take a look and your feedback is welcome!
Comment 4 Miroslav Rezanina 2017-12-05 12:58:49 UTC 
Fix included in qemu-kvm-rhev-2.10.0-11.el7
Comment 6 yilzhang 2017-12-06 05:25:45 UTC 
(In reply to Fam Zheng from comment #3)
> Proposed document change upstream:
> 
> https://lists.gnu.org/archive/html/qemu-devel/2017-11/msg04421.html
> 
> Yiling, please take a look and your feedback is welcome!

It looks OK for me, thanks.
Comment 7 Ping Li 2017-12-07 08:40:21 UTC 
Image file locking, and block device options share-rw and file.locking have been introduced in the qemu-doc added by commit c83bac681b. However the qemu-img option "-U" is simply added in qemu-img-cmds.hx without explanation in the qemu-img.texi. 


We could get the introduction from upstream User Documentation or internal doc.

Upstream:
https://qemu.weilnetz.de/doc/qemu-doc.html#disk_005fimage_005flocking

Downstream:
/usr/share/doc/qemu-kvm/qemu-doc.html
Comment 8 Fam Zheng 2018-01-17 06:14:02 UTC 
Upstream patches to address comment 7:

https://lists.gnu.org/archive/html/qemu-devel/2017-12/msg05082.html
Comment 9 Fam Zheng 2018-01-29 06:17:28 UTC 
The latest patch for upstream:

https://lists.gnu.org/archive/html/qemu-devel/2018-01/msg00631.html
Comment 10 Fam Zheng 2018-02-26 05:38:25 UTC 
Moving to 7.6 since it's docs supplementary update only.
Comment 13 Tingting Mao 2018-07-06 03:29:52 UTC 
Check the qemu-img manpage, the below description is added:

Warning: Never use qemu-img to modify images in use by a running virtual machine or any other process; this may destroy the image. Also, be aware that querying an image that is being modified by another process may encounter inconsistent state.

--force-share (-U)
  If specified, "qemu-img" will open the image in shared mode, allowing other QEMU processes to open it in write mode. For example, this can be used to get the image information (with 'info' subcommand) when the image is used by a running guest. Note that this could produce inconsistent results because of concurrent metadata changes, etc. This option is only allowed when opening images in read-only mode.


Hi Fam,

In the --force-share (-U) part, you mentioned "This option is only allowed when opening images in read-only mode.". However, while I execute 'dd' to write data to a running image, I could get the info with -U option successfully.

In my side, the description is still confusing. Please correct me if there is something wrong.

Thanks
Comment 14 Fam Zheng 2018-07-10 06:01:52 UTC 
You are opening the image in read-only mode with 'info', which matches what the manpage says. "dd" in your case, or a QEMU running VM, may be using the image in read-write mode. The manpage is talking about qemu-img commands being invoked.
Comment 15 Tingting Mao 2018-07-10 07:15:58 UTC 
Clear now, thanks for Fam's information.

According to the comment 13, set the bug as verified.
Comment 17 errata-xmlrpc 2018-11-01 11:01:10 UTC 
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHBA-2018:3443
Note You need to log in before you can comment on or make changes to this bug.