From ea5d0e0b5e48d4b8c6037fc7ac4c9dc91880fc24 Mon Sep 17 00:00:00 2001 From: amarkdotdev Date: Sun, 9 Aug 2026 22:49:51 +0300 Subject: [PATCH 1/2] docs: document udev dependency for /dev/disk/by-uuid links Explain that cross-filesystem UUID links depend on 60-persistent-storage.rules at link-creation and runtime, with path fallback when UUID lookup is unavailable. Signed-off-by: amarkdotdev --- README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/README.md b/README.md index e5171911..9a2105ee 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ For the release notes, see the [NEWS file](NEWS.md). - [Features](#features) - [Building and installing](#building-and-installing) - [Runtime dependencies](#runtime-dependencies) + - [udev dependency for cross-filesystem links](#udev-dependency-for-cross-filesystem-links) - [Configuration file](#configuration-file) - [Setting up `fscrypt` on a filesystem](#setting-up-fscrypt-on-a-filesystem) - [Setting up for login protectors](#setting-up-for-login-protectors) @@ -313,6 +314,32 @@ If you configure `fscrypt` to use non-default features, other kernel prerequisites may be needed too. See [Configuration file](#configuration-file). +### udev dependency for cross-filesystem links + +Cross-filesystem metadata links (for example `.fscrypt/protectors/*.link` files +that point at a protector stored on another filesystem) prefer to identify the +target filesystem by UUID via `/dev/disk/by-uuid`. Those symlinks are created by +the standard udev rule `60-persistent-storage.rules` (from systemd/udev, eudev, +or classic udev). + +This is a **runtime / link-creation** dependency, not a build-time dependency: + +* **Link creation time:** when `fscrypt` writes a cross-filesystem link, it looks + up the target filesystem UUID under `/dev/disk/by-uuid`. If that directory is + missing or does not contain a usable UUID symlink for the device, `fscrypt` + falls back to storing the mountpoint path only. +* **Runtime (following a link):** when resolving an existing link that contains a + `UUID=` entry, `fscrypt` again uses `/dev/disk/by-uuid` (with a path fallback if + the UUID cannot be resolved). + +Most Linux distributions ship `60-persistent-storage.rules` by default. If you +run a minimal or custom udev setup without that rule, ensure equivalent rules +still create `/dev/disk/by-uuid/*` symlinks before relying on UUID-based +cross-filesystem links. Example upstream sources: + +* [systemd `60-persistent-storage.rules`](https://github.com/systemd/systemd/blob/master/rules.d/60-persistent-storage.rules) +* [eudev `60-persistent-storage.rules`](https://github.com/gentoo/eudev/blob/master/rules/60-persistent-storage.rules) + ## Configuration file Running `sudo fscrypt setup` will create the configuration file From bc6971447717e410cc91c9ca49f938e7b0aec903 Mon Sep 17 00:00:00 2001 From: Aaron Date: Thu, 20 Aug 2026 07:19:33 +0300 Subject: [PATCH 2/2] docs: point udev rule links at current upstream URLs Signed-off-by: Aaron --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9a2105ee..c6512b37 100644 --- a/README.md +++ b/README.md @@ -337,8 +337,8 @@ run a minimal or custom udev setup without that rule, ensure equivalent rules still create `/dev/disk/by-uuid/*` symlinks before relying on UUID-based cross-filesystem links. Example upstream sources: -* [systemd `60-persistent-storage.rules`](https://github.com/systemd/systemd/blob/master/rules.d/60-persistent-storage.rules) -* [eudev `60-persistent-storage.rules`](https://github.com/gentoo/eudev/blob/master/rules/60-persistent-storage.rules) +* [systemd `60-persistent-storage.rules`](https://github.com/systemd/systemd/blob/main/rules.d/60-persistent-storage.rules.in) +* [eudev `60-persistent-storage.rules`](https://github.com/eudev-project/eudev/blob/master/rules/60-persistent-storage.rules) ## Configuration file