Skip to content

Layers with an absolute hard-link target unpack, as with Docker - #322

Open
talaatmagdyx wants to merge 1 commit into
libracoder:mainfrom
talaatmagdyx:abs-hardlink-302
Open

talaatmagdyx wants to merge 1 commit into
libracoder:mainfrom
talaatmagdyx:abs-hardlink-302

Conversation

@talaatmagdyx

Copy link
Copy Markdown
Contributor

Fixes #302

Problem

A layer with a hard link whose target starts with / (usr/bin/perl5.38.2 → /usr/bin/perl, as some image pipelines write them) failed to unpack, so docker create and docker run refused the image:

unpack sha256:6799e69d…: failed to unpack `bin/tool-1.0`

Docker, containerd and Podman read a hard link's target from the layer's root, so the leading / is harmless there.

Cause

The guest agent unpacks layers with tar-rs. For a hard link, tar-rs joins the target onto the layer directory with Path::join, which an absolute path replaces. The target becomes the guest's own /usr/bin/perl, and tar-rs refuses it as outside the destination.

Change

crates/kiri-init/src/linux/layers.rs, in untar:

  • A hard link with an absolute target is made by hard_link_in, with the leading / taken as the layer's root. Every other entry, including relative hard links, still goes through tar-rs as before.
  • Both the target's directories and the link's own go through the walk whiteouts already use (whiteout_dir, now layer_dir): every step must be a real directory of this layer, and .. is refused. A target through a symlink, or one that climbs out, is still refused with path escapes the layer. linkat doesn't follow a symlink target, so the link stays in the layer.
  • A missing target fails the layer with hard link … to /…: No such file or directory, instead of tar-rs's bare failed to unpack.

Tests

  • Unit absolute_hard_link_is_read_from_the_layer_root: /bin/tool links the layer's bin/tool (same inode); /../../etc/hostname, /root/etc/hostname (with root → / in the layer) and a missing target are refused, and nothing is linked.
  • e2e (images: tag, save, load): load-hardlink-absolute loads a one-layer image with the issue's link and reads /bin/tool-1.0 with docker cp; load-hardlink-escape checks that /../../etc/hostname is refused. The image comes from tests/hardlink-image.py, the issue's script.
  • Results, macOS 26.6.2 on Apple silicon, at main ae3467e:
    • the issue's image: refused on main, created here, and /bin/tool-1.0 holds the file;
    • a relative link: unchanged; //./bin/./tool: works; .., through a symlink, missing: refused;
    • full tests/e2e.sh, the same setup with main's guest and with this one: the two new checks fail on main (the issue's error) and pass here; the other results are the same on both, apart from one-off failures early in the run, on different tests each time. The failures common to both come from the throwaway test setup (no Finder mount, a credential helper that keeps no logins, a kernel without patches 0003 and 0005, a home outside /Users);
    • cargo test -p kiri-init linux::layers as root: all pass but whiteout_becomes_char_device, which needs mknod and fails the same way on main in an unprivileged container;
    • clippy: the same 14 findings as main, none in layers.rs.

Notes

  • The fix is in the guest agent, so it ships with a rebuilt initramfs (cargo xtask guest).
  • Refusing every .. in an absolute target is stricter than Docker, which cleans /a/../b to /b first. No image I know of writes that.

A layer's hard link to `/usr/bin/perl` names the layer's own
`usr/bin/perl`, as Docker, containerd and Podman read it. tar-rs joins
the target onto the layer directory, which a leading `/` replaces, and
refuses the result as outside the layer, so the image could not start.

Such a link is now made in `untar`, from the layer's root. Both paths go
through the walk whiteouts use (now `layer_dir`): every step must be a
real directory of the layer and `..` is refused, so a link still cannot
reach outside. Relative hard links and every other entry go through
tar-rs as before.

Fixes libracoder#302
AndreKurait added a commit to AndreKurait/asagiri that referenced this pull request Nov 16, 2026
The hosted Docker reference rejected our old metadata expectation: a
hard-link header changes the shared inode's owner and mode. Preserve the
conflicting headers in the fixture and require Docker's observed result.
The installed Asagiri0.1.5 reproduces the opposite values as a negative
control and its owned resources were removed.

Apply ownership, mode, time and xattrs in the Linux layer extractor using
a pinned inode and final-symlink-safe metadata operations. Keep tar-rs's
path checks and add safe replacement for an existing destination. Do not
open special files for I/O. Add real tests for shared metadata, PAX fields,
replacement and symlink-inode boundaries, plus eight Docker API cases.

Local validation: seven portable filesystem tests passed; Python syntax
and diff checks passed. Linux extraction and hosted Docker/Asagiri matrix
remain pending. Retain the failed run43806691901 as reference evidence.

Related: libracoder/kiri#302 and libracoder/kiri#322. Attribute semantics
checked against moby/moby pkg/archive/archive.go at v28.0.4.

Signed-off-by: Andre Kurait <akurait@amazon.com>
AndreKurait added a commit to AndreKurait/asagiri that referenced this pull request Nov 16, 2026
The real Linux run passed the new regular-file and symlink metadata
regressions, but two older FIFO/device tests still expected the first
header's mode and timestamp after a conflicting hard-link header.
Docker applies the later link header to the shared inode.

Keep the original special-entry checks, then separately require the
later header's attributes and shared inode/link count. Verify device
numbers and types survive both paths. Use the test process's UID/GID
so the FIFO case also works without root; no device is opened for I/O.

Related: libracoder/kiri#302
Related: libracoder/kiri#322
Signed-off-by: Andre Kurait <akurait@amazon.com>
AndreKurait added a commit to AndreKurait/asagiri that referenced this pull request Nov 16, 2026
Keep each layer path unique and put the replaced file in a lower layer. The Docker reference rejected the previous duplicate-path fixture; its seven name and metadata cases passed. Retain all eight API cases and the separate Linux extraction replacement tests.

Related: libracoder/kiri#302, libracoder/kiri#322
Signed-off-by: Andre Kurait <akurait@amazon.com>
@libracoder

Copy link
Copy Markdown
Owner

@talaatmagdyx thanks. Your fix and tests are what showed the problem in #302. #398 is now merged. Its hard-link path handles every link (absolute and relative) through Kiri's confined inroot lookup, so it covers the absolute-target case this PR fixes, and it also follows a symlinked parent inside the layer, as containerd does. That makes the two clash in layers.rs.

Could you rebase onto main and keep only your tests? That's tests/hardlink-image.py, the e2e checks, and the absolute_hard_link_is_read_from_the_layer_root unit test. Drop hard_link_in and the has_root branch. One expected error needs changing: for /root/etc/hostname (where root is a symlink to /), main now follows the symlink inside the layer and reports No such file instead of escapes. Nothing is linked either way. With that, all of your tests pass on main (checked on macOS, Linux and WSL 2).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Layers with an absolute hard-link target fail to unpack (failed to unpack usr/bin/perl5.38.2)

2 participants