Bug#1118371: Add guidance for file locking; transition from existence-based locking and /var/lock to file locking
Package: debian-policy
Version: 4.7.2.0
Severity: normal
Tags: patch
X-Debbugs-Cc: josh@joshtriplett.org
Originally discussed at
https://lists.debian.org/debian-policy/2025/10/msg00023.html .
I've attached a git patch implementing the Policy changes discussed in
that thread.
Based on #1115317, the Technical Committee called for a transition on
locking, and an update to Policy. In general, Policy updates tend to be
lagging indicators, updating after most packages are already compliant.
In this case, most packages already *do* use file locking, rather than
existence-based lockfiles, so I think it'd be reasonable to capture this
in Policy (as a "should" initially, making it a *normal* bug to do
otherwise) *concurrently* with porting the remaining software over to
file locking (per the transitional mechanism this documents in Policy).
Almost all of this is a "should", constituting a "normal" bug. The only
"must" language is around *new* requirements for handling both file
locking and traditional locking while avoiding deadlocks, and the
statement that "`/dev`` and ``/run`` and ``$XDG_RUNTIME_DIR`` *must*
support file locking".
>From b382d4d898631549599ecdb16b1d6fe671232a22 Mon Sep 17 00:00:00 2001
Message-ID: <b382d4d898631549599ecdb16b1d6fe671232a22.1760811130.git.josh@joshtriplett.org>
From: Josh Triplett <josh@joshtriplett.org>
Date: Sat, 18 Oct 2025 11:09:39 -0700
Subject: [PATCH] Policies on file locking
---
policy/ch-opersys.rst | 76 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 76 insertions(+)
diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 1501076..780ce36 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -95,6 +95,14 @@ Debian Policy. The following exceptions to the FHS apply:
``/usr/bin/mh/``, as was allowed in FHS version 2.3. Other
subdirectories are not allowed.
+14. ``/var/lock`` and ``/run/lock`` should only be used by software
+ designed to run as root, and should not be assumed to be writable by
+ non-root users. See :ref:`s-lockfiles` for more on using lockfiles,
+ rather than defaulting to the use of ``/var/lock`` or ``/run/lock``.
+ This includes locking for serial ports; the guidance in the FHS
+ about locking serial ports should be treated as a "traditional lock"
+ as documented in :ref:`s-lockfiles`.
+
The version of this document referred here can be found in the
``debian-policy`` package or on `FHS (Debian
copy) <https://www.debian.org/doc/packaging-manuals/fhs/>`_ alongside
@@ -207,6 +215,8 @@ the older ``/var/run`` and ``/var/lock`` paths. The latter paths will
normally be symlinks or other redirections to ``/run`` for backwards
compatibility.
+See :ref:`s-lockfiles` for more on using lockfiles.
+
.. _s9.2:
Users and groups
@@ -978,6 +988,72 @@ Event-based boot with upstart
The ``upstart`` event-based boot system is no longer maintained in
Debian, so this section has been removed.
+.. _s-lockfiles:
+
+Lockfiles
+---------
+
+Software should not use existence-based lockfiles, where the existence
+of the lockfile constitutes holding the lock. Such existence-based
+lockfiles have multiple problems, including stale locks (when the
+lockfile exists but the locking process is no longer running). Software
+should use file locking (e.g. ``flock`` or various flavors of
+``fcntl``-based locks) on an appropriate file instead. ``flock`` is
+generally most common, but software may use any appropriate file-locking
+mechanism as long as all coordinating pieces of software agree.
+
+Where possible, software should apply file locking to an appropriate
+target file or directory rather than a dedicated lockfile. For instance,
+if locking a device or a data file, software should use file locking on
+the device file or data file directly, rather than creating a separate
+file to lock. Note that coordinating software must agree on what file or
+directory to apply file locking to.
+
+``/var/lock`` and ``/run/lock`` should only be used by software designed
+to run as root, and should only be used if there is not an appropriate
+target file or directory to lock instead. Software that needs to create
+a dedicated lockfile to apply file locking to (e.g. to lock a resource
+not represented by a file) should arrange to create its own directory in
+``/run`` (for system software, e.g. by using the systemd
+``RuntimeDirectory`` directive) or ``$XDG_RUNTIME_DIR`` (for user
+software).
+
+Note that some exotic filesystems (e.g. unusual FUSE filesystems) may
+not support file locking, but ``/dev`` and ``/run`` and
+``$XDG_RUNTIME_DIR`` *must* support file locking, and ``/tmp`` and
+``$HOME`` are generally expected to.
+
+As a transitional measure, when lockfiles are used for coordination
+across multiple pieces of software, and some of that software has
+historically used existence-based lockfiles or (as non-root) lockfiles
+in ``/var/lock`` or ``/run/lock``, software should *both* use file
+locking on an appropriate target file or non-existence-based lockfile
+*and* attempt to lock the traditional lock. To avoid deadlocks and to
+allow detection of un-transitioned software, the locks must be acquired
+in that order (file lock then traditional lock) and dropped in reverse
+order. For the traditional lock, the software must distinguish between:
+
+- Failing to acquire the traditional lock because another process has
+ it, which it should treat as being locked and act accordingly,
+ dropping the file lock if not blocking on the traditional lock. The
+ software may wish to warn that either the traditional lock is stale or
+ the process owning the traditional lock has not yet been transitioned
+ to file locking.
+
+- Failing to acquire the lock for some other reason, such as a
+ permission error (e.g. inability to write to ``/var/lock``), which it
+ should ignore and assume the system has been transitioned to use file
+ locking exclusively.
+
+After an appropriately coordinated transition for that cooperating set
+of software, the software may drop the acquisition of the traditional
+lock, and use file locking exclusively. Such a coordinated transition
+may include
+:doc:`declaring relationships between packages <ch-relationships>` to
+enforce upgrades of software in Debian, and/or appropriate transition
+periods for compatibility with software not in Debian.
+
+
.. [#]
This is necessary in order to reserve the directories for use in
cross-installation of library packages from other architectures, as
--
2.51.0
Reply to: