🚨 Telegraf Error Guide: '[inputs.docker] Got permission denied ... docker.sock' — Fix Socket Access

Overview

The docker input talks to the Docker Engine API over the Unix socket /var/run/docker.sock. When the telegraf user is not allowed to open that socket, the plugin logs a permission error straight from the Docker client:

2026-07-10T12:00:00Z E! [inputs.docker] Error in plugin: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/info": dial unix /var/run/docker.sock: connect: permission denied

When Telegraf itself runs in a container without the socket mounted, the same plugin instead reports the socket is absent:

E! [inputs.docker] Error in plugin: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

No container or engine metrics are produced until access is fixed.

Symptoms

• All docker_* metrics (container_cpu, container_mem, docker engine stats) are missing.
• journalctl -u telegraf repeats Got permission denied ... docker.sock every interval.
• docker ps works for you (in the docker group) but fails as sudo -u telegraf docker ps.
• Telegraf runs in a container and the host socket was never bind-mounted.
• The error started after a host rebuild that recreated the socket with different group ownership.

Common Root Causes

• telegraf not in the docker group — the socket is srw-rw---- root docker and the service user lacks that group.
• Group change not applied — telegraf was added to docker but the service was not restarted.
• Socket ownership differs — some distros/rootless setups use a different group or path (/run/user/<uid>/docker.sock).
• Telegraf in a container without the socket mounted — the container cannot see /var/run/docker.sock at all.
• SELinux/AppArmor denial — MAC policy blocks socket access even with correct group membership (common with the :z/:Z mount flags missing).
• Rootless Docker — the daemon socket lives under the user’s runtime dir, not /var/run.

Diagnostic Workflow

Confirm the socket’s ownership and mode, then test access as the service user:

ls -l /var/run/docker.sock          # expect: srw-rw---- root docker
id telegraf                          # is 'docker' among its groups?
sudo -u telegraf docker version 2>&1 | head

Run only the docker input with debug to confirm the plugin sees the daemon after a fix:

telegraf --config /etc/telegraf/telegraf.conf --test --input-filter docker --debug

The docker input config points at the socket endpoint:

[[inputs.docker]]
  endpoint = "unix:///var/run/docker.sock"
  gather_services = false
  perdevice = false
  total = true
  timeout = "5s"

The standard fix is group membership plus a restart:

sudo usermod -aG docker telegraf
sudo systemctl restart telegraf
sudo -u telegraf docker ps >/dev/null && echo "socket OK"

When Telegraf runs in a container, mount the socket (read-only) and match the group id:

docker run -d --name telegraf \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --group-add "$(getent group docker | cut -d: -f3)" \
  telegraf:latest

For SELinux-enforcing hosts, check for denials before touching policy:

sudo ausearch -m avc -c telegraf --start recent

Example Root Cause Analysis

After a host was rebuilt from a golden image, docker_* metrics vanished and Telegraf logged Got permission denied ... docker.sock. ls -l /var/run/docker.sock showed srw-rw---- root docker, and id telegraf listed only telegraf — the automation that adds telegraf to the docker group had run in the old image but the group membership was not baked into the new one.

Running sudo -u telegraf docker version confirmed the client could not reach the daemon. Adding the user to the docker group and restarting resolved it:

sudo usermod -aG docker telegraf
sudo systemctl restart telegraf

Immediately after, telegraf --test --input-filter docker printed container metrics. The team then added usermod -aG docker telegraf to the image build so future rebuilds keep the membership. The lesson: adding a user to a group requires a fresh process — a running service must be restarted — and group membership must be provisioned in the image, not only at first boot.

Prevention Best Practices

• Add telegraf to the docker group as part of image/config-management provisioning, not a one-off manual step.
• Always restart the Telegraf service after changing group membership; existing processes keep their old groups.
• Prefer read-only socket access; the docker input only needs to read, so mount :ro in containerized setups.
• For containerized Telegraf, pass --group-add with the host’s docker GID so the in-container user matches.
• On SELinux hosts, add the correct policy/context instead of disabling enforcement, and use :z/:Z on socket mounts where appropriate.
• Verify with sudo -u telegraf docker ps in post-deploy checks so a missing group is caught before metrics go dark.

Quick Command Reference

# Inspect socket ownership/mode and the user's groups
ls -l /var/run/docker.sock
id telegraf

# Definitive access test as the service user
sudo -u telegraf docker version 2>&1 | head

# Grant access and restart
sudo usermod -aG docker telegraf && sudo systemctl restart telegraf

# Run only the docker input with debug
telegraf --config /etc/telegraf/telegraf.conf --test --input-filter docker --debug

# Check SELinux denials
sudo ausearch -m avc -c telegraf --start recent

Conclusion

[inputs.docker] Got permission denied ... docker.sock means the telegraf user cannot open the Docker socket — almost always because it is not in the docker group (or the service was not restarted after adding it). Confirm with sudo -u telegraf docker version, add the group, restart, and for containerized Telegraf mount the socket read-only with a matching --group-add. Bake the membership into provisioning and check SELinux on enforcing hosts, and container metrics will collect reliably.