ecr/SPEC.md

ecr - implementation specification

Synopsis

ecr [OPTIONS] <DISTRO[:VERSION]> -- [COMMAND]...

CLI Interface

Positional Arguments

• <distro> (required): Distribution name or OCI image reference
• <version> (optional): Distribution version/codename

Options

Flag	Default	Description
-a, --arch <arch>	host arch	Target architecture
--bind <path>	cwd	Directory to overlay-mount (can be specified multiple times)
--bind-rw <path>	none	Read-write bind mount at /mnt/<basename> (can be specified multiple times, overrides --bind for same path)
--no-cache	false	Download fresh tarball, ignore cache
--no-bind	false	Skip mounting any directory
--kernel[=PATH]	none	Boot with QEMU system emulation; downloads the default Alpine linux-virt kernel when no =PATH is given
-m, --memory <size>	2G	Memory size for QEMU VM (only used with --kernel)
-v, --verbose	false	Print diagnostic messages
-h, --help	-	Show help
-V, --version	-	Show version

File Layout

Cache Directory

~/.cache/ecr/
├── ubuntu-noble-amd64.tar.gz
├── alpine-latest-x86_64.tar.gz
├── debian-bookworm-amd64.tar.gz
└── ...

No metadata files. Tarballs are downloaded once and never redownloaded. Users can delete files manually or use --no-cache to fetch fresh.

Config File

~/.config/ecr.yaml:

dns:
  - 1.1.1.1

Distro Sources

Direct Tarball Downloads

Distro	Version Format	Source
Ubuntu	noble, jammy, mantic or 26.04, 25.10, 22.04, latest, lts	cdimage.ubuntu.com
Alpine	3.20, 3.19, latest, edge	dl-cdn.alpinelinux.org

Docker Hub (OCI Registry)

All other distributions use Docker Hub images via OCI registry API:

Distro	Image Reference
Debian	library/debian
Arch	library/archlinux
Fedora	library/fedora
Gentoo	gentoo/stage3
Custom	<image>[:tag] or <registry>/<image>[:tag]

Custom Image References

Users can specify any OCI-compatible image:

ecr debian:bookworm -- ./build.sh
ecr gentoo/stage3 -- emerge --sync
ecr gcr.io/my-project/my-image:v1.0 -- /app/test

Architecture Mapping

ecr	Ubuntu	Alpine	Docker Hub
amd64	amd64	x86_64	amd64
arm64	arm64	aarch64	arm64
armhf	armhf	armv7	arm/v7
riscv64	riscv64	riscv64	riscv64
ppc64el	ppc64el	ppc64le	ppc64le
s390x	s390x	s390x	s390x

OCI Image Download

For Docker Hub images:

1. Get anonymous bearer token from https://auth.docker.io/token
2. Query manifest list: GET https://registry.hub.docker.com/v2/<repo>/manifests/<tag>
3. Select manifest matching target architecture
4. Download layer blobs with authentication
5. Extract layers to rootfs

If architecture is not available in manifest list, error with available architectures:

Error: No manifest found for architecture 'riscv64'. Available: amd64, arm64, ppc64le, s390x

Execution Flow

1. Parse CLI arguments
2. Resolve distro/version/arch to image source
3. Check cache for existing tarball
4. If not cached, download tarball (direct or OCI)
5. Create temp directory for extraction
6. Extract tarball to temp directory
7. Create namespaces: user, pid, mount, uts
8. Set up mounts: /proc, /sys (ro), /dev, /dev/pts
9. Write /etc/resolv.conf with DNS servers
10. Set up overlay mounts for bind paths
11. Set up read-write bind mounts
12. Set environment variables
13. Exec shell or command in chroot
14. On exit, clean up temp directory

Namespace Setup

Namespaces (Always Created)

• user: Map current user to root (UID 0) inside
• pid: Isolated process tree
• mount: Private mounts for chroot setup
• uts: Hostname set to ecr-<distro>-<random>

Network

Host network namespace (no isolation).

User Namespace Mapping

uid_map: 0 <current_uid> 1
gid_map: 0 <current_gid> 1

This makes the user appear as root inside the chroot while remaining unprivileged on the host.

Mounts Inside Chroot

Path	Type	Options
/proc	proc	defaults
/sys	sysfs	ro,nosuid,nodev,noexec
/dev	devtmpfs	nosuid
/dev/pts	devpts	nosuid,noexec
/root/	overlay	lowerdir=<bind_path>, upperdir=, workdir=
/mnt/	bind	rw (for --bind-rw)
/etc/resolv.conf	file	written with DNS

QEMU Integration

Foreign Architecture Detection

If --arch differs from host architecture, QEMU is required.

binfmt_misc Check

Before entering chroot, verify binfmt_misc is registered for target architecture by checking /proc/sys/fs/binfmt_misc/qemu-<arch>.

If not registered, error with message:

Error: binfmt_misc not registered for riscv64

Install QEMU user emulation:
  Ubuntu/Debian: sudo apt install qemu-user-static
  Arch: sudo pacman -S qemu-user-static-binfmt
  Alpine: sudo apk add qemu-user-static

QEMU Binary

No action required. Modern qemu-user-static packages register binfmt_misc with the F (fix binary) flag, loading the interpreter into kernel memory. The kernel handles foreign binary execution transparently.

QEMU System Emulation Mode

When --kernel is specified, ecr switches from namespace/chroot mode to QEMU system emulation. The extracted rootfs is converted to an uncompressed CPIO initramfs and booted with the provided kernel.

Usage

The kernel path uses = syntax (--kernel=PATH); --kernel without a value downloads the default kernel. Without =, a following path would be parsed as the DISTRO argument.

ecr --kernel ubuntu:noble
ecr --kernel=/boot/vmlinuz ubuntu:noble
ecr --kernel=/boot/vmlinuz --memory 4G alpine
ecr --kernel=/boot/vmlinuz debian -- /bin/sh -c "echo hello"

Execution Flow

1. Download/cache rootfs tarball (same as namespace mode)
2. Extract tarball to temporary directory
3. Create uncompressed CPIO initramfs from rootfs (streamed to disk), including essential device nodes (/dev/ttyS0, /dev/null, /dev/tty) and an /init script that mounts proc/sys/dev, sets the hostname, execs the requested command argv verbatim (each argv element base64-encoded in the cmdline as ECR_ARGV), and powers off on exit
4. Launch QEMU with:
   • -kernel <path> - provided (or downloaded) kernel
   • -initrd initramfs.cpio - rootfs as initramfs
   • -append "console=ttyS0 [quiet] ECR_SHELL=... [ECR_ARGV=...] ECR_HOSTNAME=..." - kernel command line (quiet unless -v)
   • -m <memory> - memory size (default 2G)
   • -display none -serial mon:stdio - console on stdio
   • -netdev user,id=net0 -device virtio-net-pci,netdev=net0 - network NIC
   • -enable-kvm -cpu host - when the host supports KVM and the target matches the host architecture
5. Wait for QEMU to exit (init powers the VM off when the command/shell exits; -no-reboot makes QEMU terminate)
6. Cleanup temporary files

Initramfs Creation

The rootfs directory is converted to an uncompressed CPIO archive (newc format) using the cpio crate, streamed entry by entry so large rootfs images never need to fit in memory. Hard links are preserved: the first occurrence of a (device, inode) pair carries the data with a synthetic inode, subsequent occurrences are zero-size entries sharing that inode, which the kernel's initramfs loader turns into real hard links.

Architecture Support

ecr Arch	QEMU System Binary
amd64/x86_64	qemu-system-x86_64
arm64/aarch64	qemu-system-aarch64
armhf/armv7	qemu-system-arm
riscv64	qemu-system-riscv64
ppc64el	qemu-system-ppc64
s390x	qemu-system-s390x

Requirements

• QEMU system emulator installed (qemu-system-<arch>)
• Kernel with required drivers (serial console, virtio-net for network)

Differences from Namespace Mode

Feature	Namespace Mode	QEMU Mode
Isolation	User namespace	Full VM
Performance	Near-native	Emulated (KVM-accelerated when available)
Root access	No	Yes (inside the VM)
Foreign arch	binfmt_misc required	Built-in emulation
Bind mounts	Overlay/bind	Not supported (flags are ignored with a warning)
Network	Host network	User-mode NIC (not configured inside the guest)

File Handling

Overlay Mount (Default)

By default, the current working directory is mounted as an overlay filesystem at /root/<basename> inside the chroot, where <basename> is the name of the current directory.

Overlay configuration:

• lowerdir: the source directory (read-only)
• upperdir: temp directory for modifications
• workdir: temp directory required by overlayfs

Changes made inside the chroot are written to upperdir and discarded on exit. The host directory is never modified.

Multiple --bind paths can be specified, each creates an overlay at /root/<basename>.

Example:

$ cd ~/projects/myapp
$ ecr ubuntu:noble -- make build
# ~/projects/myapp mounted at /root/myapp
# Build artifacts written to overlay, discarded on exit

Read-Write Bind Mount

--bind-rw <path> creates a true read-write bind mount at /mnt/<basename>. This modifies the host filesystem directly. Use with caution.

Multiple --bind-rw paths can be specified. If a path is specified in both --bind and --bind-rw, the read-write mount takes precedence.

If no path is specified, defaults to current working directory.

No Mount

--no-bind skips mounting any directory.

DNS

Default DNS server is 1.1.1.1. Configured via /etc/resolv.conf in chroot:

nameserver 1.1.1.1

Override with config file (~/.config/ecr.yaml):

dns:
  - 8.8.8.8
  - 8.8.4.4

Environment Variables

Default environment inside chroot:

• HOME=/root
• USER=root
• SHELL=/bin/bash (or /bin/sh if bash unavailable)
• TERM=
• PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Host environment is not inherited.

Signal Handling

Forward SIGINT, SIGTERM, SIGHUP, SIGQUIT to child process. Wait for child to exit before cleanup.

Security Requirements

User Namespace Required

ecr requires unprivileged user namespaces. If unavailable (sysctl kernel.unprivileged_userns_clone=0 or AppArmor restrictions), error with:

Error: User namespaces not available

Enable with:
  sysctl -w kernel.unprivileged_userns_clone=1

Or check AppArmor profile restrictions.