[PATCH v1 0/3] block: Add 'posix' option for file locking

[PATCH v1 0/3] block: Add 'posix' option for file locking

[Silvan Kaiser]

QEMU currently supports three values for the 'locking' property of
file-based block devices: 'auto' (the default), 'on', and 'off'.
When OFD (Open File Descriptor) locks are available, 'auto' and 'on'
use them; when they are not, 'on' falls back to POSIX locks with a
warning.

This series adds a fourth value, 'posix', which explicitly forces the
use of traditional POSIX locks (F_SETLK/F_GETLK) regardless of OFD
availability.  The motivation is that some userspace filesystem
implementations (e.g. FUSE) handle POSIX locks correctly but do not
fully support OFD lock semantics.  Issues with OFD support detection
on underlying file systems and some OFD guarantees not being fully
supported can prohibit users from using the default OFD locking.
Previously, users in this situation had no way to force POSIX locking
without disabling locking entirely.

The series is structured as:
  1/3 - core implementation in block/file-posix.c, util/osdep.c,
        include/qemu/osdep.h and qapi/block-core.json
  2/3 - documentation updates in qemu-options.hx and
        docs/system/qemu-block-drivers.rst.inc
  3/3 - new iotest 315 verifying the option is accepted without
        fallback warnings and that POSIX locks are applied

Silvan Kaiser (3):
  block: Add 'posix' option for file locking
  docs/system: Document locking=posix option for file block driver
  tests/qemu-iotests: Add test 315 for locking=posix

 block/file-posix.c                     | 18 ++++--
 docs/system/qemu-block-drivers.rst.inc |  3 +
 include/qemu/osdep.h                   |  1 +
 qapi/block-core.json                   | 18 +++++-
 qemu-options.hx                        | 10 +--
 tests/qemu-iotests/315                 | 88 ++++++++++++++++++++++++++
 tests/qemu-iotests/315.out             |  7 ++
 util/osdep.c                           |  9 ++-
 8 files changed, 139 insertions(+), 15 deletions(-)
 create mode 100755 tests/qemu-iotests/315
 create mode 100644 tests/qemu-iotests/315.out

-- 
2.47.3


-- 
Quobyte GmbH, Berlin, AG Charlottenburg HRB 149012 B, Dr. Felix Hupfeld, 
Dr. Bjoern Kolbeck

[PATCH 1/3] block: Add 'posix' option for file locking

[Silvan Kaiser]

The new 'posix' value for the 'locking' property of file-based block
devices forces the use of traditional POSIX locks (F_SETLK/F_GETLK)
instead of OFD (Open File Descriptor) locks.

While OFD locks are preferred when available — they are per file descriptor and
thus survive QEMU-internal fd operations such as hot-plug and block jobs — some
userspace filesystem implementations (e.g. FUSE) handle POSIX locks correctly
but do not fully support OFD lock semantics. Issues with OFD support detection
on underlying file systems and some OFD guarantees not being fully supported
can prohibit users from using the default OFD locking.
Previously, users in this situation had no way to force POSIX locks without
disabling locking entirely; 'locking=on' would silently fall back to POSIX only
when OFD was unavailable.

The new 'posix' option makes the choice explicit and allows users to set up a
clear POSIX config, allowing users to control the locking setup for any scenario
where OFD locking is not advisable.
Note that the known shortcoming of POSIX locks still applies: locks
can be silently lost when QEMU closes and reopens file descriptors
during hot-plug or block job operations.

Signed-off-by: Silvan Kaiser <silvan@quobyte.com>
---
 block/file-posix.c   | 18 +++++++++++-------
 include/qemu/osdep.h |  1 +
 qapi/block-core.json | 18 ++++++++++++++++--
 util/osdep.c         |  9 +++++++--
 4 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/block/file-posix.c b/block/file-posix.c
index e49b13d6ab..c99974000d 100644
--- a/block/file-posix.c
+++ b/block/file-posix.c
@@ -625,7 +625,7 @@ static int raw_open_common(BlockDriverState *bs, QDict *options,
     BlockdevAioOptions aio, aio_default;
     int fd, ret;
     struct stat st;
-    OnOffAuto locking;
+    BlockdevLockingOptions locking;
 
     opts = qemu_opts_create(&raw_runtime_opts, NULL, 0, &error_abort);
     if (!qemu_opts_absorb_qdict(opts, options, errp)) {
@@ -666,16 +666,16 @@ static int raw_open_common(BlockDriverState *bs, QDict *options,
 
     s->aio_max_batch = qemu_opt_get_number(opts, "aio-max-batch", 0);
 
-    locking = qapi_enum_parse(&OnOffAuto_lookup,
-                              qemu_opt_get(opts, "locking"),
-                              ON_OFF_AUTO_AUTO, &local_err);
+    locking = qapi_enum_parse(&BlockdevLockingOptions_lookup,
+                          qemu_opt_get(opts, "locking"),
+                          BLOCKDEV_LOCKING_OPTIONS_AUTO, &local_err);
     if (local_err) {
         error_propagate(errp, local_err);
         ret = -EINVAL;
         goto fail;
     }
     switch (locking) {
-    case ON_OFF_AUTO_ON:
+    case BLOCKDEV_LOCKING_OPTIONS_ON:
         s->use_lock = true;
         if (!qemu_has_ofd_lock()) {
             warn_report("File lock requested but OFD locking syscall is "
@@ -684,12 +684,16 @@ static int raw_open_common(BlockDriverState *bs, QDict *options,
                          "unexpectedly.\n");
         }
         break;
-    case ON_OFF_AUTO_OFF:
+    case BLOCKDEV_LOCKING_OPTIONS_OFF:
         s->use_lock = false;
         break;
-    case ON_OFF_AUTO_AUTO:
+    case BLOCKDEV_LOCKING_OPTIONS_AUTO:
         s->use_lock = qemu_has_ofd_lock();
         break;
+    case BLOCKDEV_LOCKING_OPTIONS_POSIX:
+        s->use_lock = true;
+        qemu_use_posix_locks();
+        break;
     default:
         abort();
     }
diff --git a/include/qemu/osdep.h b/include/qemu/osdep.h
index f151578b5c..8ea506e462 100644
--- a/include/qemu/osdep.h
+++ b/include/qemu/osdep.h
@@ -634,6 +634,7 @@ int qemu_unlock_fd(int fd, int64_t start, int64_t len);
 int qemu_lock_fd_test(int fd, int64_t start, int64_t len, bool exclusive);
 bool qemu_has_ofd_lock(void);
 int qemu_fcntl_addfl(int fd, int flag);
+void qemu_use_posix_locks(void);
 #endif
 
 bool qemu_has_direct_io(void);
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 508b081ac1..cec369f0fe 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -3362,6 +3362,19 @@
             { 'name': 'virtio-blk-vhost-vdpa', 'if': 'CONFIG_BLKIO' },
             'vmdk', 'vpc', 'vvfat' ] }
 
+##
+# @BlockdevLockingOptions:
+#
+# @off: Disable locking.
+# @on: Enable locking (prefer OFD).
+# @auto: Use locking if OFD is available.
+# @posix: Force use of traditional POSIX locks.
+#
+# Since: 10.3
+##
+{ 'enum': 'BlockdevLockingOptions',
+  'data': [ 'off', 'on', 'auto', 'posix' ] }
+
 ##
 # @BlockdevOptionsFile:
 #
@@ -3382,7 +3395,8 @@
 #     automatically.  (default: 0, since 6.2)
 #
 # @locking: whether to enable file locking.  If set to 'auto', only
-#     enable when Open File Descriptor (OFD) locking API is available
+#     enable when Open File Descriptor (OFD) locking API is available.
+#     'posix' forces use of POSIX locks.
 #     (default: auto, since 2.10)
 #
 # @drop-cache: invalidate page cache during live migration.  This
@@ -3412,7 +3426,7 @@
 { 'struct': 'BlockdevOptionsFile',
   'data': { 'filename': 'str',
             '*pr-manager': 'str',
-            '*locking': 'OnOffAuto',
+            '*locking': 'BlockdevLockingOptions',
             '*aio': 'BlockdevAioOptions',
             '*aio-max-batch': 'int',
             '*drop-cache': {'type': 'bool',
diff --git a/util/osdep.c b/util/osdep.c
index 000e7daac8..76495282cc 100644
--- a/util/osdep.c
+++ b/util/osdep.c
@@ -223,8 +223,7 @@ static void qemu_probe_lock_ops(void)
             fcntl_op_getlk = F_GETLK;
         }
 #else
-        fcntl_op_setlk = F_SETLK;
-        fcntl_op_getlk = F_GETLK;
+        qemu_use_posix_locks();
 #endif
     }
 }
@@ -239,6 +238,12 @@ bool qemu_has_ofd_lock(void)
 #endif
 }
 
+void qemu_use_posix_locks(void)
+{
+    fcntl_op_setlk = F_SETLK;
+    fcntl_op_getlk = F_GETLK;
+}
+
 static int qemu_lock_fcntl(int fd, int64_t start, int64_t len, int fl_type)
 {
     int ret;
-- 
2.47.3


-- 
Quobyte GmbH, Berlin, AG Charlottenburg HRB 149012 B, Dr. Felix Hupfeld, 
Dr. Bjoern Kolbeck

[PATCH 2/3] docs/system: Document locking=posix option for file block driver

[Silvan Kaiser]

Signed-off-by: Silvan Kaiser <silvan@quobyte.com>
---
 docs/system/qemu-block-drivers.rst.inc |  3 +++
 qemu-options.hx                        | 10 ++++++----
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
index 384e95ba76..bdecbf39ca 100644
--- a/docs/system/qemu-block-drivers.rst.inc
+++ b/docs/system/qemu-block-drivers.rst.inc
@@ -882,6 +882,9 @@ 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.
 
+To force the use of POSIX locks even when OFD locking is available, specify
+"locking=posix". The same caveats about silent lock loss apply.
+
 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.
diff --git a/qemu-options.hx b/qemu-options.hx
index 21972f8326..23502c5aa6 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1540,10 +1540,12 @@ SRST
             default: threads)
 
         ``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 available, otherwise no lock is applied.
-            (auto/on/off, default: auto)
+            Specifies whether the image file is protected with locks.
+            'on' enables locking, preferring OFD (Open File Descriptor)
+            locks if available, but falling back to POSIX locks with a
+            warning. 'posix' forces the use of POSIX locks. 'auto' (the
+            default) enables locking only if OFD locks are available.
+            'off' disables locking. (on/off/auto/posix, default: auto)
 
         Example:
 
-- 
2.47.3


-- 
Quobyte GmbH, Berlin, AG Charlottenburg HRB 149012 B, Dr. Felix Hupfeld, 
Dr. Bjoern Kolbeck

[PATCH 3/3] tests/qemu-iotests: Add test 315 for locking=posix

[Silvan Kaiser]

Signed-off-by: Silvan Kaiser <silvan@quobyte.com>
---
 tests/qemu-iotests/315     | 88 ++++++++++++++++++++++++++++++++++++++
 tests/qemu-iotests/315.out |  7 +++
 2 files changed, 95 insertions(+)
 create mode 100755 tests/qemu-iotests/315
 create mode 100644 tests/qemu-iotests/315.out

diff --git a/tests/qemu-iotests/315 b/tests/qemu-iotests/315
new file mode 100755
index 0000000000..9ccc4b0439
--- /dev/null
+++ b/tests/qemu-iotests/315
@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# group: rw quick
+#
+# Test image locking with locking=posix
+#
+# Unlike 'locking=on', which prefers OFD locks and falls back to POSIX
+# with a warning, 'locking=posix' explicitly forces the use of POSIX
+# locks without any warning.  This test verifies that:
+#   - locking=posix does not emit a fallback warning
+#   - locking=posix actually applies POSIX locks on the image
+#
+# The lock check uses qemu-storage-daemon opening the image via the
+# 'file' protocol driver directly (no format layer on top), because
+# POSIX locks are per-process and are silently released when any fd to
+# the same inode is closed -- which happens during qcow2 initialisation
+# inside a full QEMU instance.
+#
+# Copyright 2026 Quobyte Inc
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+# creator
+owner=silvan@quobyte.com
+
+seq="$(basename $0)"
+echo "QA output created by $seq"
+
+tmp=/tmp/$$
+status=1	# failure is the default!
+
+_cleanup()
+{
+    _cleanup_test_img
+    if [ -f "$TEST_DIR/qsd.pid" ]; then
+        kill -SIGTERM "$(cat "$TEST_DIR/qsd.pid")" 2>/dev/null
+        rm -f "$TEST_DIR/qsd.pid"
+    fi
+    rm -f "$SOCK_DIR/qsd-315.sock"
+}
+trap "_cleanup; exit \$status" 0 1 2 3 15
+
+# get standard environment, filters and checks
+. ./common.rc
+. ./common.filter
+
+_supported_fmt qcow2
+_supported_proto file
+_supported_os Linux
+
+size=32M
+
+_make_test_img $size
+
+# locking=posix is an explicit choice, not a fallback, so the
+# "falling back to POSIX file locks" warning must never appear,
+# regardless of whether OFD locking is available on this host.
+echo "Checking that locking=posix does not warn about OFD fallback"
+if $QEMU_IMG info --image-opts \
+        "driver=file,locking=posix,filename=$TEST_IMG" 2>&1 |
+    grep -q 'falling back'; then
+    _fail "FAIL: unexpected fallback warning with locking=posix"
+fi
+echo "OK: no fallback warning"
+
+# Use qemu-storage-daemon with driver=file (no format layer) to hold the
+# image open with locking=posix, then verify POSIX locks appear in
+# /proc/locks.  A format layer (e.g. qcow2) would trigger internal fd
+# reopen operations that silently release POSIX locks, so we bypass it.
+echo "Checking that locking=posix applies POSIX locks on the image"
+$QSD \
+    --blockdev "driver=file,node-name=file0,filename=$TEST_IMG,locking=posix" \
+    --nbd-server "addr.type=unix,addr.path=$SOCK_DIR/qsd-315.sock" \
+    --export "type=nbd,id=exp0,node-name=file0,writable=on" \
+    --daemonize --pidfile "$TEST_DIR/qsd.pid"
+
+INODE=$(stat -c %i "$TEST_IMG")
+if grep -q "POSIX.*:${INODE} " /proc/locks; then
+    echo "OK: POSIX locks present on image"
+else
+    _fail "FAIL: no POSIX locks found on image"
+fi
+
+kill -SIGTERM "$(cat "$TEST_DIR/qsd.pid")"
+rm -f "$TEST_DIR/qsd.pid" "$SOCK_DIR/qsd-315.sock"
+
+# success, all done
+echo "*** done"
+rm -f $seq.full
+status=0
diff --git a/tests/qemu-iotests/315.out b/tests/qemu-iotests/315.out
new file mode 100644
index 0000000000..e90082fc64
--- /dev/null
+++ b/tests/qemu-iotests/315.out
@@ -0,0 +1,7 @@
+QA output created by 315
+Formatting 'TEST_DIR/t.IMGFMT', fmt=IMGFMT size=33554432
+Checking that locking=posix does not warn about OFD fallback
+OK: no fallback warning
+Checking that locking=posix applies POSIX locks on the image
+OK: POSIX locks present on image
+*** done
-- 
2.47.3


-- 
Quobyte GmbH, Berlin, AG Charlottenburg HRB 149012 B, Dr. Felix Hupfeld, 
Dr. Bjoern Kolbeck

Re: [PATCH v1 0/3] block: Add 'posix' option for file locking

[Daniel P. Berrangé]

On Thu, Mar 26, 2026 at 10:19:45AM +0100, Silvan Kaiser wrote:
> QEMU currently supports three values for the 'locking' property of
> file-based block devices: 'auto' (the default), 'on', and 'off'.
> When OFD (Open File Descriptor) locks are available, 'auto' and 'on'
> use them; when they are not, 'on' falls back to POSIX locks with a
> warning.
> 
> This series adds a fourth value, 'posix', which explicitly forces the
> use of traditional POSIX locks (F_SETLK/F_GETLK) regardless of OFD
> availability.  The motivation is that some userspace filesystem
> implementations (e.g. FUSE) handle POSIX locks correctly but do not
> fully support OFD lock semantics.  Issues with OFD support detection
> on underlying file systems and some OFD guarantees not being fully
> supported can prohibit users from using the default OFD locking.
> Previously, users in this situation had no way to force POSIX locking
> without disabling locking entirely.

Don't the OFD locks silently degrade into POSIX lock semantics
when used over FUSE ? If not, what is the behaviour problem
you're seeing ? 


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|