Reference Brief / Linux Kernel Namespaces

The kernel primitives behind every container

kernel 4.6+util-linuxOCI runtime spec Eight namespace types partition kernel state, accessed through three syscalls (clone, unshare, setns). Most types require CAP_SYS_ADMIN to create; the user namespace is the exception, which is why rootless containers are built on it. A container is one process per namespace plus cgroups plus an image. This brief covers the types, the syscalls, the inode model, and the ops paths, with hover-context on every underlined term.

The eight namespace types

Runtime models, in one paragraph each

runc / Docker / containerd: clone(2) with all CLONE_NEW* flags, capabilities trimmed, seccomp applied, pivot_root into a layered overlayfs rootfs, network plugged in by CNI.

Podman rootless: the user namespace is created first using your subuid range from /etc/subuid; all other namespaces are nested inside it so kernel capability checks pass against the namespaced credentials. No setuid binary on the hot path.

Kubernetes pod: the pause container holds the net and ipc namespaces; app containers join via setns(2). Mount, PID, UTS are per-container by default; PID can be shared with shareProcessNamespace: true.

From scratch (this repo): unshare --pid --uts --mount --ipc --net --cgroup --fork, mount /proc /sys /dev inside the rootfs, pivot_root. See demos/07-mini-container.sh. The rest of any runtime is image layout and policy.

Inode model

A namespace is a kernel object identified by an inode number. Two processes share a namespace iff their /proc/<pid>/ns/<type> symlinks resolve to the same inode. That is the entire ownership model.

Syscalls

Type matrix

PID namespace anatomy

Inside a new PID namespace, the first forked child becomes PID 1 with init semantics: it must reap orphans, and if it dies the kernel sends SIGKILL to every other process in the namespace. This is why tini, dumb-init, and Docker --init exist.

Network namespace anatomy

A new net namespace starts with a single lo interface, in the DOWN state. Connectivity is built by hand: a veth pair is a virtual ethernet cable; one end stays on the host, the other is moved into the namespace by ip link set ... netns .... Bridges, NAT, and routing finish the job.

User namespace and the UID map

The user namespace is the only one an unprivileged user can create directly. Inside the namespace, the kernel checks capabilities against the namespaced credentials, so the process can mount, change hostname, and create other namespaces. From the host the process is still its real UID and has no extra power on host-owned objects.

/proc layout

Persistence

A namespace lives as long as something references it: a process inside it, an open fd to its /proc/<pid>/ns/<type>, or a bind mount of that file onto a stable path. ip netns add foo uses the bind-mount trick under /var/run/netns/foo. nsm create uses a long-lived holder process. Both work, both leak if you forget to clean them up.

Building a container, phase by phase

1. Prepare a rootfs. debootstrap, docker export, or anything that drops a Linux userland into a directory. demo 07 step 0
2. Create a cgroup and set limits. cgroups v2: write to memory.max, cpu.max, pids.max. demo 07 step 1
3. unshare into all namespace types. --pid --uts --mount --ipc --net --cgroup --fork --map-root-user. demo 07 step 3
4. Mount /proc /sys /dev inside the rootfs. Without /proc, ps sees the host. inside the unshared shell
5. pivot_root into the rootfs. Real containers use this, not chroot. After umount -l /.old_root the host fs is gone. demo 07
6. Configure network. Create a veth pair, move one end in, assign IPs, add NAT on the host. demo 03
7. Drop capabilities, apply seccomp, exec the entrypoint. Educational demos skip this; production runtimes do not. runc, not bash

Operations and debugging

• Find a container's PID: docker inspect -f '{{.State.Pid}}' <name>, then everything is at /proc/<pid>/ns/. Same for podman, crictl, k8s.
• Enter without the daemon: nsenter --target <pid> --all bash works even when dockerd is wedged. The kernel doesn't care which userspace asked.
• Network debugging: nsenter --target <pid> --net bash then tcpdump, ss, iptables-save, ip route all run in the container's network view.
• Compare to host: read both readlink /proc/1/ns/X and readlink /proc/<pid>/ns/X; equal inodes mean the container is sharing that subsystem with the host.
• List system-wide: lsns, optionally -t net to filter, gives you holder-process and member counts.
• Watch for change: nsm monitor diff-walks /proc/*/ns/* once per second and prints additions and removals. Useful to catch a runtime spawning short-lived helper namespaces.

Pitfalls

• PID 1 dies, everything dies. If the container entrypoint is a shell that execs your app, the app becomes PID 1 and signal handling changes. Use tini or --init.
• Mount propagation surprises. A new mount namespace inherits propagation from the parent. If the parent is shared, mounts inside the namespace can leak to the host. Containers usually mount --make-rprivate / first.
• User namespaces interact with everything. Files written from inside as "root" are owned by your subuid range on the host. chown across the namespace boundary is gated by the map.
• cgroupv1 vs v2. The cgroup namespace is much more useful under v2, where the entire cgroup hierarchy is one tree. Under v1, hide-the-path matters less because controllers were already separate.
• net namespace teardown is not free. Closing a netns blocks until kernel cleanup completes. On busy hosts this can stall ip netns del for seconds.
• Time namespace is opt-in. Tools that read /proc/uptime or CLOCK_BOOTTIME see different values; tools that use CLOCK_REALTIME do not. The wall clock is shared.

References