The cache-seeding tests seeded entry names under amd64 but resolved
the request against the host arch, so on an arm64 host the lookup
missed and the tests walked into the network path. Requests now pin
arch, matching the seeded names on any host. The tool gate uses
find_tool: on macOS the e2fsprogs binaries are keg-only, never on
PATH.
mke2fs built against libarchive populates an ext4 from a tarball in
one pass; Homebrew's bottle is not built that way, so when the found
mke2fs cannot take a tarball the builder unpacks the rootfs with the
library's own tar decoder and populates from the directory — slower,
and the run says so. The mkfs child is exec'd fresh, so it reads
DYLD_FALLBACK_LIBRARY_PATH (libarchive's keg) at startup.
The engine is libkrun.1.dylib, dlopen'd from the Homebrew kegs when
the loader's own search fails (bare sonames never reach the brew
prefix); the probe becomes a per-platform hypervisor probe — KVM on
Linux, sysctl + a real hv_vm_create on macOS, so an entitlement
denial (HV_DENIED) names the re-sign fix instead of surfacing as an
opaque krun_start_enter EINVAL. Tool lookup (mke2fs, debugfs) gains
the same keg fallback, and dyld_fallback_dirs() collects the kegs the
bare-soname dlopens (libkrunfw, libarchive) need in
DYLD_FALLBACK_LIBRARY_PATH. The machine child's parent-death contract
moves to a kqueue NOTE_EXIT watcher: macOS has no PR_SET_PDEATHSIG,
and SIGKILL-on-parent-exit is what keeps a killed caller from
stranding a booted machine.
utils::detect_shell lost to the image probe; krun_set_root and
krun_set_env have had no caller since the root crossed as a block
device. Unused FFI bindings rot where they stand.
The early return keyed on files alone, so an unlink-only call was a
silent no-op. No caller passes an empty file set today, but the
signature invites one, and the control-file unlink is the case that
must never vanish.
The fork contract lived in a comment inside run_prepared; an
embedder meeting it first in the public API docs, with the
fork-with-threads hazard spelled out, has a chance of honoring it.
Resolution ran before the cache was consulted, so every run of
alpine:3.23, ubuntu or any floating alias hit the CDN or
changelogs.ubuntu.com, and an offline run of a cached image died in
resolution instead of booting. The boot path now asks the cache
first: an alias boots the newest cached entry of its distro, within
the series or the edge flavor it floats in, and resolves upstream
only on a miss; pull and --no-cache still resolve upstream.
Exactly-named references (Ubuntu YY.MM, known codename, Alpine X.Y.Z)
resolve offline on every path; resolve_source folds into the policy,
which lives with the cache it consults.
Only :latest was treated as floating; any other unpinned tag skipped
the registry digest check, so a moved :v1.2 kept booting stale. Tags
are mutable pointers, that is what digest pins exist for; the pin
skip stays, the tag skip goes.
mke2fs creates and sizes the output file before it populates it, so a
build that failed mid-way left a recent-looking image full of zeros at
the final name - newer than the tarball, and trusted by the freshness
check forever after. The first run after the libarchive fix booted
exactly that wreckage: EXT4-fs "Can't find ext4 filesystem".
The build now lands in a sibling .part file and renames over the image
only on success, and the freshness check additionally requires the
ext4 superblock magic (s_magic, at byte 1080) before trusting an
existing image - caches already carrying wreckage rebuild over it on
the next run instead of needing a manual clean.
The run path shells out to mkfs.ext4 and debugfs from e2fsprogs; a
host without them fails at the first pull, so probe names them up
front like it names KVM and the engine.
The rootfs was a virtiofs share over an extracted tree, and that
showed: the tree's owners were the host user's, because an
unprivileged extract cannot chown to a tar's uid, and every chown
inside the machine failed with EPERM against the host side.
The rootfs crosses as a raw ext4 image now. mke2fs builds the cache
image straight from the entry tarball (-d takes gz, xz and zst, and
bakes each entry's recorded uid, gid and mode), the run copies it
into a scratch directory with cp --reflink=auto --sparse=auto, and
the engine attaches it with krun_add_disk +
krun_set_root_disk_remount; the init blob mounts /dev/vda at / and
chroots. The OCI layer bundle merges into one plain tar first, with
whiteouts applied across layers and headers passed verbatim, so
registry images keep their ownership too.
Per-run provisioning rides debugfs: the generated init lands at
/ecrou-init, the host resolver overwrites /etc/resolv.conf (unlink
first - resolver-bearing images ship it as a symlink), a stale
control file goes. The exit-code control file now outranks the
machine child's exit code: with a block root the engine's exit-code
channel (an ioctl through the virtiofs root device) never fires, so
decode_status reads the file first and treats the child's code as
machinery talk. Shell detection and the rare control-file read are
debugfs stats, no extracted tree to walk.
extract.rs keeps what the image build consumes (the tar decoder and
the OCI merge) and drops the extraction-to-disk path it once carried;
the module is private now. The engine needs the blk feature from here
on: the snap and the CI engine build follow in their own commits.
The list view now says what each command does in the plainest verbs:
run boots a command from an image, pull downloads one, probe checks
the requirements. The long help keeps the contracts — freshness
semantics, what probe actually tests.
The runtime runs images; building them belongs to the OCI ecosystem —
CI builds, digests, scanning — and a keyed local layer could never
offer a digest. Provision also installed packages through TSI, whose
per-stream throughput makes a real package install crawl exactly at
first use, and the bare-command shape mutated the shared cache entry
under the image's own name.
0.1 runs images: run, pull, probe — distro aliases, OCI references
with digest pins, local rootfs archives. The one honest idea provision
carried stays in SPEC's Later: provision by booting, for locked-down
hosts that cannot run any builder.
Each command keeps a crisp one-liner in the command list and carries
its contract in the long help: how an image reference resolves, what
provision's two shapes do, why pull exists (run never contacts a
registry on a cache hit), and what probe checks. Flag help states the
real constraints instead of the shortest noun phrase: the guest path
of a share must be absolute, the host environment is never inherited,
--capture is refused with --tty, --quiet silences engine and kernel
messages.
The remediation hard-coded kvm_intel, wrong on arm64 and riscv64
which the snap now ships. x86_64 keeps the vendor split (kvm_intel,
kvm_amd) and the nested-virt parameter file; everywhere else KVM is
one module and the nested pointer is not actionable.
A parent-side failure after the fork (a console stat or read that
went wrong, a wait that could not complete) used to return and leave
the VM booting unattended. PDEATHSIG only fires when the caller's
process exits; a library consumer that catches the error keeps
running, and the scratch rootfs goes away under the machine.
kill_machine is best effort: a machine that already exited reaps
through ECHILD. Also drops a duplicated fork-error block left behind
by the supervise split.
Only the guest init can mint a guest code: it reports the payload's
code through the control file and the VMM exits the child with it. A
signal on the machine child therefore means the VMM or the engine
died; mapping it to 128+n masqueraded an OOM-killed VMM as the
payload having died by that signal (T3).
125 and 126 keep their two-sided reading: the child bails with 125 on
a boot failure and the init refuses with 126 on a failed share or a
missing workdir, but a payload may genuinely exit either code — the
control file is the arbiter, and a run that never reached the payload
is an error naming the cause.
The SPEC bar for T6 is failure on a single hit from the denied set;
the errno-based check only caught attempts the snap's seccomp
allowlist had already denied, so a host mount that succeeded would
have passed. Exact-name matching over the traced call also stops
"mount" matching "umount2" lines.
Fetch or refresh an image's cache entry without booting it. The
command is the CLI face of the run/pull split: runs never contact a
registry on a cached image, pull does - reporting the entry path
and whether anything transferred. --no-cache forces a redownload.
SPEC documents the command and the run/pull trust model.
prepare was a freshness hybrid: runs of an unpinned OCI tag contacted
the registry on every boot, and only ":latest" was checked - :main
floated in name only. Docker's split is cleaner, so it is the model
now: prepare (and run) trust a present entry and never touch the
network on a hit - a cold cache pulls by default, since there is
nothing to boot otherwise. RootfsCache::pull is the refresh
operation: re-check any unpinned tag against the registry digest,
re-resolve floating distro aliases, download only what moved,
extract nothing. Digest pins stay immutable to both. The trade, as
in docker: a stale :latest boots until someone pulls.
Local archives are not pullable - the error says so.
A run blocked on the cache-entry flock was silent: the wait went to
the log sink, which renders nowhere by default, so the CLI read as
a hang. The Progress trait gains message() - a status line outside
the counted-operation protocol, defaulting to a no-op so existing
sinks keep compiling - and the flock wait reports what it is
waiting for. The CLI renders messages on the active bar and spins
one up when no operation is active.
generate_cache_filename derived a distro tarball's extension by
resolving its URL - a naming function with a network dependency and
a silent unwrap_or_default degradation. Naming is now pure string
shaping: distro artifacts are gzipped tarballs, so the name says
.tar.gz, and a future artifact format changes extraction and this
line together. Same filenames as before for every existing entry;
a caller skipping resolve_source now gets a deterministic key
instead of a lookup.
The cache stopped being an implementation detail of the rootfs
lifecycle: entry naming, the advisory lock, digest freshness,
provisioned-layer pointers, and extraction-to-scratch are a store
in their own right. cache.rs now owns RootfsCache's paths, pointers
and extraction products; rootfs.rs keeps the lifecycle API
(PrepareRequest, PreparedRootfs, prepare, prepare_provisioned).
resolve_source moves next to its inputs in distro. Pure movement -
naming still derives its extension from the URL, next commit
changes that.
entry_path spliced the layer key into the cache filename raw: the
guard lived at the write/extract/prepare boundaries, so a library
consumer deriving paths through resolved_entry_path could get a
path outside the cache directory instead of the named error.
entry_path now returns Result and validates, prepare drops its now
redundant pre-check.
Ubuntu tarballs came from the daily/current directories - moving
targets, no published checksums guarantee, gone when a release
EOLs. resolve_ubuntu_url now builds the cdimage release URL:
ubuntu-base/releases/<YY.MM>/release/ubuntu-base-<YY.MM>-base-<arch>.tar.gz,
whose SHA256SUMS the existing checksum verification consumes.
Resolution returns the YY.MM number (the cache key follows), and
accepts the codename interchangeably: a static table maps the
known codenames offline - ubuntu:resolute and ubuntu:26.04 are the
same image and the same entry - with meta-release as a fallback
for codenames newer than the table. Floating aliases (latest/lts)
still consult meta-release; explicit numbers never touch the
network, which also removes the per-cache-path network lookup
generate_cache_filename used to trigger for codename inputs.
URLs verified live: tarball and SHA256SUMS both 200.
Docker pulls ubuntu@sha256:... and repo:tag@sha256:...; ecrou
errored on the '@'. parse_oci_ref now peels the pin (which contains
the reference's only legal post-slash colon), validates it as
algo:hex, and the manifest is fetched by digest - the tag, when
co-present, is ignored the way docker ignores it. Pinned
references are immutable by definition: the :latest freshness
check skips them, and the cache filename carries the pin so a
tagged ref and its pin never share an entry. Pull parameters
gather into registry::OciPull.
Two concurrent cold runs of the same image both downloaded it; the
atomic rename made it safe, not cheap. prepare now takes an
exclusive flock on a <entry>.lock sidecar before downloading, so a
second run waits and reuses the winner's entry - re-deriving the
freshness answer under the lock, since the digest it saw may be
its own download. no_cache callers skip the lock: an explicit
fresh download never waits. Locks release on process death, so a
crashed run cannot wedge the cache.
A virtiofs mount that failed (bad fsconfig, missing share) was
swallowed: the payload ran without its data and the only symptom
was a confusing failure downstream. The init now names the share
tag and target on the console and exits 126 - the same contract as
an unreachable workdir - instead of booting a run that cannot do
its job.
A caller share targeting /.ecrou-io (or inside it) shadowed the
capture share's files, and one at /.ecrou-exit or '/' shadowed the
exit handshake; collect_shares never looked at guest targets. The
capture share itself still owns the namespace by design; workspace
and --share are validated like any other caller share. The overlap
check takes the rootfs path directly.
A layer name lands verbatim in file paths: layers/<name> for the
pointer, <entry>.<key>.tar.gz for keyed entries. --layer ../x
escaped the cache directory on write and read alike. Names are now
restricted to [A-Za-z0-9._-] without a leading dot, enforced at
every surface that accepts one (write, read, extract, and the
prepare_provisioned layer key).
A .tar.bz2 tarball fell through extract's compression dispatch to
the magic-byte fallback and died as garbage tar errors; a bzip2
distro URL would spend the whole transfer first (download now
rejects it before spending the transfer). No bzip2 decoder exists
in the tree, and none is planned.
A download that died mid-stream (read error, digest mismatch)
returned before progress.finish(), leaving the sink with an open
operation — a lingering progress bar in the CLI and a broken
begin/finish pairing for any other sink.
The library is blocking end to end — vm::run waits on the machine
for the payload's whole lifetime — so the async interior bought no
concurrency (OCI layers download sequentially) and nothing any
consumer shape could use; each call rented a tokio runtime with
'Failed to create Tokio runtime' as a user-visible failure mode.
download.rs and registry.rs move to reqwest::blocking, folding the
runtime wrappers away; distro.rs joins the same client shape,
which also gives its metadata calls their first timeouts. The
shared client bounds the connect and, for small metadata bodies,
the whole request; transfers stay unbounded (the blocking client
has no per-read window; a stalled stream is the operator's
Ctrl-C). tokio and futures-util drop out as direct dependencies;
tokio remains transitively under reqwest.
vm.rs composed run options and supervised the machine process in
one file. The process half moves out: the fork that enters the VM
loop, the console relay, the wait and exit-status decode, and the
termios save/restore. run_prepared keeps the composition and calls
into the new module. No behavior change.
rootfs.rs mixed the cache lifecycle with the tree-to-tarball
writer that persisting relies on. The packer moves to pack.rs
beside extract.rs: pack_rootfs becomes crate-internal, its
partial-cleanup test moves with it. No behavior change.
download.rs carried two clients in one file: the plain transfer
plumbing and a full OCI Distribution Spec client (token auth,
manifest lists, layer blobs). The registry half moves to its own
module; download.rs keeps hashing, checksum files and file
transfers. fetch_oci_digest moves with it; rootfs imports it from
the new home. No behavior change.
The freshness digest check and the distro checksum fetch kept the
total 30 s request timeout the transfer clients just lost. They
move to connect + read windows, matching the one policy.
Config::load was never called: the DNS-override story it carried
contradicts the actual resolver flow, and nothing in the CLI or
snap advertised a key. Delete the module and every mention of the
ecrou.yaml file in SPEC and the snap; the XDG_CONFIG_HOME redirect
in the command chain served only that file.
validate_memory_string predates vm::parse_memory_mib and nothing
calls it; the qemu_* name mappers and their tests served the QEMU
engine that never shipped. The Arch variants stay: they feed the
debian/OCI/Alpine name mappings and the host-arch detection.
KvmUnavailable and ArchNotAvailable were raised as anyhow context
strings and wrapped into Other at the public boundary, so the
matching lib.rs documents never fired. They now ride at the top of
an anyhow chain and the manual From recovers them by downcast;
KvmUnavailable carries the open(2) error as its source instead of
swallowing it.
This changes the API: KvmUnavailable is a struct variant.
Downloads, OCI bundle packing and rootfs packing all wrote through
one fixed partial name, so two processes preparing the same entry
interleaved bytes and renamed the wreckage into place for good.
Each writer now gets a unique partial file (utils::partial_path)
and the last atomic rename wins with whole bytes either way; the
layer pointer is written the same way.
The 300 s client timeout covered the whole body stream, so any
download slower than a couple of MB/s died mid-transfer. Connect
and per-read windows catch dead peers and stalls instead; slow
transfers now finish.
The termios save ran after fork, so a child that reached raw mode
first would be captured and later restored as-is. A caught signal
interrupted waitpid, failed the run, and left the machine running;
EINTR now retries the wait.
Whiteout markers trusted the archive's own path, so a crafted
`.wh.` entry carrying `..` could delete host directories above
the rootfs. Both branches now go through `safe_join`, and a
`.wh..` marker, whose target is the parent directory itself, is
refused with them.
The founding rule restated SPEC.md, which stays the source of truth
for the confinement budget. Commit bodies gain a length cap, and a
commit must build and work on its own; bisectability outranks the
one-component-per-commit split when the two collide.
vhaudiquet