DEV Community

Cover image for Install Zabbix Agent 2 on Ubuntu 24.04 and 22.04 in 10 Minutes
logiserv
logiserv

Posted on

Install Zabbix Agent 2 on Ubuntu 24.04 and 22.04 in 10 Minutes

#zabbix #ubuntu #monitoring #sysadmin

To monitor an Ubuntu server with Zabbix, you need to install an agent: a lightweight service that collects system metrics (CPU load, memory, filesystem usage, running services, logs) and sends them to the monitoring server. See the full definition of the Zabbix agent.

This guide covers the complete manual installation on Ubuntu Server 20.04 LTS, 22.04 LTS and 24.04 LTS. The procedure works with any Zabbix server.

The easy way: with Logiserv

Logiserv is built on this same Zabbix engine and automates everything. From the Agent page of the dashboard, a command is generated for your fleet:

curl -sSL "https://www.logiserv.app/api/agent-script/linux?token=..." | sudo bash
Enter fullscreen mode Exit fullscreen mode

The script detects the distribution, adds the repository, installs the package, gets a unique PSK key for the system from the server, writes the configuration, creates the host on the server side with the right templates, adjusts the permissions needed for security metrics and starts the service.

Allow 1 to 2 minutes per system with Logiserv. The detailed manual installation below takes 6 steps and about 10 minutes per server, not counting host creation on the Zabbix server side. See the detailed comparison.

Agent 1 or Agent 2?

Two packages coexist in the official repository:

  • zabbix-agent: the legacy agent written in C, configuration file zabbix_agentd.conf
  • zabbix-agent2: the current version written in Go, configuration file zabbix_agent2.conf

Agent 2 is recommended for any new installation: built-in plugins (PostgreSQL, MySQL, Docker, Redis…), a single persistent connection to the server, lower memory footprint. This guide uses Agent 2; the commands for Agent 1 are identical if you replace agent2 with agent everywhere.

Note: The package provided by the Ubuntu repositories (universe) is often much older than the current version. Use the official Zabbix repository described below to get an up-to-date version aligned with your server.

Prerequisites

  • sudo access on the system
  • the IP address or DNS name of your Zabbix server
  • outbound network access to port 10051/TCP on the server

Step 1: add the official Zabbix repository

The zabbix-release package name includes the Ubuntu version. For Ubuntu 24.04:

wget https://repo.zabbix.com/zabbix/7.4/release/ubuntu/pool/main/z/zabbix-release/zabbix-release_latest+ubuntu24.04_all.deb
sudo dpkg -i zabbix-release_latest+ubuntu24.04_all.deb
sudo apt update
Enter fullscreen mode Exit fullscreen mode

For Ubuntu 22.04, replace ubuntu24.04 with ubuntu22.04; for 20.04, with ubuntu20.04.

Automatic version, whatever the release:

. /etc/os-release
wget -qO /tmp/zabbix-release.deb \
  "https://repo.zabbix.com/zabbix/7.4/release/ubuntu/pool/main/z/zabbix-release/zabbix-release_latest+ubuntu${VERSION_ID}_all.deb"
sudo dpkg -i /tmp/zabbix-release.deb
sudo apt update
Enter fullscreen mode Exit fullscreen mode

Step 2: install the agent 

sudo apt install -y zabbix-agent2
Enter fullscreen mode Exit fullscreen mode

The package creates the zabbix system user, installs the systemd unit and places the configuration file in /etc/zabbix/.

To also install the optional plugins (PostgreSQL, MongoDB, MSSQL):

sudo apt install -y zabbix-agent2-plugin-*
Enter fullscreen mode Exit fullscreen mode

Step 3: configure the agent

Edit /etc/zabbix/zabbix_agent2.conf:

sudo nano /etc/zabbix/zabbix_agent2.conf
Enter fullscreen mode Exit fullscreen mode

The essential directives:

# Server allowed to query this agent (passive mode)
Server=192.168.1.10

# Server to which the agent pushes its metrics (active mode)
ServerActive=192.168.1.10

# Must match EXACTLY the host name defined on the Zabbix server side
Hostname=srv-web-01

LogFile=/var/log/zabbix/zabbix_agent2.log
LogFileSize=10
Enter fullscreen mode Exit fullscreen mode

The Hostname pitfall

The Hostname value must be strictly identical to the "Host name" field of the host created in the Zabbix interface. A case difference is enough for active checks to never report, with no explicit error on the server side.

To automatically use the system's name:

HostnameItem=system.hostname
Enter fullscreen mode Exit fullscreen mode

Active or passive mode

  • Passive (Server=): the server queries the agent, which must be reachable on port 10050. Problematic behind NAT.
  • Active (ServerActive=): the agent pushes its data. No inbound port to open, preferable for remote or cloud systems.

Both modes can coexist.

Tip: Don't feel like going through the next steps? The PSK key, copying it to the server, creating the host and starting the service are where mistakes happen most. With Logiserv, a single command does them all, with a unique key per system. Try it for free, no credit card.

Step 4: encrypt the connection with a PSK key

Without encryption, metrics travel in clear text. Generate a 32-byte key:

sudo mkdir -p /etc/zabbix
openssl rand -hex 32 | sudo tee /etc/zabbix/zabbix_agent2.psk > /dev/null
sudo chown zabbix:zabbix /etc/zabbix/zabbix_agent2.psk
sudo chmod 600 /etc/zabbix/zabbix_agent2.psk
Enter fullscreen mode Exit fullscreen mode

Complete the configuration:

TLSConnect=psk
TLSAccept=psk
TLSPSKIdentity=PSK-srv-web-01
TLSPSKFile=/etc/zabbix/zabbix_agent2.psk
Enter fullscreen mode Exit fullscreen mode

Copy the same key and identity into the Encryption tab of the host on the server side. Use a distinct identity per system: a compromised shared key exposes the whole fleet.

Warning: openssl rand -hex 32 appends a newline. Zabbix generally tolerates it, but in case of a SSL alert number 40 error, remove it: sudo truncate -s 64 /etc/zabbix/zabbix_agent2.psk

Step 5: open the port in the firewall

Note: With Logiserv, this step is unnecessary. The install command generated from the Agent page configures the agent in active mode only: it connects itself outbound to the Logiserv server on port 10051/TCP and listens on no port. No inbound port to open, no firewall rule to create.

Only in passive mode. With UFW:

sudo ufw allow from 192.168.1.10 to any port 10050 proto tcp
Enter fullscreen mode Exit fullscreen mode

Restricting to the Zabbix server's address avoids exposing the agent to the whole network. In active mode, no inbound rule is needed.

Step 6: start and verify 

sudo systemctl enable --now zabbix-agent2
sudo systemctl status zabbix-agent2
Enter fullscreen mode Exit fullscreen mode

Test a metric locally, without going through the server:

zabbix_agent2 -t system.cpu.load[all,avg1]
zabbix_agent2 -t vfs.fs.size[/,pfree]
zabbix_agent2 -t agent.version
Enter fullscreen mode Exit fullscreen mode

A response like system.cpu.load[all,avg1] [d|0.080000] confirms collection works.

Check the log:

sudo tail -f /var/log/zabbix/zabbix_agent2.log
Enter fullscreen mode Exit fullscreen mode

Common error messages

Message Likely cause
no active checks on server Hostname doesn't match any host on the server side
SSL alert number 40 PSK key or identity mismatch between agent and server
connection refused Service stopped, or port 10050 filtered
Permission denied on a log The zabbix user isn't in the adm group

On that last point, some security metrics require access to system logs:

sudo usermod -aG adm zabbix
sudo systemctl restart zabbix-agent2
Enter fullscreen mode Exit fullscreen mode

Monitoring multiple Ubuntu servers

Repeated on twenty systems, this procedure becomes costly: repository, package, configuration, unique PSK key, host creation on the server side, key copying. Allow ten minutes per server, with as many opportunities for drift.

The classic approaches: Ansible or an equivalent configuration tool (robust, but playbooks and a secrets vault to maintain), cloud-init at provisioning, or Zabbix auto-registration with actions and host metadata configured on the server side.

At scale

On a much larger fleet, a commenter on r/zabbix (u/fabomajstor, shared with permission) runs it end to end in about 30 seconds per server:

  • Provisioning: Red Hat Satellite deploys the host, then Ansible installs the agent, creates the zabbix user and its sudoers rules, configures the local firewall and writes the agent config.
  • Passive checks: on a closed network, the server and proxies do the polling, so scheduling and load stay central. Server= is restricted to the authorized server and proxy IPs.
  • One PSK per host: generated during provisioning and stored encrypted on the host. No recovery: if a key is in doubt, the host config is destroyed and rebuilt with a new one, so there is no key escrow to protect.
  • Registration: the Zabbix API attaches templates, host groups and inventory automatically.
  • Hardening: DenyKey=system.run[*]. If none of your templates use system.run, that line alone closes the remote command path. AllowKey is only needed for a few explicit exceptions.

Discussion on r/zabbix: https://www.reddit.com/r/zabbix/comments/1xebg9x/zabbix_agent_2_on_ubuntu_24042204_the_6_steps_and/

The same installation with Logiserv

Logiserv is built on this same Zabbix engine and automates everything. From the Agent page of the dashboard, a command is generated for your fleet:

curl -sSL "https://www.logiserv.app/api/agent-script/linux?token=..." | sudo bash
Enter fullscreen mode Exit fullscreen mode

The script detects the distribution, adds the repository, installs the package, gets a unique PSK key for the system from the server, writes the configuration, creates the host on the server side with the right templates, adjusts the permissions needed for security metrics and starts the service.

Manual installation vs. Logiserv

Manual installation (this guide) With Logiserv
Steps 6 steps, about fifteen commands 1 copy-pasted command
Time per server About 10 minutes, excluding host creation 1 to 2 minutes, everything included
Repository Package to pick according to the Ubuntu version Detected automatically
Configuration file Edited by hand Written by the script
PSK key To generate, secure, then copy to the server side Unique, generated and registered automatically
Host on the Zabbix server To create in the interface, templates to link Created automatically in the fleet's group
Firewall UFW rule in passive mode No inbound port
Zabbix server To host, secure, back up, update Hosted and maintained by Logiserv
Dashboards and alerts To build Included, ready to use
  • Recognized distributions: Ubuntu, Debian, Raspberry Pi OS, RHEL, Rocky, AlmaLinux, Amazon Linux, SLES. The distribution is detected automatically via /etc/os-release.
  • Encryption: unique PSK per system. 32-byte key generated at enrollment, never shared between two hosts.
  • Inbound port required: none. Active mode: only outbound traffic to the server is needed.
  • Log permissions: configured automatically. The zabbix user is added to the adm and shadow groups for security checks.

How the Agent page works is detailed in the Logiserv documentation.

Going further

Originally published in French on logiserv.app.

Top comments (0)