Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Getting Started

Installing and Configuring the Zabbix Agent on Linux and Windows

Install Zabbix agent 2 on Linux and Windows, edit Server, ServerActive and Hostname in zabbix_agent2.conf, open port 10050, test with zabbix_get and add the host in the frontend.

The server alone sees nothing; it needs data. The easiest source is the Zabbix agent, a small program on each monitored machine that reports CPU, memory, disk, network, process and log information. This lesson installs agent 2 (the current agent written in Go) and connects it to your server. The older agent (zabbix_agentd) uses nearly the same configuration file format and item keys, so the lesson applies to both.

Commands are read-only here because the agent does not run on this site. Python stand-ins check configuration logic.

Install on Linux

Add the Zabbix repository as shown in installing the server, then:

Terminal
sudo apt install zabbix-agent2
# RHEL family:  sudo dnf install zabbix-agent2
sudo systemctl enable --now zabbix-agent2

The configuration file is /etc/zabbix/zabbix_agent2.conf, the log is /var/log/zabbix/zabbix_agent2.log.

The three settings that matter

INI
Server=192.0.2.5
ServerActive=192.0.2.5
Hostname=web-01
  • Server: IP addresses or CIDR ranges (comma-separated) from which the agent accepts passive checks. If the server's address is not listed, the frontend shows "Received empty response" or "Connection refused" errors.
  • ServerActive: where the agent sends active data and fetches its check list. You may add a port (192.0.2.5:10051) or several servers separated by commas (HA nodes) or semicolons (separate Zabbix installations).
  • Hostname: must match the Host name field of the host in the frontend exactly (case-sensitive). Active checks fail silently if it differs. If left empty, agent 2 uses the system name unless HostnameItem is set.

Other common settings: ListenPort=10050, ListenIP, LogFile, LogFileSize, Timeout, Include=/etc/zabbix/zabbix_agent2.d/*.conf, and UserParameter lines (see common agent keys). After editing the file, restart the service:

Terminal
sudo systemctl restart zabbix-agent2

Open the firewall

Passive checks connect to the agent on TCP 10050; active checks connect from the agent to the server on TCP 10051.

Terminal
sudo ufw allow from 192.0.2.5 to any port 10050 proto tcp   # Ubuntu
sudo firewall-cmd --permanent --add-port=10050/tcp          # RHEL

Install on Windows

  1. Download the MSI installer for Zabbix agent 2 from the official site (choose the version that matches your server's major version, for example 7.0).
  2. Run it. The wizard asks for Host name, Zabbix server IP/DNS, Agent listen port (10050), Server or Proxy for active checks, and whether to add the agent to the Windows Firewall exceptions list.
  3. The service Zabbix Agent 2 starts automatically. Its configuration is C:\Program Files\Zabbix Agent 2\zabbix_agent2.conf with the same keys as Linux.

Silent install for automation (read-only example):

BAT
msiexec /i zabbix_agent2-7.0.0-windows-amd64-openssl.msi /qn ^
  SERVER=192.0.2.5 SERVERACTIVE=192.0.2.5 HOSTNAME=win-app-01

Test from the server

Install the zabbix-get package on the server and ask the agent for a value:

Terminal
zabbix_get -s 192.0.2.10 -p 10050 -k agent.ping
# 1
zabbix_get -s 192.0.2.10 -k system.hostname
zabbix_get -s 192.0.2.10 -k "vfs.fs.size[/,pfree]"

agent.ping returns 1 when the agent is up. If you see ZBX_NOTSUPPORTED, the key is unknown or invalid. If you see "Connection refused" the agent is not listening or the firewall blocks it; "Check access restrictions in Zabbix agent configuration" means the server IP is missing from Server=.

Add the host in the frontend

  1. Data collection > Hosts > Create host.
  2. Host name: web-01 (identical to Hostname=).
  3. Templates: type Linux by Zabbix agent (or Windows by Zabbix agent) and select it.
  4. Host groups: type a name such as Linux servers to create one, or choose an existing one.
  5. Interfaces > Add > Agent: IP address 192.0.2.10, port 10050.
  6. Click Add.

Within a minute or two the ZBX availability icon in the host list turns green, and Monitoring > Latest data fills with values. If the icon stays gray or turns red, hover over it to read the error.

Stand-in: validate an agent config

Python Stand-in: agent config linter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: is the agent reachable?

A real agent answers on TCP 10050. This simulation shows the decision tree you follow when the host icon is not green.

Python Stand-in: troubleshooting decision tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Encryption and security

By default the agent talks in plain text. Zabbix supports PSK (pre-shared key) and certificate encryption between server, proxy and agent. Settings: TLSConnect, TLSAccept, TLSPSKIdentity, TLSPSKFile. In the frontend you set the same under host > Encryption. Use encryption whenever agents report across untrusted networks. Also remember that Server= is an access control list: keep it narrow.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which setting lists the addresses allowed to run passive checks against the agent?

    Server= is the allow list for passive checks; ServerActive= is where active data is sent.
  2. 2. What must the agent's Hostname match?

    Active checks identify the host by this name, case-sensitive.
  3. 3. What does zabbix_get -s IP -k agent.ping return when the agent works?

    agent.ping returns 1 when the agent is available.
  4. 4. Which template would you link to a Windows server using the agent?

    The Windows by Zabbix agent template provides Windows-specific items and triggers.

Summary

  • Install agent 2 from the Zabbix repository (Linux) or the MSI (Windows).
  • Set Server, ServerActive and Hostname; restart the service; open TCP 10050.
  • Test with zabbix_get; then create the host with an agent interface and a template.
  • Green ZBX icon + values in Latest data = success.
  • Use PSK or certificates across untrusted networks.

Next: Passive and active checks