From c83bac681bd10d576c3af9a45b49065aa6b7330e Mon Sep 17 00:00:00 2001

From: Fam Zheng <famz@redhat.com>

Date: Thu, 30 Nov 2017 09:25:42 +0100

Subject: [PATCH 05/36] docs: Add image locking subsection

RH-Author: Fam Zheng <famz@redhat.com>

Message-id: <20171130092544.19231-4-famz@redhat.com>

Patchwork-id: 78016

O-Subject: [RHV7.5 qemu-kvm-ma PATCH 3/5] docs: Add image locking subsection

Bugzilla: 1494210

RH-Acked-by: Stefan Hajnoczi <stefanha@redhat.com>

RH-Acked-by: Jeffrey Cody <jcody@redhat.com>

RH-Acked-by: John Snow <jsnow@redhat.com>

This documents the image locking feature and explains when and how

related options can be used.

Signed-off-by: Fam Zheng <famz@redhat.com>

Signed-off-by: Kevin Wolf <kwolf@redhat.com>

(cherry picked from commit b1d1cb272882dd6868740155120f6aeb260a204c)

Signed-off-by: Fam Zheng <famz@redhat.com>

Signed-off-by: Miroslav Rezanina <mrezanin@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 d3b8f3b..aa64e60 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 b0db386..6af38de 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

-- 

1.8.3.1