Package: debian-policy Version: 4.7.2.0 Severity: normal Tags: patch X-Debbugs-Cc: [email protected]
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.j...@joshtriplett.org> From: Josh Triplett <[email protected]> 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
