fix(install): follow symlink components in destination path with -D by abendrothj · Pull Request #11505 · uutils/coreutils

abendrothj · 2026-03-26T11:00:06Z

Summary

install -D was replacing pre-existing symlinks in the destination path with real directories instead of following them. This broke any workflow where part of the install prefix is a symlink; including BOSH deployments, Homebrew, Nix, stow, and any make install targeting a symlinked prefix.

Reproduction (from the issue):

mkdir -p /tmp/target
ln -s /tmp/target /tmp/link
echo hello > /tmp/file.txt
install -D -m 644 /tmp/file.txt /tmp/link/subdir/file.txt
# GNU coreutils 8.32: /tmp/link stays a symlink, file lands in /tmp/target/subdir/file.txt
# uutils 0.7.0:       /tmp/link is replaced with a real directory — wrong

Root cause

PR #10140 introduced create_dir_all_safe() in safe_traversal.rs to prevent TOCTOU symlink race conditions. The fix was correct in intent but too aggressive: open_or_create_subdir() unconditionally unlinked and recreated any symlink it encountered, including pre-existing legitimate ones.

Changes

src/uucore/src/lib/features/safe_traversal.rs

open_or_create_subdir: when stat_at returns S_IFLNK, call open_subdir(Follow) instead of unlink_at + mkdir_at. The O_DIRECTORY flag already in open_subdir means dangling or non-directory symlinks still return an error cleanly.
find_existing_ancestor: switch from fs::symlink_metadata to fs::metadata so that a symlink-to-directory is recognised as an existing ancestor rather than a component to recreate (this was already the stated intent in the function's doc comment).

src/uu/install/src/install.rs

Align the dir_exists check and the DirFd::open call to also follow symlinks, consistent with the above.

tests/by-util/test_install.rs

Update the two tests added by fix(install): prevent symlink race condition in install -D (fixes #10013) #10140 — they were asserting the buggy behavior (symlink replaced). Flip the assertions to document the correct GNU behavior.
Add test_install_d_follows_symlink_prefix as a direct regression test for the issue's reproduction case.

TOCTOU / security note

The true TOCTOU race (a symlink injected during the operation into a not-yet-existing path component) is still blocked: mkdirat fails with EEXIST if an attacker creates a symlink between stat_at returning ENOENT and our mkdir_at. Newly-created directories are still opened with O_NOFOLLOW.

What changes is that pre-existing symlinks are now followed — which is exactly what GNU coreutils 8.32 does. The previous behavior was stricter than GNU in this regard.

github-actions · 2026-03-26T11:30:22Z

GNU testsuite comparison:

GNU test failed: tests/timeout/timeout-group. tests/timeout/timeout-group is passing on 'main'. Maybe you have to rebase?
Note: The gnu test tests/seq/seq-epipe is now being skipped but was previously passing.
Congrats! The gnu test tests/cp/link-heap is now passing!
Note: The gnu test tests/misc/write-errors was skipped on 'main' but is now failing.

codspeed-hq · 2026-03-26T11:41:42Z

Merging this PR will not alter performance

✅ 319 untouched benchmarks
⏩ 46 skipped benchmarks¹

_{Comparing abendrothj:fix/install-d-follow-symlinks (dbe8864) with main (19c7f64)}

46 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

github-actions · 2026-03-26T20:44:22Z

GNU testsuite comparison:

GNU test failed: tests/misc/io-errors. tests/misc/io-errors is passing on 'main'. Maybe you have to rebase?
Skip an intermittent issue tests/cut/bounded-memory (fails in this run but passes in the 'main' branch)
Skipping an intermittent issue tests/pr/bounded-memory (passes in this run but fails in the 'main' branch)
Note: The gnu test tests/tail/tail-n0f is now being skipped but was previously passing.

github-actions · 2026-03-28T12:12:50Z

GNU testsuite comparison:

Skipping an intermittent issue tests/date/date-locale-hour (passes in this run but fails in the 'main' branch)
Skipping an intermittent issue tests/date/resolution (passes in this run but fails in the 'main' branch)
Note: The gnu test tests/tail/tail-n0f is now being skipped but was previously passing.

zhw2101024 · 2026-04-22T11:19:05Z

The test fails in the mkfifo test, anyway hope this PR can be merged, and the related issue not left to the next released uutils.

abendrothj · 2026-04-22T19:46:50Z

The test fails in the mkfifo test, anyway hope this PR can be merged, and the related issue not left to the next released uutils.

agreed. seems like flakiness, since mkfifo is unrelated.

github-actions · 2026-04-22T19:53:55Z

GNU testsuite comparison:

Skip an intermittent issue tests/cut/bounded-memory (fails in this run but passes in the 'main' branch)
Skip an intermittent issue tests/tail/tail-n0f (fails in this run but passes in the 'main' branch)
Note: The gnu test tests/tail/pipe-f is now being skipped but was previously passing.

install -D was replacing pre-existing symlinks in the destination path with real directories instead of following them, breaking any workflow where part of the install prefix is a symlink (BOSH, Homebrew, Nix, stow, `make install` with a symlinked prefix).

Ecordonnier · 2026-05-24T20:31:41Z

 /// Find the deepest existing real directory ancestor for a path.
 ///
 /// Returns the existing ancestor path and a list of components that need to be created.
 /// Uses `symlink_metadata` to detect symlinks - symlinks are NOT followed and are


This comment is wrong after the change. Should be changed to something like:

/// Uses `metadata` (follows symlinks) so that symlinks to directories are treated /// as existing ancestors rather than components to create.

Ecordonnier · 2026-05-24T20:32:58Z

 /// Open or create a subdirectory using fd-based operations only.
 ///
 /// This is a helper function for `create_dir_all_safe` that handles a single
 /// path component. If a symlink exists where a directory should be, it is


this comment is wrong after the change and needs to be updated.

Ecordonnier · 2026-05-24T20:35:59Z

 /// This function prevents TOCTOU race conditions by:
 /// 1. Finding the deepest existing ancestor directory (path-based, but safe since it exists)
 /// 2. Opening that ancestor with a file descriptor
 /// 3. Creating all new directories using fd-based operations (mkdirat, openat with O_NOFOLLOW)


after the change: existing symlinks are followed (with O_DIRECTORY as a safety net), while only newly created path components are protected with O_NOFOLLOW.

Ecordonnier · 2026-05-24T20:37:29Z

 fn test_install_d_symlink_race_condition() {
-    // Test for symlink race condition fix (issue #10013)
-    // Verifies that pre-existing symlinks in path are handled safely
+    // Test that pre-existing symlinks in the path are followed (GNU coreutils behavior).


the test name doesn't match what is being tested. it's not related to race-conditions any more

Ecordonnier · 2026-05-25T20:13:20Z

Thanks. I've merged the branch and will add the cosmetic changes in a follow-up PR. This should be merged ASAP since it is a critical fix.

abendrothj force-pushed the fix/install-d-follow-symlinks branch from 9c7f91a to 4fc3ac8 Compare March 26, 2026 11:13

abendrothj force-pushed the fix/install-d-follow-symlinks branch 2 times, most recently from ebc0ba6 to cd070c4 Compare March 26, 2026 20:34

abendrothj force-pushed the fix/install-d-follow-symlinks branch from cd070c4 to ed62194 Compare March 28, 2026 12:03

oech3 mentioned this pull request May 6, 2026

install: on a file install breaks usrmerge on ubuntu 26.04 #12166

Closed

eyupcanakman mentioned this pull request May 21, 2026

install: fix EEXIST race losing files in parallel install -D #12429

Open

Ecordonnier force-pushed the fix/install-d-follow-symlinks branch from 93383c7 to dbe8864 Compare May 24, 2026 20:03

Ecordonnier self-requested a review May 24, 2026 20:05

Ecordonnier reviewed May 24, 2026

View reviewed changes

Ecordonnier merged commit 21fda8c into uutils:main May 25, 2026
172 of 173 checks passed

Uh oh!

Conversation

abendrothj commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Root cause

Changes

TOCTOU / security note

Uh oh!

github-actions Bot commented Mar 26, 2026

Uh oh!

codspeed-hq Bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

github-actions Bot commented Mar 26, 2026

Uh oh!

github-actions Bot commented Mar 28, 2026

Uh oh!

zhw2101024 commented Apr 22, 2026

Uh oh!

abendrothj commented Apr 22, 2026

Uh oh!

github-actions Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ecordonnier May 24, 2026

Choose a reason for hiding this comment

Uh oh!

Ecordonnier May 24, 2026

Choose a reason for hiding this comment

Uh oh!

Ecordonnier May 24, 2026

Choose a reason for hiding this comment

Uh oh!

Ecordonnier May 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Ecordonnier commented May 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

abendrothj commented Mar 26, 2026 •

edited

Loading

codspeed-hq Bot commented Mar 26, 2026 •

edited

Loading

github-actions Bot commented Apr 22, 2026 •

edited

Loading