Diag: docker socket permission denied, fix group membership not chmod

TL;DR

For "permission denied": likely causes: (a) agent user not in the docker group (host install), (b) socket not mounted into the agent container, (c) socket mounted read-only or with wrong perms.

permission denied

Steps

1. Symptom (exact): agent log: permission denied opening /var/run/docker.sock. Container metrics missing, Docker check failing, everything else fine.
2. Likely causes: (a) agent user not in the docker group (host install), (b) socket not mounted into the agent container, (c) socket mounted read-only or with wrong perms.
3. Host: groups dd-agent (or the agent user). Missing docker is the answer.
4. As the agent user, try reading the socket. Permission denied reproduces it exactly.
5. Container: inspect the agent container mounts. No /var/run/docker.sock mount means the agent cannot see Docker at all, different symptom (no error, just no containers).
6. - Host: add the agent user to the docker group and restart the agent (group membership needs a fresh process).

• Container: mount the socket into the agent container per the docs.
• Do not chmod 777 the socket. Group membership is the fix; world-writable docker socket is a security incident.

5. Verify: Docker check OK in agent status, containers appear in Infrastructure, Containers. If you use containerd/crio instead of Docker, the socket path differs: configure the right runtime socket, not the Docker one.

When to use

You are seeing this: Symptom (exact): agent log: permission denied opening /var/run/docker.sock. Use this skill when you run into "Diag: docker socket permission denied, fix group membership not chmod".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The ECS and container docs require the agent container to access the Docker socket to discover containers; host installs need the dd-agent user in the docker group for the same. Verified against live docs 2026-09-26.