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.
Same dlopen as the snap stages for: the runner has e2fsprogs but not
the lib, and the first cold pull would fail. The t64 name with a
fallback keeps it honest if the runner image changes base.
Populating an ext4 image from a tarball is a runtime dlopen of
libarchive in mke2fs, not a linked dependency: the deb does not pull
it in, the stage set did not have it, and the first snap build failed
with "you need libarchive to be able to process tarballs". Stage
libarchive13t64 next to e2fsprogs.
The design paragraphs follow the code: the rootfs crosses as a raw
ext4 image built from the tarball, ownership is real inside the
machine, provisioning rides debugfs, and the control file mints the
exit code because the engine's own channel is virtiofs-root only.
The confinement budget admits the e2fsprogs children and cp, the
snap section stages e2fsprogs and names the blk feature, and the
boot-economics row counts an image copy instead of an extraction.
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 T6 run boots from a block device now; an engine without the blk
feature fails the lookup for krun_add_disk and the audit never sees a
machine. Same feature set as the snap ships.
The rootfs boots from a virtio-blk disk now, and the blk feature is
what compiles the device into libkrun - without it krun_add_disk and
krun_set_root_disk_remount have no symbols and every run fails at
lookup. e2fsprogs joins the stage set for mkfs.ext4 (the cache image
build) and debugfs (per-run provisioning and the control-file read);
core26 ships 1.47.4, which knows how to build from a compressed
tarball.
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 summary takes the README tagline. The description now leads with
an Install section, shows a first run that opens a shell, and leaves
the XDG redirection internals out of the listing.
The version: key in snapcraft.yaml was a second number to bump by
hand, and between releases it read whatever it was left at. The ecrou
part now sets its version from [workspace.package] at pull time —
the same value clap reports with --version — so Cargo.toml is the
only place a version lives, and the release workflow stamps only
that. A missed match fails the pack loudly.
The pack lint flagged five empty metadata fields. They render on the
snapcraft.io listing, and contact is asked for at publish time. The
repo answers for website, source-code, and contact (the issue tracker,
since the listing is public); title matches the binary name.
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.
The keyed-layer design shipped: provision --spec hashes the spec with
its base reference and --layer names the entry for run --layer. The
row was describing the past as the future; what remains is eviction.
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 code is the source of truth now; what stays is the part code
cannot carry — the founding rule and confinement budget (fixed: the
budget said no child process, the machine child is one), the run
contracts (exit codes rewritten to match the engine-failure and
reserved-code semantics), the trust model, the falsification tests,
and the roadmap.
Cut: the engine call list, the RunOptions listing, the CLI flags
table, the cache layout tree, the workspace/module map, the ecr
porting table, and the open questions — all answered or all mirrors
of code that answers them faster.
libkrunfw5 ships for riscv64 in ubuntu-ports, not the main archive
(archive.ubuntu.com carries amd64 and arm64 binaries); the part now
maps each target arch to its pool and a pinned digest.
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.
The test has been declared as CI-only since it landed and never ran
anywhere. The job builds the engine from the tag the snap bundles,
takes libkrunfw from the pool, opens /dev/kvm, and runs the ignored
test with ECROU_BIN and LD_LIBRARY_PATH pointed at them.
The arm64 runner leg builds that platform natively, where libkrun
compiles and the libkrunfw part picks the arm64 pool .deb on its own.
Both snaps upload as artifacts and publish to stable from one job.
The pool carries an arm64 libkrunfw5 next to the amd64 one, so the
part now picks the flavor and the install path from the target arch
(CRAFT_ARCH_BUILD_FOR / CRAFT_ARCH_TRIPLET_BUILD_FOR) with the
checksum pinned per arch. riscv64 goes: the pool has no libkrunfw5
build for it, and libkrun does not target it.
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.
vhaudiquet