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.
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.
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.
Proposed document change upstream:
Yiling, please take a look and your feedback is welcome!
Fix included in qemu-kvm-rhev-2.10.0-11.el7
(In reply to Fam Zheng from comment #3)
> Proposed document change upstream:
> Yiling, please take a look and your feedback is welcome!
It looks OK for me, thanks.
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 patches to address comment 7:
The latest patch for upstream:
Moving to 7.6 since it's docs supplementary update only.
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.
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.
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.
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.
Clear now, thanks for Fam's information.
According to the comment 13, set the bug as verified.
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.