Docker Engine, containerd, runc — what is in the package · Docker & Containers

When you install docker-ce you install five packages. They cooperate to give you the docker command. Knowing what each one does is the difference between “the daemon is broken” and “containerd is broken” — two very different troubleshooting paths, run against two different sets of logs.

The packages

Package	Provides	Role
`docker-ce`	`dockerd`, `docker-proxy`, `docker-init`	The daemon: API, images, networks, volumes
`docker-ce-cli`	`docker`	The client. Talks to a daemon over a socket
`containerd.io`	`containerd`, `containerd-shim-runc-v2`, `ctr`, `runc`	The supervisor, the per-container shim, and the OCI runtime
`docker-buildx-plugin`	`docker buildx`	BuildKit integration
`docker-compose-plugin`	`docker compose`	Compose v2

Two things about that table are worth pausing on.

runc ships in containerd.io, not in docker-ce. So does the shim. The Docker packages contain no container runtime at all. That is deliberate: a Kubernetes node can install containerd.io alone and never have Docker on it.

The CLI is a separate package from the daemon. They are versioned independently and can drift, which is why docker version reports them separately.

The call chain, and the process that is not there

Read-only / Safeversion— All four components, in one call. The bottom three come from containerd.io.

$ docker version

Client: Docker Engine - Community
Version:           28.5.1
API version:       1.51
Go version:        go1.24.8
OS/Arch:           linux/amd64
Context:           default

Server: Docker Engine - Community
Engine:
Version:          28.5.1
API version:      1.51 (minimum version 1.24)
OS/Arch:          linux/amd64
containerd:
Version:          v2.1.5
runc:
Version:          1.2.6
docker-init:
Version:          0.19.0

Illustrative output

Now look at what is actually running on a host with containers on it:

Read-only / Safeprocesses— Two daemons, one shim per container, one proxy per published port. No runc.

$ ps -eo pid,ppid,comm --forest | grep -E 'dockerd|containerd|docker-proxy|runc'

   1180       1 containerd
 1461       1 dockerd
 1499    1461  \_ docker-proxy
 2043    1180 containerd-shim-runc-v2
 2210    1180 containerd-shim-runc-v2

Illustrative output

`ps aux | grep runc` returns nothing, and that is correct

This is the fact that reorganises everything else, and almost nobody is told it.

runc is not a daemon and does not supervise anything. It is invoked, it does its work, and it exits. A healthy host running fifty containers has zero runc processes, and that is not a symptom.

What runc does in its brief life is create the namespaces, apply the cgroup settings, set up the mounts and the seccomp filter, and execve the entrypoint — then it gets out of the way, leaving your application as the process. The container is not “running inside runc”. It is a normal Linux process that runc configured.

The wrong diagnoses this produces are predictable, and all of them waste time:

“runc crashed, that is why the container died.” runc exited seconds after the container started, on purpose, and has nothing to do with the exit.
“I will restart runc to recover the container.” There is nothing to restart.
“runc is using no CPU, so the container must be idle.” runc’s CPU time is irrelevant; look at the application’s own process.

The corollary matters more: because runc is not there, runc cannot be the thing reporting the exit status. Something else has to hold the container’s stdout, stderr and exit code for the whole life of the container. That is the shim, and it is why one exists per container rather than one per host.

What actually happens on `docker run`

Four processes, three IPC hops, and one syscall sequence.

docker (CLI) to dockerd over /var/run/docker.sock, speaking the Docker HTTP API. The CLI resolves the image reference, but the daemon does the pull.
dockerd to containerd over gRPC on /run/containerd/containerd.sock. dockerd hands over an OCI bundle: a root filesystem, and a config.json describing namespaces, mounts, cgroup limits, capabilities, seccomp and the process to run.
containerd starts a shim. containerd-shim-runc-v2 is a separate process, parented to containerd, that will outlive the runtime invocation. It creates the pipes for stdio and a ttrpc socket for control.
The shim invokes runc create and then runc start. runc reads config.json, calls clone(2)/unshare(2) for the namespaces, writes the cgroup files under /sys/fs/cgroup/, pivots the root filesystem, applies the seccomp filter and the capability set, and execves the entrypoint. Then runc exits.
The shim remains. It holds the read ends of the stdio pipes, waits on the container’s PID 1, and reports the exit status back to containerd when it terminates.

You can read the exact bundle runc was given. It is the ground truth for every “why does this container have that limit / that capability / that mount” question, because it is what the kernel was actually asked for — not what you typed, and not what docker inspect reconstructs:

Read-only / SafeOCI bundle— The runtime spec the kernel was configured from. Requires root.

CONTAINER=web
ID=$(docker inspect --format '{{.Id}}' "$CONTAINER")

sudo cat "/run/containerd/io.containerd.runtime.v2.task/moby/$ID/config.json" \
| jq '{ process: .process.args,
        caps: .process.capabilities.effective,
        cgroup: .linux.cgroupsPath,
        namespaces: [.linux.namespaces[].type] }'

The path itself is informative: io.containerd.runtime.v2.task is the shim’s runtime plugin, and moby is the containerd namespace Docker uses. That namespace is the reason for the next failure mode.

When the layers disagree

Each layer has its own client and its own log, and using the right one is most of the diagnosis.

Read-only / Safelayer by layer— Ask each layer separately. Where the answers diverge is where the fault is.

# Layer 1: does the daemon answer at all?
docker info >/dev/null 2>&1 && echo "dockerd OK" || echo "dockerd DOWN"
journalctl -u docker -b --no-pager | tail -20

# Layer 2: does containerd answer, and does it see the same containers?
sudo ctr --namespace moby containers list
journalctl -u containerd -b --no-pager | tail -20

# Layer 3: are the tasks actually running?
sudo ctr --namespace moby tasks list

`ctr` without `--namespace moby` shows you an empty host

ctr defaults to the default containerd namespace. Docker’s containers live in moby. So the first time an operator reaches for ctr during an incident, they get an empty list and conclude containerd has lost everything — which is alarming, wrong, and leads directly to restarting containerd, which is the one action that genuinely does destroy the situation.

sudo ctr namespaces list shows which namespaces exist. Always pass --namespace moby when you are looking for Docker’s containers.

ctr is a debugging tool for containerd, not a supported management interface for Docker’s containers. Read with it. Do not write with it — creating or deleting tasks behind dockerd’s back leaves the daemon’s metadata store describing a world that no longer exists.

Symptom	Layer at fault	Evidence that confirms it
`Cannot connect to the Docker daemon`	dockerd, or the socket	`systemctl status docker`, `journalctl -u docker -b`
Daemon answers; every container operation errors	containerd, or its socket	`systemctl status containerd`; `ctr --namespace moby containers list`
Container fails to start with a permissions or mount error	runc, or the OCI config	`.State.Error` in `docker inspect`; the bundle `config.json`
Container exits 126 or 127	Not a layer fault at all — the image	`docker inspect --format '{{json .Config}}'`
`docker ps` empty but the application still serves	dockerd restarted and lost nothing; you are looking at live restore	`ctr --namespace moby tasks list`
Images disappeared after an upgrade	The image store switched	`docker info --format '{{.Driver}}'`

Read-only / Safecontainerd down— What a healthy daemon on top of a dead runtime looks like.

$ docker run --rm hello-world

docker: Error response from daemon: failed to create task for container: \
failed to dial "/run/containerd/containerd.sock": \
connection error: desc = "transport: Error while dialing: dial unix \
/run/containerd/containerd.sock: connect: connection refused"

Illustrative output

Note that docker info succeeds throughout this. The daemon is fine. Restarting docker.service will not help and, on a host where containers are still running under their shims, is a strictly worse move than starting containerd. Start containerd first, then re-test; only restart dockerd if it fails to reconnect.

Why the split exists

Three processes instead of one

A single binary could do all of it: serve the API, manage images, supervise containers, and configure the kernel. The separation buys three things that are each load-bearing.

dockerd is the API surface. It exposes the Docker API, resolves image references, manages networks and volumes, drives health checks and restart policy. It does not create a single namespace itself.
containerd is the supervisor. It pulls and unpacks images, manages snapshots, creates OCI bundles, and starts and tracks tasks. It does not know what a Dockerfile is, or what a Docker network is.
runc is the runtime. It knows nothing about Docker, registries, or images. It takes a directory containing a root filesystem and a config.json and turns it into a running process.

Each boundary is a real substitution point that somebody uses in production: Kubernetes talks to containerd directly through the CRI plugin and skips dockerd entirely; gVisor (runsc) and Kata replace runc without touching containerd or dockerd, configured through daemon.json’s runtimes map and selected per container with --runtime.

The operational payoff is the reason to care: the layers restart independently. systemctl restart docker with live restore does not disturb a single container, because the shims and the container processes are children of containerd, not of dockerd. That property is a direct consequence of the split, and it is why “restart the daemon” is a routine action on a Docker host and a frightening one on a monolithic runtime.

Verification that can fail

Read-only / Safecomponent check— Assert all four components report a version and that client and server agree.

set -e

CLIENT=$(docker version --format '{{.Client.Version}}')
SERVER=$(docker version --format '{{.Server.Version}}')

if [ "${CLIENT%%.*}" != "${SERVER%%.*}" ]; then
  echo "major version skew: client $CLIENT, server $SERVER" >&2
  exit 1
fi

docker version --format 'engine={{.Server.Version}} containerd={{.Server.Containerd.Version}} runc={{.Server.Runc.Version}} init={{.Server.Init.Version}}'

# The runtime layer answers independently of the daemon.
sudo ctr --namespace moby containers list >/dev/null
echo "all four components reporting"

A client and server on different major versions is worth failing a check over: the API negotiates down to the server’s version, so newer client subcommands and --format fields quietly stop working rather than erroring.

What happens if containerd is upgraded but dockerd is not?

Usually nothing, and that is the point worth understanding rather than a rule to memorise.

docker-ce declares a versioned dependency on containerd.io, and containerd maintains a stable API across its supported branches — currently the 1.7 LTS branch and the 2.x line. Within that contract, a containerd patch upgrade under a running dockerd is a supported operation.

Where it stops being routine is at a major containerd boundary. containerd went from 1.7 straight to 2.0, with no 1.8, and 2.0 removed deprecated APIs and config schema. A config.toml written for 1.x with version = 2 is not what a 2.x containerd expects, and the failure is at containerd start, not at Docker level — so the symptom is “all my containers stopped” with a perfectly healthy docker.service in the journal.

Two habits keep this boring:

Let apt resolve containerd.io from docker-ce’s dependency rather than pinning it independently. Pinning it is asserting a compatibility claim Docker has not made.
Treat a containerd major upgrade as a container-restarting change with its own window, exactly like a Docker Engine major upgrade — and read journalctl -u containerd first, not journalctl -u docker, when it goes wrong.

Knowledge check

Why this matters

The value of knowing these boundaries shows up in the first two minutes of an incident, when you decide which log to open.

An operator who thinks of “Docker” as one thing reads journalctl -u docker, finds nothing wrong, and restarts the daemon — which does not help, and on a host with a broken containerd underneath, throws away the one component that was still working. An operator who knows the stack asks each layer separately, sees where the answers diverge, and fixes that layer.

The runc detail is the one to carry away, because it is counter-intuitive and it comes up constantly. There is no runtime process supervising your container. There is a shim holding its stdio and its exit code, and an ordinary Linux process that something configured and then walked away from. Once that is clear, docker exec making a new process rather than entering a supervisor, cgroup limits applying to a normal process tree, and containers surviving a daemon restart all stop being surprising.