Skip to content

docs: document udev dependency for /dev/disk/by-uuid links #456

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ebiggers merged 2 commits into from
Aug 22, 2026
+27 −0
Merged

docs: document udev dependency for /dev/disk/by-uuid links #456

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea5d0e0
docs: document udev dependency for /dev/disk/by-uuid links
amarkdotdev Aug 9, 2026
bc69714
docs: point udev rule links at current upstream URLs
amarkdotdev Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)

@ebiggers ebiggers Aug 20, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link doesn't work.

@amarkdotdev amarkdotdev Aug 20, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

swapped it for a working link

* [eudev `60-persistent-storage.rules`](https://github.com/gentoo/eudev/blob/master/rules/60-persistent-storage.rules)

@ebiggers ebiggers Aug 20, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one does work, but it redirects to a new location. Best to link directly to the new location.

@amarkdotdev amarkdotdev Aug 20, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pointed at the dest instead of the redirect


## Configuration file

Running `sudo fscrypt setup` will create the configuration file
Expand Down