Skip to content
Tutorials Center
My learning

Topics

Lesson 42 of 111 ยท Containers in Depth

Namespaces, cgroups and Container Internals

Look under the hood of a container: Linux namespaces, cgroups v2, user namespaces, capabilities and seccomp, with real commands you can run and compare.

There is no "container" object in the Linux kernel. What Docker calls a container is an ordinary process (or a few) that the kernel has been told to treat specially in three ways. Namespaces limit what the process can see. Control groups (cgroups) limit what it can use. A set of security filters (capabilities, seccomp, masked paths) limit what it is allowed to do. A root filesystem built from image layers completes the illusion.

How Docker Works introduced these ideas in a few paragraphs. Here you take them apart one at a time and prove each with a command. Every output below is real, from Docker 29 on a Linux 6.18 kernel (the WSL2 one inside Docker Desktop). Once you can read these signs, container behavior stops being mysterious: a process that cannot see the host, a program killed with exit code 137, a "permission denied" for something root should be allowed to do.

flowchart LR
    P(("Process")) --> NS["Namespaces<br/>what it can see"]
    P --> CG["cgroups<br/>what it can use"]
    P --> SEC["Capabilities, seccomp,<br/>masked paths<br/>what it may do"]
    P --> FS["Root filesystem<br/>from image layers"]

A container is a process wrapped in four layers of restriction, all enforced by the host kernel.

Namespaces: a private view

A namespace wraps a global system resource so that processes inside it see their own private instance. Linux has eight kinds, and Docker gives each container its own of most of them.

Namespace Isolates What the container sees Docker option to share with the host
pid Process IDs Its own process tree; the first process is PID 1 --pid=host
net Network devices, IPs, routes, ports Its own interfaces, its own localhost --network host
mnt Mount points Its own root filesystem and mounts (bind mounts)
uts Hostname and domain name Its own hostname --uts=host
ipc Shared memory, semaphores, message queues Its own IPC objects --ipc=host
user User and group IDs Different UID mapping (off by default) --userns=host
cgroup The view of the cgroup tree Its own cgroup as the root --cgroupns=host
time Clock offsets (boot time) Rarely used n/a

You can see a process's namespaces under /proc/<pid>/ns. Two processes in the same namespace point to the same object:

CONSOLE
$ docker run --rm alpine ls /proc/self/ns
cgroup
ipc
mnt
net
pid
pid_for_children
time
time_for_children
user
uts

Each name is a link such as net:[4026532817]; the number identifies the namespace. A different container shows different numbers for mnt, net, pid, ipc and uts, but the same user number as the host, which tells you something we will return to.

PID, UTS and network, one at a time

CONSOLE
$ docker run --rm alpine sh -c 'echo "my pid is $$"; echo "pid 1 is $(cat /proc/1/comm)"'
my pid is 1
pid 1 is sh

$ docker run --rm --pid=host alpine sh -c 'echo "pid 1 is $(cat /proc/1/comm)"'
pid 1 is initd

$ docker run --rm --hostname demo alpine hostname
demo

$ docker run --rm --network none alpine sh -c 'ip -o link | cut -d: -f2'
 lo

In its own PID namespace the container's first process is PID 1, and it cannot see anything else on the machine (PID 1 also has special signal rules, covered in Signals and Init Processes). With --pid=host the same alpine command sees the host's real init process, which is exactly why that flag is dangerous in production. --hostname only changes the UTS namespace. And with --network none the network namespace contains nothing but the loopback interface, lo: the container exists, with no way out.

Sharing a namespace on purpose

Because namespaces are independent objects, containers can join each other's. This is how sidecars work, and how Kubernetes pods are built:

CONSOLE
$ docker run -d --name web nginx:alpine
$ docker run --rm --network container:web alpine wget -qO- http://127.0.0.1 | grep -o '<title>.*</title>'
<title>Welcome to nginx!</title>

The second container never published or linked anything. It shares web's network namespace, so 127.0.0.1 is the same loopback, and it reaches nginx directly. The same trick with --pid=container:web lets a debugging container see another container's processes, a technique used in Debugging Containers.

Creating a namespace yourself

The unshare tool starts a command in new namespaces. The Docker default profile does not let a container create namespaces, which is itself a security feature:

CONSOLE
$ docker run --rm alpine unshare --uts hostname x
unshare: unshare(0x4000000): Operation not permitted

If you deliberately relax the security (never do this outside an experiment), it works and shows what the kernel is doing for every container:

CONSOLE
$ docker run --rm --cap-add SYS_ADMIN --security-opt seccomp=unconfined alpine \
    sh -c 'unshare --uts --fork sh -c "hostname inner; hostname"; hostname | wc -c'
inner
13

$ docker run --rm --cap-add SYS_ADMIN --security-opt seccomp=unconfined --security-opt apparmor=unconfined alpine \
    sh -c 'unshare --pid --fork --mount-proc sh -c "echo pid=\$\$; ls /proc | grep -c \"^[0-9]\""'
pid=1
3

The first command changes the hostname in a new UTS namespace and the container's own hostname is untouched (12 characters plus a newline is 13). The second creates a new PID namespace: the shell inside becomes PID 1, and /proc has only three process entries. A "container" is nothing more than this, repeated for several namespace types at once, by a runtime.

User namespaces and the meaning of root

By default Docker does not use a user namespace, so UID 0 inside the container is UID 0 on the host. You can see the mapping in /proc/self/uid_map:

CONSOLE
$ docker run --rm alpine sh -c 'id -u; cat /proc/self/uid_map'
0
         0          0 4294967295

Read the three numbers as "container UID 0 maps to host UID 0, for 4,294,967,295 IDs": an identity mapping. Root in the container is root on the host, merely restricted by the filters described below. That is why the advice in Users and Permissions is to run as a non-root user.

A user namespace breaks that equivalence. With a mapping like "container 0 maps to host 100000", a process that believes it is root is just an unprivileged user outside, so an escape gives far less. Docker offers it through the daemon option userns-remap and through rootless mode; it is off by default because it complicates volumes and some features.

cgroups: a budget for resources

A control group is a node in a tree maintained by the kernel. Processes belong to a group, and the group has controllers that account for and limit resources. Modern distributions use cgroup v2, one unified tree under /sys/fs/cgroup. Inside a container you see only your own branch as the root:

CONSOLE
$ docker run --rm alpine sh -c 'cat /proc/self/cgroup; cat /sys/fs/cgroup/cgroup.controllers'
0::/
cpuset cpu io memory hugetlb pids rdma

0::/ means "unified hierarchy, I am the root", thanks to the cgroup namespace. The controllers that apply are CPU, memory, I/O, PIDs and a few more. Their settings are plain files. The Docker flags from Resource Limits simply write numbers into them:

CONSOLE
$ docker run --rm -m 64m --cpus 0.5 --pids-limit 20 alpine \
    sh -c 'cat /sys/fs/cgroup/memory.max /sys/fs/cgroup/cpu.max /sys/fs/cgroup/pids.max'
67108864
50000 100000
20
Docker flag File Value written
-m 64m memory.max 67,108,864 bytes
--cpus 0.5 cpu.max 50000 100000: 50 ms of CPU time per 100 ms period
--pids-limit 20 pids.max 20 processes and threads
--cpu-shares 512 cpu.weight A converted relative weight (59 here; the default is 100)

The limits behave differently. cpu.max throttles: the process is paused until the next period, but not killed. memory.max is a hard wall: when a container needs more memory than it may have and the kernel cannot reclaim any, the OOM killer kills a process. You can provoke and observe it:

CONSOLE
$ docker run -d --name hog -m 16m --memory-swap 16m alpine \
    sh -c 'x=$(head -c 64000000 /dev/zero | tr "\0" a); echo done'
$ docker inspect -f 'oom={{.State.OOMKilled}} exit={{.State.ExitCode}}' hog
oom=true exit=137

Exit code 137 is 128 + 9: the process died from signal 9 (SIGKILL), sent by the kernel. OOMKilled=true confirms the cause. (--memory-swap equal to -m disables swap so the result is immediate.) Remember from Docker vs Virtual Machines that /proc/meminfo inside the container still shows the host's memory, because the limit lives in the cgroup, not in what /proc reports.

The filesystem and the security filters

Two more mechanisms finish the picture.

The root filesystem. The container's / is an overlay mount: the read-only image layers stacked, plus one thin writable layer on top. The runtime switches the container's root to it with pivot_root inside the new mount namespace.

CONSOLE
$ docker run --rm alpine sh -c 'mount | grep " on / " | cut -c1-30'
overlay on / type overlay (rw,

That is the layered storage of Image Layers, as seen by the kernel. Everything written to / goes into the top layer and disappears with the container.

Capabilities, seccomp and masked paths. Root's power is split into about forty capabilities (bind low ports, change file owners, load kernel modules...). Docker starts a container with a short default list and removes the rest. Seccomp adds a syscall filter that blocks several hundred dangerous calls. Certain /proc and /sys paths are masked or read-only. All of it is visible in the process status:

CONSOLE
$ docker run --rm alpine grep -E '^(CapEff|Seccomp):' /proc/self/status
CapEff:	00000000a80425fb
Seccomp:	2

CapEff is a bitmask of the capabilities the process has; a80425fb has 14 bits set, Docker's default set (a normal root shell on a host has about 40). Seccomp: 2 means a filter is installed. Together with the user-namespace default these explain why some root actions fail inside a container; the settings are covered in Capabilities and non-root and Seccomp and AppArmor.

Who builds all this?

You type docker run; the CLI asks dockerd, which asks containerd, which starts a shim and calls runc. runc is a small program that implements the Open Container Initiative (OCI) runtime specification: it reads a config.json describing the namespaces, cgroup limits, mounts, capabilities and seccomp profile, makes the corresponding kernel calls, and finally executes your program as PID 1 of the new world. After that, runc exits; the process runs under the shim.

sequenceDiagram
    participant U as docker run
    participant D as dockerd
    participant C as containerd
    participant R as runc
    participant K as Linux kernel
    U->>D: create and start
    D->>C: prepare image layers, OCI spec
    C->>R: start container
    R->>K: clone with new namespaces
    R->>K: write cgroup limits, apply seccomp and capabilities
    R->>K: pivot_root to the overlay filesystem
    R->>K: exec your program (PID 1)

runc performs the kernel calls that turn an ordinary process into a container, then hands over to your program.

Because the standard is open, the same image can run on other runtimes, including sandboxed ones (gVisor, Kata) that keep the interface but replace the isolation underneath.

Practical consequences

  • "It is just a process." From the host, container processes appear in ps and in top, and can be killed like any other. That is why docker stats can read their usage from cgroup files.
  • Exit code 137 is a SIGKILL: either the OOM killer (check OOMKilled) or docker kill / a stop that timed out. 143 is SIGTERM.
  • Sharing a namespace is a privilege. --pid=host, --network host, --ipc=host and --privileged remove walls; use them only for a reason.
  • Limits are enforced by the host, not the app. Set them in addition to runtime settings, such as the JVM heap, so the two agree.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which pair correctly matches a kernel feature with what it does for a container?

    Namespaces give a private view of PIDs, network, mounts and more. Cgroups account for and cap resources such as memory, CPU and process count.
  2. 2. A container exits with code 137 and docker inspect shows OOMKilled=true. What happened?

    137 is 128 + 9 (SIGKILL). With OOMKilled true, the cgroup memory limit was hit and the OOM killer acted.
  3. 3. What does docker run --network container:web alpine ... do?

    Namespaces are separate objects that can be joined. The new container shares the network namespace of web, so 127.0.0.1 reaches web's services.
  4. 4. By default, what is the relationship between UID 0 inside a Docker container and the host?

    Docker does not enable user namespaces by default, so /proc/self/uid_map is an identity mapping. That is why running as non-root, userns-remap or rootless mode matter.
  5. 5. What does --cpus 0.5 write into the cgroup?

    The CPU controller throttles the group's processes once they use their quota in a period; they are slowed down, not killed.

Summary

  • A container is a normal Linux process restricted by namespaces (what it sees), cgroups (what it uses), security filters (what it may do) and an overlay root filesystem.
  • Namespace types: pid, net, mnt, uts, ipc, user, cgroup, time. They can be shared on purpose (--network container:x, --pid=host).
  • The default has no user namespace: container root is host UID 0, held back by capabilities and seccomp (verify with /proc/self/status).
  • cgroup v2 limits are files: memory.max, cpu.max, pids.max, cpu.weight; memory overuse ends in the OOM killer (exit 137), CPU overuse in throttling.
  • runc applies the OCI spec by making these kernel calls, then executes your program as PID 1.

Next: Metrics, Tracing and Dashboards for Containers