Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

dockerd will not start inside a Docker container

ErrorCould not mount /sys/kernel/security.

Short answer

Running Docker inside a container needs two things: the container must be started with --privileged, and on cgroup v2 hosts the processes must be moved into a child cgroup before controllers are enabled. The official docker:dind image does both. A hand-made image that starts dockerd directly usually fails on one of them.

  • Applies to Docker Engine 28, docker:dind image, Ubuntu 24.04 (cgroup v2)
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the host uses cgroup v2 and whether the failing container is privileged.

    ls /sys/fs/cgroup/cgroup.controllers   # this file exists on cgroup v2 hosts
    docker inspect --format '{{.HostConfig.Privileged}}' my-dind
  2. 2Match what you see, then jump to its fix

    1. 1Privileged prints false, and dockerd inside the container fails early on mounts.The container is not privilegedFix
    2. 2The container is privileged, the host is cgroup v2, and your own entrypoint runs dockerd directly.A custom image starts dockerd without the cgroup v2 setupFix

What does the error look like?

  • Could not mount /sys/kernel/security.
  • Writing to cgroup.subtree_control fails with EBUSY (cgroup v2)

Cause 1 of 2

The container is not privileged

1Check

The Docker Hub page for the docker image states that --privileged is required for Docker-in-Docker to function properly. The dind helper script is written to run in a privileged container, and it reports Could not mount /sys/kernel/security when it cannot mount.

docker inspect --format '{{.HostConfig.Privileged}}' my-dind

2Fix

Start the official dind image with --privileged. The flag is not a secure sandbox, so use it only on hosts you control and never expose the daemon without TLS.

docker run -d --name my-dind --privileged docker:dind

3Verify

Run a command through the inner daemon.

docker exec my-dind docker run --rm hello-world

Confirmed by hub.docker.com

Did this fix it?

Cause 2 of 2

A custom image starts dockerd without the cgroup v2 setup

1Check

On cgroup v2 the root cgroup has processes in it, so enabling controllers for children fails with EBUSY. The dind script in the Moby repository creates an init child group, moves the processes into it, and then writes the controllers to cgroup.subtree_control. It only does this when /sys/fs/cgroup/cgroup.controllers exists.

docker exec my-dind ls /sys/fs/cgroup/cgroup.controllers

2Fix

Use the official docker:dind image, or copy the dind script into your image and make it the wrapper around dockerd instead of starting dockerd on its own.

FROM docker:dind
# add your tools here, and keep the image's own entrypoint
RUN apk add --no-cache git

3Verify

Start the container and confirm the inner daemon answers.

docker run -d --name my-dind --privileged my-dind-image
docker exec my-dind docker info

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Prefer the official docker:dind image as the base for CI helpers.
  • Keep TLS on for any daemon reachable over the network.
  • Where possible, mount the host Docker socket for build jobs instead of nesting a daemon, accepting that the job then controls the host daemon.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.