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

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

[Fam Zheng]

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              |  3 +++
 3 files changed, 40 insertions(+)

-- 
2.14.3

[Qemu-devel] [PATCH 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..fa2e90d15f 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 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 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 "lslocks" command on
+host and see if there are locks held by QEMU process on the image file. More
+than one bytes could be locked by a QEMU instance, each byte of which reflects
+a perticular permission that are 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

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

[Philipp Hahn]

Hello,

Am 23.11.2017 um 14:59 schrieb Fam Zheng:
> diff --git a/docs/qemu-block-drivers.texi b/docs/qemu-block-drivers.texi
> index 1cb1e55686..fa2e90d15f 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
...
> +To check if image locking is active, check the output of "lslocks" command on
> +host and see if there are locks held by QEMU process on the image file. More
> +than one bytes could be locked by a QEMU instance, each byte of which reflects

"one byte", without the 's'?

> +a perticular permission that are acquired or protected by the running block

"particular", 'e' -> 'a'

Philipp

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

[Fam Zheng]

On Thu, 11/23 17:07, Philipp Hahn wrote:
> Hello,
> 
> Am 23.11.2017 um 14:59 schrieb Fam Zheng:
> > diff --git a/docs/qemu-block-drivers.texi b/docs/qemu-block-drivers.texi
> > index 1cb1e55686..fa2e90d15f 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
> ...
> > +To check if image locking is active, check the output of "lslocks" command on
> > +host and see if there are locks held by QEMU process on the image file. More
> > +than one bytes could be locked by a QEMU instance, each byte of which reflects
> 
> "one byte", without the 's'?
> 
> > +a perticular permission that are acquired or protected by the running block
> 
> "particular", 'e' -> 'a'
> 

Yes to both. Thanks!

Fam

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

[Kevin Wolf]

Am 23.11.2017 um 14:59 hat Fam Zheng geschrieben:
> 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..fa2e90d15f 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 Open

s/with/with the/

> +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 risk that the lock

s/risk/a risk/ (native speakers, is this the right correction?)

> +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

s/by/with the/

> +option. In the command line the option is usually in the form of

Comma after "command line"?

> +"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 "lslocks" command on

_the_ "lslocks" command

> +host and see if there are locks held by QEMU process on the image file. More

"by a" or "by the", depending on what exactly you want to say

> +than one bytes could be locked by a QEMU instance, each byte of which reflects

s/bytes/byte/

> +a perticular permission that are acquired or protected by the running block

s/are/is/

> +driver.
> +
>  @c man end

Kevin

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

[Fam Zheng]

On Thu, 11/23 18:01, Kevin Wolf wrote:
> Am 23.11.2017 um 14:59 hat Fam Zheng geschrieben:
> > 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..fa2e90d15f 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 Open
> 
> s/with/with the/
> 
> > +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 risk that the lock
> 
> s/risk/a risk/ (native speakers, is this the right correction?)
> 
> > +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
> 
> s/by/with the/
> 
> > +option. In the command line the option is usually in the form of
> 
> Comma after "command line"?
> 
> > +"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 "lslocks" command on
> 
> _the_ "lslocks" command
> 
> > +host and see if there are locks held by QEMU process on the image file. More
> 
> "by a" or "by the", depending on what exactly you want to say
> 
> > +than one bytes could be locked by a QEMU instance, each byte of which reflects
> 
> s/bytes/byte/
> 
> > +a perticular permission that are acquired or protected by the running block
> 
> s/are/is/
> 
> > +driver.
> > +
> >  @c man end

Updating all of them. Thanks!

Fam

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

[Fam Zheng]

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

diff --git a/qemu-options.hx b/qemu-options.hx
index 3728e9b4dd..bcb7a88ec3 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -693,6 +693,9 @@ 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.
+(auto/on/off, default: auto)
 @end table
 Example:
 @example
-- 
2.14.3

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

[Kevin Wolf]

Am 23.11.2017 um 14:59 hat Fam Zheng geschrieben:
> Signed-off-by: Fam Zheng <famz@redhat.com>
> ---
>  qemu-options.hx | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 3728e9b4dd..bcb7a88ec3 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -693,6 +693,9 @@ 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.
> +(auto/on/off, default: auto)

Maybe "should be protected" would be better than "is protected"?

Do we want to explain what "auto" means?

Kevin

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

[Fam Zheng]

On Thu, 11/23 18:03, Kevin Wolf wrote:
> Am 23.11.2017 um 14:59 hat Fam Zheng geschrieben:
> > Signed-off-by: Fam Zheng <famz@redhat.com>
> > ---
> >  qemu-options.hx | 3 +++
> >  1 file changed, 3 insertions(+)
> > 
> > diff --git a/qemu-options.hx b/qemu-options.hx
> > index 3728e9b4dd..bcb7a88ec3 100644
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -693,6 +693,9 @@ 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.
> > +(auto/on/off, default: auto)
> 
> Maybe "should be protected" would be better than "is protected"?

Yes.

> 
> Do we want to explain what "auto" means?

Will add that.

Fam