All of lore.kernel.org
 help / color / mirror / Atom feed
* [Qemu-devel] [PATCH 0/2] docs: Add documentation for image locking
@ 2017-11-23 13:59 Fam Zheng
  2017-11-23 13:59 ` [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection Fam Zheng
  2017-11-23 13:59 ` [Qemu-devel] [PATCH 2/2] qemu-options: Mention locking option of file driver Fam Zheng
  0 siblings, 2 replies; 9+ messages in thread
From: Fam Zheng @ 2017-11-23 13:59 UTC (permalink / raw)
  To: qemu-devel; +Cc: kwolf, famz, mreitz

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection
  2017-11-23 13:59 [Qemu-devel] [PATCH 0/2] docs: Add documentation for image locking Fam Zheng
@ 2017-11-23 13:59 ` Fam Zheng
  2017-11-23 16:07   ` Philipp Hahn
  2017-11-23 17:01   ` Kevin Wolf
  2017-11-23 13:59 ` [Qemu-devel] [PATCH 2/2] qemu-options: Mention locking option of file driver Fam Zheng
  1 sibling, 2 replies; 9+ messages in thread
From: Fam Zheng @ 2017-11-23 13:59 UTC (permalink / raw)
  To: qemu-devel; +Cc: kwolf, famz, mreitz

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

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [Qemu-devel] [PATCH 2/2] qemu-options: Mention locking option of file driver
  2017-11-23 13:59 [Qemu-devel] [PATCH 0/2] docs: Add documentation for image locking Fam Zheng
  2017-11-23 13:59 ` [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection Fam Zheng
@ 2017-11-23 13:59 ` Fam Zheng
  2017-11-23 17:03   ` Kevin Wolf
  1 sibling, 1 reply; 9+ messages in thread
From: Fam Zheng @ 2017-11-23 13:59 UTC (permalink / raw)
  To: qemu-devel; +Cc: kwolf, famz, mreitz

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

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* Re: [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection
  2017-11-23 13:59 ` [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection Fam Zheng
@ 2017-11-23 16:07   ` Philipp Hahn
  2017-11-24  8:43     ` Fam Zheng
  2017-11-23 17:01   ` Kevin Wolf
  1 sibling, 1 reply; 9+ messages in thread
From: Philipp Hahn @ 2017-11-23 16:07 UTC (permalink / raw)
  To: Fam Zheng, qemu-devel; +Cc: kwolf, mreitz

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection
  2017-11-23 13:59 ` [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection Fam Zheng
  2017-11-23 16:07   ` Philipp Hahn
@ 2017-11-23 17:01   ` Kevin Wolf
  2017-11-24  8:43     ` Fam Zheng
  1 sibling, 1 reply; 9+ messages in thread
From: Kevin Wolf @ 2017-11-23 17:01 UTC (permalink / raw)
  To: Fam Zheng; +Cc: qemu-devel, mreitz

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Qemu-devel] [PATCH 2/2] qemu-options: Mention locking option of file driver
  2017-11-23 13:59 ` [Qemu-devel] [PATCH 2/2] qemu-options: Mention locking option of file driver Fam Zheng
@ 2017-11-23 17:03   ` Kevin Wolf
  2017-11-24  8:44     ` Fam Zheng
  0 siblings, 1 reply; 9+ messages in thread
From: Kevin Wolf @ 2017-11-23 17:03 UTC (permalink / raw)
  To: Fam Zheng; +Cc: qemu-devel, mreitz

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection
  2017-11-23 17:01   ` Kevin Wolf
@ 2017-11-24  8:43     ` Fam Zheng
  0 siblings, 0 replies; 9+ messages in thread
From: Fam Zheng @ 2017-11-24  8:43 UTC (permalink / raw)
  To: Kevin Wolf; +Cc: qemu-devel, mreitz

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection
  2017-11-23 16:07   ` Philipp Hahn
@ 2017-11-24  8:43     ` Fam Zheng
  0 siblings, 0 replies; 9+ messages in thread
From: Fam Zheng @ 2017-11-24  8:43 UTC (permalink / raw)
  To: Philipp Hahn; +Cc: qemu-devel, kwolf, mreitz

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Qemu-devel] [PATCH 2/2] qemu-options: Mention locking option of file driver
  2017-11-23 17:03   ` Kevin Wolf
@ 2017-11-24  8:44     ` Fam Zheng
  0 siblings, 0 replies; 9+ messages in thread
From: Fam Zheng @ 2017-11-24  8:44 UTC (permalink / raw)
  To: Kevin Wolf; +Cc: qemu-devel, mreitz

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2017-11-24  8:44 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-11-23 13:59 [Qemu-devel] [PATCH 0/2] docs: Add documentation for image locking Fam Zheng
2017-11-23 13:59 ` [Qemu-devel] [PATCH 1/2] docs: Add image locking subsection Fam Zheng
2017-11-23 16:07   ` Philipp Hahn
2017-11-24  8:43     ` Fam Zheng
2017-11-23 17:01   ` Kevin Wolf
2017-11-24  8:43     ` Fam Zheng
2017-11-23 13:59 ` [Qemu-devel] [PATCH 2/2] qemu-options: Mention locking option of file driver Fam Zheng
2017-11-23 17:03   ` Kevin Wolf
2017-11-24  8:44     ` Fam Zheng

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.