Skip to content

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

Closed

Description

@tojim00d

Kiri version and system

0.2.1 on macOS 27.0.1 (Apple silicon)

What you did

A one-layer image with bin/tool and a hard link bin/tool-1.0 -> /bin/tool (leading slash in the link target). The script below writes it as a docker save archive:

"""Build a one-layer image (docker save format) whose layer has a hard link with an absolute target:
   bin/tool (regular file) and bin/tool-1.0 -> /bin/tool (hard link, leading slash)."""
import hashlib, io, json, tarfile, time
layer = io.BytesIO()
with tarfile.open(fileobj=layer, mode="w", format=tarfile.GNU_FORMAT) as t:
    d = tarfile.TarInfo("bin"); d.type = tarfile.DIRTYPE; d.mode = 0o755; t.addfile(d)
    data = b"#!/bin/sh\necho hello from tool\n"
    f = tarfile.TarInfo("bin/tool"); f.size = len(data); f.mode = 0o755; t.addfile(f, io.BytesIO(data))
    h = tarfile.TarInfo("bin/tool-1.0"); h.type = tarfile.LNKTYPE; h.linkname = "/bin/tool"; h.mode = 0o755; t.addfile(h)
lb = layer.getvalue(); ld = hashlib.sha256(lb).hexdigest()
cfg = json.dumps({"architecture": "arm64", "os": "linux", "config": {"Cmd": ["/bin/tool-1.0"]},
                  "rootfs": {"type": "layers", "diff_ids": ["sha256:" + ld]}}).encode()
cd = hashlib.sha256(cfg).hexdigest()
out = io.BytesIO()
with tarfile.open(fileobj=out, mode="w") as t:
    for name, b in [(f"{ld}/layer.tar", lb), (f"{cd}.json", cfg),
                    ("manifest.json", json.dumps([{"Config": f"{cd}.json", "RepoTags": ["abs-hardlink:test"], "Layers": [f"{ld}/layer.tar"]}]).encode())]:
        i = tarfile.TarInfo(name); i.size = len(b); i.mtime = int(time.time()); t.addfile(i, io.BytesIO(b))
open("abs-hardlink.tar", "wb").write(out.getvalue())
print("abs-hardlink.tar written")
python3 make_abs_hardlink_image.py
docker --context kiri load -i abs-hardlink.tar
docker --context kiri create abs-hardlink:test

What happened

Error response from daemon: unpack sha256:6799e69d6604db288176f21d4284db4bbb0df15a3e7323b755d0947a717e3800: failed to unpack `bin/tool-1.0`

With real images (Debian/Ubuntu bases rebuilt by a corporate pipeline):
unpack sha256:203dec0f…: failed to unpack `/var/lib/kiri/layers/.tmp-203dec0f…/usr/bin/perl5.38.2`
(layer entry: hrwxr-xr-x 0/0 0 2026-11-05 usr/bin/perl5.38.2 link to /usr/bin/perl)

What you expected instead

Docker, Podman and containerd resolve a hard-link target against the layer root, so a leading / is harmless. With Podman the same archive loads, create succeeds and docker cp <id>:/bin/tool-1.0 - returns the file.

In my case 3 of 4 images from our internal registry hit this (postgres, ActiveMQ Artemis, dotnet/aspnet base), while the public postgres:17 and mcr.microsoft.com/dotnet/aspnet:10.0-noble run fine.

Anything else

Probably in the guest agent's layer unpack with the tar crate (crates/kiri-init/src/linux/layers.rs): the error suggests an absolute link target is treated as outside the destination. I haven't debugged it. Stripping the leading / from link_name (and still rejecting .. that escapes the root) would match Docker without weakening the check.

Workaround meanwhile: re-pack the image into one layer with BuildKit, which writes relative link names (FROM <image> AS src / FROM scratch / COPY --from=src / /, then re-declare ENV/ENTRYPOINT/CMD/USER/WORKDIR). Builds on top of such images work already, since BuildKit unpacks the layers itself.

Activity

  1. libracoder commented on Nov 16, 2026

    @libracoder
    Owner

    Fixed by #398, now on main and in 0.2.2. Every hard link in a layer is now read from the layer's root, so an absolute target such as /usr/bin/perl unpacks as it does with Docker. A target that tries to leave the layer (/../../etc/hostname) is still refused. Checked with a fresh one-layer image on macOS, Linux and WSL 2. #322 will add its e2e test for this.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions