retoor/doos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doos 1.0.0: images, size cap, subuid ids, working apt in host mode

Browse Source 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
retoor
2026-10-23 21:41:28 +02:00
co-authored by Claude Sonnet 5.5
parent fdb96c7b1c
commit d446c29372
24 changed files with 1709 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+47 -16
View File
@@ -1,6 +1,16 @@
# doos
Version: see `VERSION` (currently 0.1.3). Release history: `CHANGELOG.md`.
User-level containers in C++20: overlayfs, user/mount/pid namespaces, slirp4netns networking, optional images (Alpine, Ubuntu, or your own rootfs), a size cap per container. No root at runtime.
```
doos list
doos get_or_create [--image I] [--size S] [--net M] [--ids X] NAME
doos attach [--image I] [--size S] [--net M] [--ids X] NAME [-- CMD...]
doos delete [--yes] NAME
doos image list | add [--sha256 HEX] SOURCE [NAME] | delete [--yes] NAME
```
Version: see `VERSION` (currently 1.0.0). Release history: `CHANGELOG.md`.
User-level containers in C++20: overlayfs over the host's `/usr`, `/etc`, `/opt`, user/mount/pid namespaces, networking through slirp4netns. No root at runtime.
@@ -13,7 +23,7 @@ doos delete [--yes] NAME
Build: `cmake -S . -B build && cmake --build build`. Test: `tests/run.sh`.
Requirements: Linux >= 5.11, `slirp4netns` for the default network mode. On Ubuntu 24.04+ install the AppArmor profile once:
Requirements: Linux >= 5.11, `slirp4netns` (default network mode), `uidmap` (`newuidmap`/`newgidmap`, for more than one id inside; falls back to one id), `curl`, `tar` and `sha256sum` (images). On Ubuntu 24.04+ install the AppArmor profile once:
```
sudo cp apparmor/doos /etc/apparmor.d/doos && sudo apparmor_parser -r /etc/apparmor.d/doos
@@ -24,27 +34,42 @@ See `SPEC.md` (behavior, limits) and `docs/RESEARCH.md` (what works, measurement
## Usage examples
```
doos get_or_create dev # created dev
doos attach dev # interactive shell as root inside
doos attach dev -- apt --version # run one command
doos attach dev # host mode: your system's /usr as base, shell as root inside
doos attach --image alpine box # first use downloads and verifies Alpine, then opens a shell
doos attach --image ubuntu web -- apt-get update
doos attach --image ubuntu-24.04 old # a specific Ubuntu release
doos attach --size 8g big # raise the writable-layer cap (default 4g)
doos attach --net none sandbox -- sh # no network at all
doos list
doos image list # what is installed, what the catalog offers
doos delete dev # dry run: shows what would go
doos delete --yes dev # really deletes
doos image delete --yes alpine # refused while a container uses it
```
Container writes to `/usr`, `/etc`, `/opt` stay in the container (copy-on-write);
`/root` and `/var` are private and persistent. `/tmp` is memory-backed and lost on exit.
A container is `running` while its first `attach` command is alive; more `attach` calls
join it. Data persists until `delete --yes`.
Your own image (a root filesystem tarball):
## Current limits you will hit
```
doos image add https://example.org/debian-rootfs.tar.xz --sha256 <hex> debian # URL needs the hash
doos image add ./rootfs.tar.gz mybase # local file
doos attach --image mybase c1
```
Tools run fine (curl, git, gcc, python3, pip, ping all verified). Package management does
not: `apt-get update` needs a seeded `/var` and `-o APT::Sandbox::User=root`, and
`apt-get install` cannot finish configuring packages because host-root-owned files are
unwritable and unchownable inside. Details, measurements and the fix are in
`docs/RESEARCH.md` (G7, "Field trial").
## Host mode or image mode
| | Host mode (default) | Image mode (`--image`) |
|---|---|---|
| Base system | your `/usr`, `/opt`, copy of `/etc` | the image, extracted once and shared |
| Needs a download | no | first use only |
| `apt-get install` | works when the host is Debian/Ubuntu based | works for the image's own package manager (apt, apk) |
| Sees host files | `/usr`, `/opt`, readable `/etc` at creation | nothing from the host |
| Best for | quick throwaway shells with your tools | reproducible, separate systems |
Writes always stay in the container (copy-on-write); `/root` and `/var` persist, `/tmp` is memory-backed and lost on exit. A container is `running` while its first `attach` command is alive; more `attach` calls join it. Data persists until `delete --yes`.
## Size cap
`--size` limits what a container writes (default 4g, 64m to 1t). The parent checks every 10 s: a warning at 80%, at 100% the container is frozen (nothing is deleted), and it thaws on its own below 95% after you free space with a second `doos attach NAME -- ...`. Needs cgroup v2 delegation (standard on systemd desktops); without it the cap only warns.
## Configuration
@@ -59,6 +84,11 @@ unwritable and unchownable inside. Details, measurements and the fix are in
|---|---|
| `write /proc/<pid>/uid_map ... blocked` or `mount ...: Permission denied` | AppArmor restricts user namespaces. Install `apparmor/doos` (command above). |
| `slirp4netns failed to start` | Install `slirp4netns`, or use `--net none` / `--net host`. |
| `subuid mapping unavailable` | Install `uidmap` and make sure `/etc/subuid` and `/etc/subgid` list your user, or use `--ids single`. |
| `sha256 mismatch` | The download is not what the publisher lists; nothing was installed. Retry or check the source. |
| `a URL image needs --sha256` | Unverifiable input is rejected by design; pass the hash from the publisher. |
| `size cap only warns, cannot freeze` | No delegated cgroup v2 (no systemd user manager). Cap is advisory. |
| `doos: seeded ...: unreadable skipped: N` | Host entries the user cannot read were left out of the container. Informational. |
| `state path must not contain ',' or ':'` | Set `DOOS_HOME` to a plain path. |
| `container 'x' is running` on delete | Exit the attached command first. |
| `container limit reached (64)` | Delete one first. |
@@ -66,7 +96,8 @@ unwritable and unchownable inside. Details, measurements and the fix are in
## Safety summary
Host files are never written: system dirs are reached only through overlayfs. Host
`/home`, `/sys` and host loopback are not reachable in the default mode. `--net host`
`/home`, `/sys` and host loopback are not reachable in the default mode. Images are
verified against the publisher's checksum before they are extracted. `--net host`
removes network isolation and is opt-in. Known gaps (no cgroups, readable host `/etc`)
are listed with researched solutions (G1 to G6, not implemented) in `docs/RESEARCH.md`.