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

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

On FUSE, OFD locks are indeed indistinguishable from POSIX locks for the
underlying fs, which is part of the problem — the filesystem can't ensure
the correct handling.
The practical issue we're hitting is stale locks not being cleaned up
across service restarts (e.g. Kolla/Cinder container restarts), which can
block volume access.
There's also a detection caveat: QEMU probes OFD capability against
/dev/null, which reliably reflects kernel support but says nothing about
the locking semantics of a remote filesystem actually serving the images.
Combined with varying OFD support across different versions of various
remote file systems, an explicit POSIX flag would give operators a
straightforward way to ensure consistent, predictable behaviour in setups
where OFD lock semantics cannot be relied upon.

Thanks for looking into this and best regards
Silvan

Am Do., 26. März 2026 um 10:34 Uhr schrieb Daniel P. Berrangé <
berrange@redhat.com>:

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

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

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

On Fri, Mar 27, 2026 at 12:25:41PM +0100, Silvan Kaiser wrote:
> On FUSE, OFD locks are indeed indistinguishable from POSIX locks for the
> underlying fs, which is part of the problem — the filesystem can't ensure
> the correct handling.

QEMU will currently request an OFD lock, which will silently degrade
to be POSIX lock semantics on FUSE. QEMU is fine with POSIX lock
semantics in general, we merely prefer OFD if possible.

This patch adding a "posix" option will cause QEMU to request a POSIX
lock, which will have the same semantics we already get.

How is adding this 'posix' option a benefit ?

> The practical issue we're hitting is stale locks not being cleaned up
> across service restarts (e.g. Kolla/Cinder container restarts), which can
> block volume access.

How does this patch help solve that ?

> There's also a detection caveat: QEMU probes OFD capability against
> /dev/null, which reliably reflects kernel support but says nothing about
> the locking semantics of a remote filesystem actually serving the images.
> Combined with varying OFD support across different versions of various
> remote file systems, an explicit POSIX flag would give operators a
> straightforward way to ensure consistent, predictable behaviour in setups
> where OFD lock semantics cannot be relied upon.

The distinction between OFD & POSIX only matter at a client process
level, it shouldn't affect remote use. OFD locks just fix the crazy
POSIX semantics where closing any FD pointing to the file in QEMU
would release the locks, even if thy were held on a different FD in
QEMU.

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