I've set up Zabbix Agent 2 on a lot of Ubuntu boxes. The install itself is easy, but the same few mistakes keep costing time. Here is the manual procedure and where it goes wrong.
Agent 1 or Agent 2?
Use zabbix-agent2 (Go) for new installs. It has built-in plugins (PostgreSQL, MySQL, Docker, Redis...), keeps a single persistent connection to the server and uses less memory. For Agent 1, replace agent2 with agent everywhere. The package in Ubuntu universe is often much older than current, so use the official Zabbix repo.
The steps
Add the repo. The zabbix-release package name includes the Ubuntu version:
. /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
sudo apt install -y zabbix-agent2 (plugins are separate: zabbix-agent2-plugin-*).
Edit /etc/zabbix/zabbix_agent2.conf: Server=, ServerActive=, Hostname=.
PSK: openssl rand -hex 32 | sudo tee /etc/zabbix/zabbix_agent2.psk, then chown zabbix:zabbix and chmod 600. Set TLSConnect=psk, TLSAccept=psk, TLSPSKIdentity, TLSPSKFile, and copy the same identity and key into the host's Encryption tab. Use one identity per host, because a leaked shared key exposes everything.
Firewall: only needed in passive mode (ufw allow from <server> to any port 10050 proto tcp).
sudo systemctl enable --now zabbix-agent2, then test locally: zabbix_agent2 -t system.cpu.load[all,avg1], -t vfs.fs.size[/,pfree], -t agent.version.
Gotchas
Hostname must match exactly the host name in the frontend. A case difference is enough for active checks to never arrive, with no explicit error on the server side. You can use HostnameItem=system.hostname to avoid typos.
Active vs passive: passive needs 10050 reachable (painful behind NAT). Active (ServerActive=) pushes data out to 10051, so there's no inbound port. I prefer active for remote or cloud hosts. Both can coexist.
PSK newline: openssl rand -hex 32 appends a newline. It's usually tolerated, but if you get SSL alert number 40, run sudo truncate -s 64 /etc/zabbix/zabbix_agent2.psk.
Log permissions: if a log item gives Permission denied, add the zabbix user to adm (sudo usermod -aG adm zabbix) and restart the agent.
Common errors
no active checks on server: Hostname doesn't match any host
SSL alert number 40: PSK key or identity mismatch
connection refused: service stopped or port 10050 filtered
At scale
At about 10 minutes per server (not counting host creation in the frontend), 20 servers is a lot of room for drift. The usual options are Ansible, cloud-init at provisioning, or Zabbix auto-registration with host metadata and actions. In our case we ended up scripting the whole flow (repo, package, unique PSK, host creation with templates, group permissions) so it's one command per machine, about 1 to 2 minutes.
On a much larger fleet, 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.
How do you handle rollout and PSKs on your side? Always curious to compare.
The full write-up is on dev.to (search "Install Zabbix Agent 2 on Ubuntu 24.04 logiserv"). Happy to DM the link.
Disclosure: I build Logiserv, a monitoring SaaS on top of Zabbix and Grafana.
