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:


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.