Tome of Finite Knowledge

Zabbix Agent Installation

4 min read

Goals: Install the Zabbix agent on a new machine and add it to the Zabbix server for monitoring.

Agent installation

See also

The Zabbix agent install docs: https://www.zabbix.com/download?zabbix=7.4&os_distribution=debian&os_version=13&components=agent_2&db&ws

In short (applicable for a Debian 13 install of Zabbix agent2 7.4):

$ wget https://repo.zabbix.com/zabbix/7.4/release/debian/pool/main/z/zabbix-release/zabbix-release_latest_7.4+debian13_all.deb
$ sudo apt install ./zabbix-release_latest_7.4+debian13_all.deb
$ sudo apt update
$ sudo apt install zabbix-agent2
$ sudo systemctl enable zabbix-agent2

Agent configuration

Edit /etc/zabbix/zabbix_agent2.conf and change settings as necessary. My typical edits are:

  • Server= - set the IP address that the Zabbix server will be querying this device from

    NAT thwarting

    If you’re monitoring a remote host over a VPN or the open internet from a server behind NAT, you may also need to list out the NAT address here!

    For example, on my AWS server, I needed to set 192.168.37.100 (which is the address my router comes up as on the VPN client) instead of 192.168.30.142, the LAN address of the Zabbix server.

  • ListenPort= - set to 10050
    • ListenIP= - if you want to restrict listening to only certain interfaces
    • Make sure this port is firewalled open (UFW)
  • ServerActive= - IP/port for active agent reports. Looks like 192.168.30.142:10051.
  • Hostname= - I usually set the hostname here in case Zabbix doesn’t pick it up right from the OS. It needs to match whatever you set the hostname as in the Zabbix server (but does not necessarily have to match the actual OS’s hostname).

After editing, be sure to reload the service with sudo systemctl restart zabbix-agent2.

Monitoring Docker - client changes

If you have a Docker service running on the host, you may wish to monitor it via Zabbix as well. I’ve found that often, this just works out of the box when installing Zabbix from apt.

But, not always. I encountered two Debian 13 hosts which, when Zabbix agent was configured, mistakenly told me that Docker: Service is down! even though it was alive and well.

Ultimately, the problem was that the Zabbix agent user did not have permission to snoop on /var/run/docker.sock and therefore couldn’t check the state of the docker service. The fix for this was quite simple:

$ sudo usermod -a -G docker zabbix
$ sudo systemctl restart zabbix-agent2  # not sure if this is actually necessary

You can preemptively test whether this is a problem in one of two ways:

On the host being monitored, check whether user zabbix is a member of group docker:

$ groups zabbix
zabbix : zabbix         # bad output!
zabbix : zabbix docker  # good output!

or, on the host running the Zabbix server:

zabbix_get -s <client IP> -k docker.info

If Zabbix is unable to read the Docker socket, you’ll get

ZBX_NOTSUPPORTED: Failed to do request: Get "http://1.28/info": dial unix /var/run/docker.sock: connect: permission denied.

Otherwise, if it’s working properly, you’ll get a big chunk of JSON which I’m not bothering to paste here.

Missing zabbix_get

If you don’t have zabbix_get, install it with sudo apt install zabbix_get.

Server-side setup

If you don’t have host autoregistration enabled, you’ll have to create the host in the Zabbix server, configure its monitoring interfaces, and assign any necessary templates.

  1. Log in to the Zabbix dashboard
  2. Go to Monitoring ⇒ Hosts and select Create host
  3. Enter the hostname (if you set Hostname= in the agent’s config, it must match that value)
  4. Add applicable host groups
  5. Add any applicable templates
  6. Add monitoring interfaces as required
    1. My typical interface, with the agent setup described above, is type Agent, IP address of the machine, hostname of the machine, connect via IP to port 10050.

No data showing up?

If everything looks right, but there’s no data available for review, make sure you added templates. Even with active agent reporting, no data is shown without any templates!

Monitoring Docker - server changes

Monitoring Docker services simply requires you to add the Docker by Zabbix agent 2 template to the relevant host. That’s it!

Graph View