How containers work, simulated

The diagram. A system diagram drawn from the simulator’s state. Along the top is the chain a command walks — you → docker CLI → dockerd → containerd → (shim →) runc — above a box for the Linux kernel with its subsystems (namespaces, cgroups, the overlay rootfs, the capabilities/seccomp/LSM gates, netfilter). Below are the containers and, depending on the View, their process trees, namespaces, cgroup meters, layer stacks, the build, the pull, the network topology or the security gates. Messages travel the wires as labelled packets, coloured by kind (daemon/API, kernel syscall, image blob, filesystem, packet, NAT rewrite, DNS, denied). Tap a container to inspect it and act on it (stop, kill, exec, start, remove). Turn on detail (below the terminal) to see the shim and each separate kernel step.

View switches what the main diagram shows without changing the simulation: Processes (the host’s PIDs vs the container’s), Namespaces (what each namespace lets the process see, with toggles to share one with the host), cgroups (a CPU timeline with throttling, a memory bar to the OOM point, a pids bar), Filesystem (the overlay layer stack, copy-up and whiteouts), Build (the Dockerfile step by step with cache hits and layer digests), Registry (tag → index → manifest → config + layers, with per-layer status), Network (docker0/user bridges, veths, the netfilter chains, published ports) and Security (the seccomp → capabilities → LSM gates).

Event log records what the kernel and daemon did; Key events hides the chatter.

Terminal accepts a small set of commands that drive the same diagram (see below).

A container is a process. docker run is a REST call to dockerd, which drives containerd, a containerd-shim-runc-v2 and the OCI runtime runc. runc calls clone() with new namespaces, sets up the cgroup, mounts the rootfs and `pivot_root`s, drops capabilities, applies seccomp, and `execve()`s your program as PID 1. PID 1 in the container is an ordinary high numbered PID on the host — the same process, two numbers (pid_namespaces(7)).

Namespaces (namespaces(7)): pid, mnt, net, uts, ipc, user, cgroup. Each narrows one global resource. --pid host, --network host, --ipc host and --uts host share one with the host. User-namespace remapping maps container uid 0 to an unprivileged host uid (user_namespaces(7)).

cgroup v2 (kernel: cgroup v2): cpu.max bandwidth control throttles a container to its quota per period (cpu.stat counts nr_throttled/throttled_usec); cpu.weight only shares CPU under contention. --cpu-shares becomes cpu.weight by runc’s formula 1 + (shares − 2) × 9999 / 262142, and --blkio-weight becomes io.weight by 1 + (weight − 10) × 9999 / 990. memory.max plus memory.swap.max drive the OOM killer, which kills a process in that cgroup only (memory.events oom_kill). pids.max makes a fork bomb’s fork()`s return `EAGAIN; without it the host’s task budget runs out.

overlayfs (kernel: overlayfs, overlay2 driver): the image layers are lowerdir, the container’s writable layer is upperdir, and the container sees the merged view. A read returns the top-most copy; writing a lower file copies it up first; deleting a lower file writes a whiteout; a directory recreated over a whiteout is opaque. Two containers from one image share every read-only layer.

Images are OCI structures. A layer is bytes whose SHA-256 is its DiffID; layers chain by ChainID = sha256(parent + " " + diffID) (OCI image config). The config and manifest are JSON documents addressed by the SHA-256 of their bytes; a multi-arch tag points to an image index that lists one manifest per platform (OCI image index). A pull fetches only the layers it doesn’t already have and verifies every blob’s digest (OCI distribution spec); pinning by digest is reproducible.

The build cache (build cache): each instruction’s cache key is its parent’s key plus the instruction text, and for COPY/ADD the checksum of the files it copies. Change a copied file and that step and everything after it rebuild; the steps before it, and a RUN whose inputs didn’t change, are reused. Order instructions by how often their inputs change (copy requirements.txt and install before copying the whole source).

Networking (bridge networking): each container gets a veth pair onto a bridge (docker0, or a per-network br-…) and an address from the network’s pool. A user-defined network has embedded DNS, so containers reach each other by name; the default bridge does not. Outbound traffic is MASQUERADE`d to the host IP; a published port (-p 8080:80`) is a DNAT rule in netfilter’s nat table that rewrites the destination to the container. --network none is loopback only; --network host shares the host’s stack.

Volumes (volumes): data on a volume survives docker rm; the writable layer does not; --tmpfs lives only in RAM. A bind mount maps a host path straight in.

Security (Docker security): Docker keeps ~14 of ~40 capabilities, applies a default seccomp profile (which gates many syscalls on a capability and blocks the keyring outright), and an AppArmor profile. A syscall passes seccomp, then the capability check, then the LSM. --read-only makes the rootfs read-only; user namespaces / rootless mode make container root unprivileged on the host (rootless). --privileged and a mounted docker.sock are effectively root on the host.

One host, one registry, a handful of images and containers. The simulator does not run real programs: a RUN step in a build and a container’s main process have their filesystem and network effects modelled, not executed, so file contents are stand-ins while the structure (layers, digests, rules, PIDs) is real.

Timeouts are compressed so failures play out in seconds; the stop timeout is 1 s, not Docker’s 10 s. cgroup accounting is a simple, deterministic model, not a benchmark.

Netfilter is drawn as Docker Engine ≤ 27 writes it (the nat table is the same in 28). No IPv6, no --userland-proxy=false nuances beyond the hairpin case, no overlay/swarm networking.

The seccomp model gates the syscalls the scenarios use; it is not the full ~44-call profile.