115 lines
3.9 KiB
Markdown
115 lines
3.9 KiB
Markdown
# ecr - ephemeral chroot
|
|
|
|
|
|
|
|
Instantly drop into a disposable Linux environment on your host machine.
|
|
No Docker daemon. No VM. No root. Just namespaces.
|
|
|
|
```sh
|
|
ecr debian # interactive Debian shell
|
|
ecr alpine:3.23 # specific Alpine version
|
|
ecr ubuntu:noble # Ubuntu by codename
|
|
ecr fedora # any Docker Hub image
|
|
```
|
|
|
|
## How it works
|
|
|
|
`ecr` pulls a root filesystem (Alpine/Ubuntu direct from their CDNs; everything else from Docker Hub), extracts it into a temporary directory, and execs a shell inside a user + mount + PID + UTS namespace. The process tree is isolated, the rootfs is discarded on exit, and your host is never touched.
|
|
|
|
## Usage
|
|
|
|
```
|
|
ecr [OPTIONS] <DISTRO[:VERSION]> [-- COMMAND...]
|
|
```
|
|
|
|
| Argument | Description |
|
|
|---|---|
|
|
| `ubuntu`, `alpine`, `debian`, `fedora`, … | Distribution to enter |
|
|
| `:version` | Optional version tag — codename, number, or `latest` / `lts` / `edge` |
|
|
| `-- cmd arg…` | Run a command instead of an interactive shell |
|
|
|
|
### Options
|
|
|
|
| Flag | Description |
|
|
|---|---|
|
|
| `--bind <PATH>` | Overlay-mount a directory read-only inside the chroot (default: current directory at `/root/<name>`) |
|
|
| `--bind-rw <PATH>` | Bind-mount a directory read-write at `/mnt/<name>` |
|
|
| `--no-bind` | Skip all directory mounts |
|
|
| `--no-cache` | Force a fresh download, bypassing the cache |
|
|
| `-v, --verbose` | Print diagnostic output (URLs, layer info, extraction steps) |
|
|
| `-a, --arch <ARCH>` | Target architecture (`amd64`, `arm64`, `armhf`, `riscv64`, …) |
|
|
| `--kernel [PATH]` | Boot with QEMU system emulation. Downloads Alpine's `linux-virt` kernel if no path provided |
|
|
| `-m, --memory <SIZE>` | Memory for QEMU VM (default: 2G, only with `--kernel`) |
|
|
|
|
## Examples
|
|
|
|
```sh
|
|
# Quick shell in the latest Debian
|
|
ecr debian
|
|
|
|
# Run a one-shot command
|
|
ecr alpine -- sh -c 'apk add curl && curl -s https://example.com'
|
|
|
|
# Work on your project inside Ubuntu — changes are visible on the host
|
|
ecr ubuntu --bind-rw ~/projects/myapp
|
|
|
|
# Native-compile for ARM64 through emulation (requires QEMU binfmt_misc)
|
|
ecr --arch arm64 alpine -- uname -m
|
|
|
|
# Always pull a fresh image
|
|
ecr --no-cache fedora
|
|
|
|
# Boot with QEMU system emulation (auto-downloads default kernel)
|
|
ecr --kernel alpine
|
|
|
|
# Boot with your own kernel
|
|
ecr --kernel /boot/vmlinuz ubuntu
|
|
|
|
# Boot with custom memory
|
|
ecr --kernel --memory 4G alpine
|
|
```
|
|
|
|
## QEMU System Mode
|
|
|
|
When `--kernel` is specified, ecr boots the rootfs in a full QEMU virtual machine instead of using namespaces:
|
|
|
|
```sh
|
|
# Auto-download Alpine's linux-virt kernel (recommended)
|
|
ecr --kernel alpine
|
|
|
|
# Use your own kernel
|
|
ecr --kernel /boot/vmlinuz ubuntu
|
|
```
|
|
|
|
This mode:
|
|
- Creates a gzipped CPIO initramfs from the rootfs
|
|
- Boots QEMU with your kernel (or auto-downloads Alpine's `linux-virt` kernel)
|
|
- Provides full VM isolation
|
|
- Works for any architecture (no binfmt_misc needed)
|
|
- Caches the default kernel in `~/.cache/ecr/`
|
|
|
|
Requirements:
|
|
- `qemu-system-<arch>` installed
|
|
- For custom kernels: kernel must have serial console support
|
|
|
|
## Supported distributions
|
|
|
|
| Name | Source | Version examples |
|
|
|---|---|---|
|
|
| `alpine` | Alpine CDN | `latest`, `stable`, `edge`, `3.23`, `3.22` |
|
|
| `ubuntu` | Ubuntu CDN | `latest`, `lts`, `noble`, `24.04` |
|
|
| `debian` `fedora` `arch` `gentoo` | Docker Hub | `latest`, any tag |
|
|
| Any Docker Hub / OCI image | Registry | `org/image:tag`, `ghcr.io/…`, `localhost:5000/…` |
|
|
|
|
## Cache
|
|
|
|
Downloaded images are cached in `~/.cache/ecr/`. For `latest` OCI tags the registry manifest digest is checked on each run — the image is only re-downloaded when it has actually changed. Use `--no-cache` to force a fresh pull regardless.
|
|
|
|
## Requirements
|
|
|
|
- Linux kernel ≥ 5.1
|
|
- Unprivileged user namespaces enabled (`/proc/sys/kernel/unprivileged_userns_clone` = 1 on some distros)
|
|
- `newuidmap` / `newgidmap` in `$PATH`
|
|
- An entry in `/etc/subuid` and `/etc/subgid` for your user
|
|
- For foreign-arch: QEMU user-mode emulation registered with `binfmt_misc`
|