Back to posts
31 July 2026 Gist: 31.07.2026 08:57

Troubleshooting Guide: Zabbix Agent 2 & Docker (Snap) Integration

If your Docker containers are running perfectly but Zabbix insists the service is offline, a Snap installation of Docker is likely the culprit. Snap deployments often use non-standard socket paths and default to restrictive root:root permissions, effectively locking the zabbix user out of the monitoring API.

zabbix docker snap
Open original on GitHub Gist

Troubleshooting Guide: Zabbix Agent 2 & Docker (Snap) Integration

Issue Description

Zabbix Agent 2 fails to monitor the Docker service, returning 0 (Down) during testing or triggering "Docker: Service is down" alerts. This issue frequently occurs when Docker is installed via the Snap package manager rather than standard APT repositories.

Root Cause

  1. Non-standard Socket Path & Configuration: The Zabbix agent 2 Docker plugin attempts to query the Docker API using default socket paths. Snap installations often place the socket elsewhere or create symlinks with non-standard behaviors.
  2. Permission Denied (Group Ownership): By default, the socket file (/run/docker.sock) in a Snap deployment may be owned by root:root instead of the standard root:docker. Because the Zabbix Agent runs under the unprivileged zabbix user, it lacks read/write access to this socket, resulting in failed data collection.

Resolution Steps

1. Locate the Docker Socket

Find the exact path of the Docker socket on the system:

find /run -type s -name "docker.sock" 2>/dev/null

(Assuming the output is /run/docker.sock)

2. Configure Zabbix Agent 2

Update the Zabbix Agent configuration to point to the correct Docker socket.
Open the Docker plugin configuration file:

nano /etc/zabbix/zabbix_agent2.d/plugins.d/docker.conf

Add or modify the endpoint directive (note the triple slash ///):

Plugins.Docker.Endpoint=unix:///run/docker.sock

3. Fix Socket Permissions and User Groups

Ensure the socket belongs to the docker group and the zabbix user is a member of that group.

# Change the group ownership of the socket to 'docker'
sudo chgrp docker /run/docker.sock

# Add the zabbix user to the docker group
sudo usermod -aG docker zabbix

4. Apply Changes

Restart the Zabbix Agent 2 service to apply the new configuration and group memberships:

sudo systemctl restart zabbix-agent2

Long-Term Recommendation (Important)

Warning regarding Snap: While the steps above resolve the immediate monitoring issue, Snap daemon updates or server reboots can reset the permissions of /run/docker.sock back to root:root. This will break the Zabbix monitoring again.

Permanent Fix: For a stable production environment, it is highly recommended to remove the Snap version of Docker and install the native docker-ce package from the official APT repository. The APT installation natively and persistently manages the docker group socket permissions.

Back to posts More on GitHub