[Qemu-devel] [PATCH v2 0/2] docs: Add documentation for image locking

[Qemu-devel] [PATCH v2 0/2] docs: Add documentation for image locking

[Fam Zheng]

v2: Grammar and spelling fixes pointed out by Kevin and Philipp.

Image locking feature was added in 2.10 but the documentation has been missing.
Users sometimes get confused and wonder how to configure it for their specific
needs. We should address common use cases in the man page and explain related
options.

Fam Zheng (2):
  docs: Add image locking subsection
  qemu-options: Mention locking option of file driver

 docs/qemu-block-drivers.texi | 36 ++++++++++++++++++++++++++++++++++++
 qemu-doc.texi                |  1 +
 qemu-options.hx              |  4 ++++
 3 files changed, 41 insertions(+)

-- 
2.14.3

[Qemu-devel] [PATCH v2 1/2] docs: Add image locking subsection

[Fam Zheng]

This documents the image locking feature and explains when and how
related options can be used.

Signed-off-by: Fam Zheng <famz@redhat.com>
---
 docs/qemu-block-drivers.texi | 36 ++++++++++++++++++++++++++++++++++++
 qemu-doc.texi                |  1 +
 2 files changed, 37 insertions(+)

diff --git a/docs/qemu-block-drivers.texi b/docs/qemu-block-drivers.texi
index 1cb1e55686..503c1847aa 100644
--- a/docs/qemu-block-drivers.texi
+++ b/docs/qemu-block-drivers.texi
@@ -785,6 +785,42 @@ warning: ssh server @code{ssh.example.com:22} does not support fsync
 With sufficiently new versions of libssh2 and OpenSSH, @code{fsync} is
 supported.
 
+@node disk_image_locking
+@subsection Disk image file locking
+
+By default, QEMU tries to protect image files from unexpected concurrent
+access, as long as it's supported by the block protocol driver and host
+operating system. If multiple QEMU processes (including QEMU emulators and
+utilities) try to open the same image with conflicting accessing modes, all but
+the first one will get an error.
+
+This feature is currently supported by the file protocol on Linux with the Open
+File Descriptor (OFD) locking API, and can be configured to fall back to POSIX
+locking if the POSIX host doesn't support Linux OFD locking.
+
+To explicitly enable image locking, specify "locking=on" in the file protocol
+driver options. If OFD locking is not possible, a warning will be printed and
+the POSIX locking API will be used. In this case there is a risk that the lock
+will get silently lost when doing hot plugging and block jobs, due to the
+shortcomings of the POSIX locking API.
+
+QEMU transparently handles lock handover during shared storage migration.  For
+shared virtual disk images between multiple VMs, the "share-rw" device option
+should be used.
+
+Alternatively, locking can be fully disabled by "locking=off" block device
+option. In the command line, the option is usually in the form of
+"file.locking=off" as the protocol driver is normally placed as a "file" child
+under a format driver. For example:
+
+@code{-blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file}
+
+To check if image locking is active, check the output of the "lslocks" command
+on host and see if there are locks held by the QEMU process on the image file.
+More than one byte could be locked by the QEMU instance, each byte of which
+reflects a particular permission that is acquired or protected by the running
+block driver.
+
 @c man end
 
 @ignore
diff --git a/qemu-doc.texi b/qemu-doc.texi
index 617254917d..db2351c746 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -405,6 +405,7 @@ encrypted disk images.
 * disk_images_iscsi::         iSCSI LUNs
 * disk_images_gluster::       GlusterFS disk images
 * disk_images_ssh::           Secure Shell (ssh) disk images
+* disk_image_locking::        Disk image file locking
 @end menu
 
 @node disk_images_quickstart
-- 
2.14.3

[Qemu-devel] [PATCH v2 2/2] qemu-options: Mention locking option of file driver

[Fam Zheng]

Signed-off-by: Fam Zheng <famz@redhat.com>
---
 qemu-options.hx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/qemu-options.hx b/qemu-options.hx
index 3728e9b4dd..f10c2a3ddb 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -693,6 +693,10 @@ This is the protocol-level block driver for accessing regular files.
 The path to the image file in the local filesystem
 @item aio
 Specifies the AIO backend (threads/native, default: threads)
+@item locking
+Specifies whether the image file is protected with Linux OFD / POSIX locks. The
+default is to use the Linux Open File Descriptor API if avaiable, otherwise no
+lock is applied.  (auto/on/off, default: auto)
 @end table
 Example:
 @example
-- 
2.14.3

Re: [Qemu-devel] [PATCH v2 2/2] qemu-options: Mention locking option of file driver

[Kevin Wolf]

Am 24.11.2017 um 09:53 hat Fam Zheng geschrieben:
> Signed-off-by: Fam Zheng <famz@redhat.com>
> ---
>  qemu-options.hx | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 3728e9b4dd..f10c2a3ddb 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -693,6 +693,10 @@ This is the protocol-level block driver for accessing regular files.
>  The path to the image file in the local filesystem
>  @item aio
>  Specifies the AIO backend (threads/native, default: threads)
> +@item locking
> +Specifies whether the image file is protected with Linux OFD / POSIX locks. The
> +default is to use the Linux Open File Descriptor API if avaiable, otherwise no

s/avaiable/available/

I'll fix this while applying.

> +lock is applied.  (auto/on/off, default: auto)
>  @end table
>  Example:
>  @example

Kevin

Re: [Qemu-devel] [PATCH v2 2/2] qemu-options: Mention locking option of file driver

[Fam Zheng]

On Fri, 11/24 16:24, Kevin Wolf wrote:
> > @@ -693,6 +693,10 @@ This is the protocol-level block driver for accessing regular files.
> >  The path to the image file in the local filesystem
> >  @item aio
> >  Specifies the AIO backend (threads/native, default: threads)
> > +@item locking
> > +Specifies whether the image file is protected with Linux OFD / POSIX locks. The
> > +default is to use the Linux Open File Descriptor API if avaiable, otherwise no
> 
> s/avaiable/available/
> 
> I'll fix this while applying.
> 

Thanks!

Fam

Re: [Qemu-devel] [PATCH v2 0/2] docs: Add documentation for image locking

[Kevin Wolf]

Am 24.11.2017 um 09:53 hat Fam Zheng geschrieben:
> v2: Grammar and spelling fixes pointed out by Kevin and Philipp.
> 
> Image locking feature was added in 2.10 but the documentation has been missing.
> Users sometimes get confused and wonder how to configure it for their specific
> needs. We should address common use cases in the man page and explain related
> options.

Thanks, applied to the block branch.

Kevin