Repository navigation
Description
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
Apply hard-link header metadata and replace existing destinations
Check special inode metadata before and after a hard-link header
Use valid OCI layers for the hard-link replacement comparison
libracoder commentedon Nov 16, 2026
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/perlunpacks 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.