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.
The run interface read like a library's. `ecrou run -it alpine` now
hands the guest a terminal: with no console output file, libkrun wires
the guest console to the process's own stdio and raw-modes the tty.
The parent saves and restores the termios around the run, because
libkrun's own restore lives in the child's exit observers, which a
SIGKILLed machine never runs. A tty run refuses to start without a
terminal on stdin and stdout, and --capture refuses to combine with
-t: the payload's streams cannot land in files and on the terminal at
once.
-i without -t keeps the machine's stdin open through pipes: libkrun
exposes the non-tty streams as virtio console ports (krun-stdin,
krun-stdout, krun-stderr), and the guest init points the payload's
stdio at whichever port nodes exist. `echo hi | ecrou run -i alpine --
cat` crosses the machine; a stream the host left on a tty has no port
node and stays on the console.
-v (--volume HOST:GUEST[:ro]) replaces --share, and -w aliases
--workdir. The global -v/--verbose loses its short flag to make room;
verbose stays reachable by its long form.
A reference starting with ./, ../ or / names a local rootfs archive:
read in place on every run, never downloaded, never cached as a
pristine entry. Provisioning over one persists into a derived cache
entry keyed by size and mtime, so the caller's file is never
overwritten and an edited archive lands in a fresh entry.
A provision command baked by hand - `ecrou provision alpine -- apk
add ...` - cannot be reviewed or shared: the artifact worth keeping is
a diff in git, not a shell history line. A spec file is that diff.
`ecrou provision --spec image.yaml` parses base, packages and a run
block, derives the provisioning script from the base's own package
manager (apt, apk, dnf, discovered at provision time on the running
machine), and bakes the result into a cache entry keyed by the spec's
content hash: the same file never provisions twice, an edited file
never reuses the old layer, and the key hashes the raw bytes so the
layer is stable across ecrou versions.
`--layer NAME` names the entry, and `ecrou run --layer NAME` boots it
directly - no image resolution, no download; the layer is whatever
the provision call persisted under that name. A keyed entry has no
tarball of its own, so the base downloads only on the first
provisioning and every later run extracts the finished layer.
prepare_provisioned and persist were sitting there with no consumer:
the machinery for "install once, every later boot carries it" that
one-shot machines cannot do on their own - packages, users, anything
short of a share - and no way to reach it.
ecrou provision IMAGE -- COMMAND is the missing surface. It boots a
machine over a freshly prepared rootfs, runs the command, and
persists the tree into the cache entry, marked provisioned; a marked
entry is extracted as-is on every later call, the command skipped.
A failing command leaves the entry unprovisioned for the next
attempt, and --no-cache re-downloads before re-provisioning.
The engine behind run splits out as vm::run_prepared: the boot half
of run, taking the rootfs the provisioner is about to persist. run
itself is prepare plus that.
One cache fix the provision flow surfaced: a digest refresh replaced
the tarball but left the old .provisioned marker, so a fresh pristine
image would present as provisioned and skip provisioning for good.
The marker now dies with the entry it belonged to.
With preservation on, the crate chmods every file to the mode it
ships as it extracts, and one refused bit killed the whole run:
alpine's usr/bin/chage ships setgid-shadow (02755, group shadow),
and an extracting context that cannot set the bit - an overlayfs
tmp, a confined sandbox - fails the chmod with EPERM and takes the
boot down with "failed to set permissions to 2755".
The crate's own chmod now runs with the special bits masked off,
which no filesystem refuses, and the shipped modes ride the fixups
like directory modes already do: applied after the walk, degraded
to plain rwx when the filesystem refuses them, exact everywhere
else. Unprivileged tar degrades the same way; the guest re-applies
whatever it needs. The setgid regression test pins the round trip.
The console is one stream, kernel and guest mixed, so a consumer that
needs the payload's stdout and stderr apart - rhema's sandbox seam
reports them as separate fields - could not get it. With capture set,
the run adds the directory as an internal rw share (guest path
/.ecrou-io, reserved) and the init wraps the payload in a redirection
group pointing at it: the streams land host-side as DIR/stdout and
DIR/stderr, written live, owned by the host user, and there when run()
returns. The console stays on stdout for diagnostics; the CLI exposes
the flag as --capture.
KVM runs only the host architecture, so the flag could not mean what
it suggested: a mismatched value downloaded a foreign rootfs that
extracted cleanly and died at boot with a cryptic guest-side exec
error. The flag's real job, picking the image variant to fetch, is
the library's; RunOptions.arch keeps that role and an empty value
still resolves to the host architecture.
The engine materializes a heuristics-driven TSI by default; disable
it and add an explicit vsock hijacking AF_INET so guest networking is
deterministic rather than sniffed. Throughput is unchanged in this
build (TLS crawls at tens of KB/s against a CDN either way) - that is
the new ln driver's own pace and belongs upstream; the flag at least
pins down which path the guest takes.
Copying /etc/resolv.conf verbatim gives the guest systemd-resolved's
stub at 127.0.0.53, and loopback never crosses the engine's socket
proxy: the name lookup dies inside the guest. Source the uplink
config from /run/systemd/resolve first and strip 127.x nameserver
lines from whatever is copied.
vhaudiquet
Valentin Haudiquet