Documentation
¶
Overview ¶
Package image extracts a rootfs into a destination directory. There are two supported sources:
- SeedDir(src, dst, exclude): copy a local directory tree into dst. Used by `init --from <dir|/>` — the production path that wraps an existing container fs into a managed rootfs.
- MaterializeTarball(src, dst): extract a .tar / .tar.gz from a local path or http(s) URL. Used by `init --tarball <path>` for demos and air-gapped setups.
Both run on stdlib only and apply the traversal-safe extractTar / walk logic in this package — there is no separate "pull from a registry" path because that would either need go-containerregistry's heavy dep tree or a fragile HTML-scraping mirror crawler. Users who want a container image should `docker export` it to a tarball and pass it via --tarball.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MaterializeTarball ¶
MaterializeTarball extracts a .tar or .tar.gz at src (filesystem path or http/https URL) into destRootfs, which must already exist. The tarball stream goes through extractTar's traversal-safe handling (zip-slip / symlink-plant / hardlink-escape).
func SeedDir ¶
SeedDir copies the tree at src into dst, skipping any path in exclude (and not descending into excluded directories). It is best-effort: unreadable files (e.g. root-owned files when running unprivileged) and special files (devices, FIFOs, sockets) are skipped rather than aborting — so seeding from "/" inside a container works even as a non-root user.
If progress is non-nil it is called after each regular file with cumulative (files, bytes) counts — `init --from /` on a multi-GB image can take minutes, and a silent copy looks like a hang.
func TarDir ¶ added in v0.4.0
TarDir writes the tree at srcDir as a tar stream to w, optionally gzip- compressed. It is the inverse of extractTar and the building block behind `agentenv export`: the resulting stream re-extracts (via extractTar or `docker import` / `tar x`) to an identical rootfs. See TarInto for the per-entry semantics (mode/special-bit/symlink/hardlink handling).
func TarInto ¶ added in v0.4.0
TarInto walks srcDir and writes its entries into tw, prefixing each archive name with prefix (e.g. "nodes/<id>" so an agentenv bundle can carry several node rootfs trees in one tar). It does NOT close tw — the caller owns the writer, so multiple TarInto calls can share one tar.Writer (and one gzip stream).
seen maps inode → the archive name it was first written under, so files that share an inode (hardlinks) — within this call OR across earlier calls sharing the same map — are emitted as tar hardlink entries instead of duplicating their bytes. This preserves the copy backend's cross-node hardlink sharing (see backend/copy.go copyTree) inside the archive, keeping repo bundles compact. Pass a fresh map[uint64]string{} for an independent archive.
Regular files, directories, and symlinks are archived; character/block devices, FIFOs, and sockets are skipped, matching extractTar's policy (the sandbox mounts a fresh /dev at run time, so device nodes are irrelevant). Mode bits — including setuid/setgid/sticky — plus uid/gid and mtime are preserved so a restored rootfs behaves identically (sudo/su keep setuid, /tmp keeps 1777, etc.).
Types ¶
type Progress ¶ added in v0.2.0
Progress reports seeding progress. It is called after each regular file is copied, with the running count of files and bytes copied so far. Callers typically throttle their own rendering (it fires very frequently); pass nil to SeedDir to disable. Directories and symlinks don't trigger it (they carry ~no bytes and would just add noise to a "GB copied" readout).
Source Files