Zabbix Agent 2: Installation, Configuration, and Plugins

Q: Do I need to restart the service after every change to zabbix_agent2.conf?

Yes, after every modification to the zabbix_agent2.conf configuration file (or files included in the zabbix_agent2.d/ directory), it is mandatory to restart the zabbix-agent2 service to apply the new settings. The service does not automatically reload the configuration, so a restart is the only way to make them effective.

Zabbix Agent 2 is the latest evolution of the Zabbix monitoring client, designed to offer greater efficiency and extended functionality compared to its classic counterpart. Correct installation and configuration of this component are crucial for ensuring reliable and granular monitoring of your hosts, from web servers to databases and Docker containers.

Zabbix Agent 2 in 60 seconds

For those in a hurry, here are the essential steps to install and configure Zabbix Agent 2 on a Debian/Ubuntu-based system:

# 1. Download the repository package (e.g., for Ubuntu 22.04)
wget https://repo.zabbix.com/zabbix/6.4/ubuntu/pool/main/z/zabbix-release/zabbix-release_6.4-1+ubuntu22.04_all.deb
sudo dpkg -i zabbix-release_6.4-1+ubuntu22.04_all.deb
sudo apt update

# 2. Install Zabbix Agent 2 and plugins
sudo apt install zabbix-agent2 zabbix-agent2-plugin-*

# 3. Edit the configuration file
sudo nano /etc/zabbix/zabbix_agent2.conf
# Set Server, ServerActive, and Hostname with your Zabbix Server's IP and the host's name

# 4. Enable and start the service
sudo systemctl enable --now zabbix-agent2

# 5. Open port 10050 on the firewall (if using UFW)
sudo ufw allow from 10.0.0.10 to any port 10050 proto tcp # Replace 10.0.0.10 with your Zabbix Server's IP

# 6. Verify operation from the Zabbix Server
zabbix_get -s web01 -k agent.ping # Replace web01 with the agent's Hostname

Proactive monitoring is a cornerstone of IT management, essential for preventing service disruptions and optimizing performance. In complex environments, where every millisecond counts, efficient tools like Zabbix Agent 2 make a significant difference. This agent, rewritten in Go, not only offers superior performance but also integrates a flexible plugin system that extends its capabilities far beyond basic monitoring. From managing system metrics to detailed database insights like PostgreSQL or MySQL, and observing Docker containers, Zabbix Agent 2 is designed to simplify data collection. This article will guide you through the installation, configuration, and use of plugins, providing a solid foundation for effective system monitoring.

Reference versions: Zabbix Agent 2 (version 6.4) · documentation consulted October 2026

Prerequisites

Before starting the Zabbix Agent 2 installation, ensure you have the following prerequisites:

A Linux operating system (these examples are based on Debian/Ubuntu, but the concepts are similar for CentOS/RHEL).
sudo or root privileges on the host to be monitored.
A functional Zabbix Server accessible from the host’s network.
The Zabbix Server’s IP address (needed for configuration).
Basic knowledge of Linux terminal operations.

Agent 2 vs. classic agent: what’s new

The choice between the classic Zabbix Agent and Zabbix Agent 2 is not just a matter of version, but of architecture and functionality. The classic Agent, written in C, is robust and proven, ideal for basic system resource monitoring. However, extending its capabilities often requires external scripts or additional modules.

Zabbix Agent 2, on the other hand, has been completely rewritten in Go. This redesign brings several significant advantages:

Plugin-based architecture: Agent 2 supports a native plugin system that allows easy extension of monitoring capabilities for specific services like Docker, PostgreSQL, MySQL, and more, without the need for complex external scripts. These plugins are written directly in Go and benefit from the agent’s architecture.
Efficiency: Being written in Go, Agent 2 is generally more efficient in terms of resource consumption (CPU and memory) and faster in data collection, especially when managing many monitoring items simultaneously.
Robust active checks: Agent 2 is particularly optimized for active checks (Zabbix Server asks the agent to send data). This mode reduces the load on the Zabbix server and allows the agent to collect data more autonomously.
Fewer dependencies: Agent 2 has fewer external dependencies compared to the classic version, simplifying installation and reducing potential conflicts. Read also: Docker Disk Space: Prune, Logs, and Unused Images

In summary, if you need to monitor specific applications (databases, containers) with greater efficiency and flexibility, Agent 2 is the recommended choice for new deployments. For hosts with minimal requirements or where the classic Agent is already in use and working well, an immediate upgrade is not mandatory, but consider the long-term benefits.

Install from the official repository

To ensure stability and receive security updates, it is always advisable to install Zabbix Agent 2 from the official Zabbix repositories. This method ensures you are using tested packages compatible with your Linux distribution.

1. Add the Zabbix repository:

For Debian/Ubuntu-based systems, the first step is to add the Zabbix repository. This varies slightly depending on the operating system version. For Ubuntu 22.04 (Jammy Jellyfish) and Zabbix 6.4, the commands are as follows:

wget https://repo.zabbix.com/zabbix/6.4/ubuntu/pool/main/z/zabbix-release/zabbix-release_6.4-1+ubuntu22.04_all.deb
sudo dpkg -i zabbix-release_6.4-1+ubuntu22.04_all.deb
sudo apt update

Be sure to check the official Zabbix download page (https://www.zabbix.com/download_agents) to get the correct zabbix-release package URL for your specific distribution and Zabbix version.

2. Install Zabbix Agent 2 and plugins:

Once the repository is added, you can proceed with installing the agent and its plugins. It is good practice to install the zabbix-agent2-plugin-* package to have all available plugins from the start, even if you won’t use them immediately. This avoids having to install them later.

sudo apt install zabbix-agent2 zabbix-agent2-plugin-*

This command will install the agent and all available official plugins. Once the installation is complete, the zabbix-agent2 service will likely already be started, but it will need to be configured.

Configure Server, ServerActive, and Hostname

Zabbix Agent 2 configuration is done via the zabbix_agent2.conf file. This file is typically located in /etc/zabbix/. The three most important directives to configure are Server, ServerActive, and Hostname.

Open the configuration file with a text editor:

sudo nano /etc/zabbix/zabbix_agent2.conf

Find and modify the following lines (they might be commented out with a #):

Server: This directive specifies the IP address or DNS name of the Zabbix Server or proxy from which the agent will accept connections for passive checks. If you have multiple Zabbix servers or proxies, you can specify them separated by commas.

    Server=10.0.0.10

Replace 10.0.0.10 with the actual IP of your Zabbix Server.

ServerActive: This directive is crucial for active checks. It specifies the IP address or DNS name of the Zabbix Server or proxy to which the agent will connect to retrieve active monitoring items and send data. Here too, you can specify multiple servers/proxies. The default port for ServerActive is 10051.

    ServerActive=10.0.0.10

Again, 10.0.0.10 must be the IP of your Zabbix Server.

Hostname: This is the unique name of the host that will be displayed in the Zabbix web interface. It is essential that this Hostname exactly matches the host name configured in the Zabbix Server for the host in question. If they do not match, monitoring will not work.

    Hostname=web01

Replace web01 with a descriptive and unique name for your host. Read also: UFW Firewall Ubuntu: Complete Configuration from A to Z (2026)

After saving the changes to the zabbix_agent2.conf file, restart the Zabbix Agent 2 service to apply them:

sudo systemctl restart zabbix-agent2

To ensure the service starts automatically at system boot, enable it:

sudo systemctl enable --now zabbix-agent2

Active and passive checks

Zabbix Agent 2 supports two main data collection modes:

Passive checks: The Zabbix Server (or proxy) queries the agent to obtain a specific value (e.g., agent.ping). The agent listens on TCP port 10050 and responds to requests. This mode is useful for ad-hoc checks or for items that do not require frequent collection.
Active checks: The agent periodically connects to the Zabbix Server (or proxy) on TCP port 10051, requests a list of active monitoring items configured for that host, and sends the collected data. This mode is more efficient for a large number of items and for monitoring frequently changing data, as the agent autonomously manages the collection schedule. It is the preferred mode for most modern templates.

The Server directive manages passive checks, while ServerActive manages active checks. It is good practice to configure both for maximum flexibility and robustness of monitoring.

Firewall and port 10050

A common error that prevents Zabbix Agent 2 from functioning correctly is incorrect firewall configuration. The agent communicates with the Zabbix Server (and vice versa) on specific ports:

Port 10050/TCP: Used for passive checks. The Zabbix Server connects to this port on the agent.
Port 10051/TCP: Used for active checks. The agent connects to this port on the Zabbix Server.

It is essential to configure the firewall on the host where Zabbix Agent 2 is installed to allow incoming connections on port 10050 from the Zabbix Server. If you use ufw (Uncomplicated Firewall) on Ubuntu, the command is:

sudo ufw allow from 10.0.0.10 to any port 10050 proto tcp

Replace 10.0.0.10 with the IP address of your Zabbix Server. If you do not specify from, the port will be open to any IP, which is less secure. Read also: Passwordless SSH Linux: Configure Keys in 5 Minutes (2026)

If you use a different firewall (e.g., firewalld on CentOS/RHEL or iptables), you will need to adapt the command accordingly. Always check the firewall status after changes to ensure the rule has been applied correctly.

Plugins: PostgreSQL, MySQL, Docker

One of the greatest strengths of Zabbix Agent 2 is its integrated plugin system, which extends monitoring capabilities for specific services. If you have installed the zabbix-agent2-plugin-* package, you already have many of these plugins available.

To enable and configure a plugin, it is often necessary to modify the zabbix_agent2.conf file and add Plugins and PluginConf directives.

Example: PostgreSQL Plugin

To monitor a PostgreSQL database, you need to configure the PostgreSQL plugin and provide access credentials. An example configuration might be:

# zabbix_agent2.conf
...
Plugins.PostgreSQL.Sessions.Max=10
Plugins.PostgreSQL.Timeout=3

# Example configuration for a PostgreSQL instance
# The specific plugin configuration file can be created in /etc/zabbix/zabbix_agent2.d/
# Example: /etc/zabbix/zabbix_agent2.d/postgresql.conf

# Database connection (user, password, host, port, dbname)
# Ensure the Zabbix user has the necessary read permissions
PluginConf.PostgreSQL.User=zabbix_monitor
PluginConf.PostgreSQL.Password=very_secret_password
PluginConf.PostgreSQL.ConnString=host=localhost port=5432 dbname=postgres

After modifying the configuration file (or creating a .conf file in zabbix_agent2.d/), restart the agent. Then, in the Zabbix web interface, link the host to a template such as PostgreSQL by Zabbix agent 2.

Example: Docker Plugin

For Docker, the plugin allows monitoring containers, images, volumes, and performance. It often does not require additional configuration in zabbix_agent2.conf if Docker is installed and the zabbix user has permissions to access the Docker socket (by adding the zabbix user to the docker group).

sudo usermod -aG docker zabbix
sudo systemctl restart zabbix-agent2

Then, link the host to the Docker by Zabbix agent 2 template in the Zabbix web interface.

Example: MySQL Plugin

Similar to PostgreSQL, the MySQL plugin requires credentials to access the database. You can configure them in zabbix_agent2.conf or in a separate file in zabbix_agent2.d/:

# /etc/zabbix/zabbix_agent2.d/mysql.conf
PluginConf.MySQL.User=zabbix_mysql_monitor
PluginConf.MySQL.Password=secure_mysql_pass
PluginConf.MySQL.DefaultDb=mysql

Restart the agent and link the MySQL by Zabbix agent 2 template.

It is essential to consult the official Zabbix documentation for each specific plugin, as configuration parameters and requirements may vary slightly.

Link the host to the template in Zabbix

Once Zabbix Agent 2 is installed and configured on the host, the next step is to link the host to the Zabbix Server and assign appropriate monitoring templates.

Add the host: Access the Zabbix web interface. Go to Configuration > Hosts and click on Create host.
Configure host details:

Host name: Enter the exact Hostname you configured in the zabbix_agent2.conf file (e.g., web01).
Visible name: A more descriptive name for the interface.
Groups: Assign the host to one or more groups (e.g., Linux servers, Web servers).
Interfaces: Click on Add next to Agent interfaces. Select Agent as the type, enter the host’s IP address, and leave the port 10050 (default).

Link templates: Go to the Templates tab. Click Select and search for the templates you want to apply. For a Linux server with Agent 2, a good starting point is Linux by Zabbix agent and Zabbix agent 2. If you are monitoring specific services, also add the relevant templates (e.g., PostgreSQL by Zabbix agent 2, Docker by Zabbix agent 2).
Add the host: Click Add to save the changes.

After a few minutes, the Zabbix Server will start querying the agent and collecting data. You can check the monitoring status in the Monitoring > Latest data section.

Verify with zabbix_get

The zabbix_get command is an essential diagnostic tool to verify that Zabbix Agent 2 is responding correctly and collecting the desired data. zabbix_get is executed from the Zabbix Server or from a host with zabbix-frontend-php installed.

The basic syntax is:

zabbix_get -s <AGENT_IP_OR_HOSTNAME> -k <MONITORING_ITEM_KEY>

-s: Specifies the IP address or Hostname of the agent to query.
-k: Specifies the monitoring item key to retrieve.

To test basic connectivity and agent response:

zabbix_get -s web01 -k agent.ping

A typical output:

The value 1 indicates that the agent is active and responding. If you receive nothing or an error, check the firewall configuration, ensure the agent is running, and that Server is correctly configured in zabbix_agent2.conf.

To test a more specific item, for example, CPU load:

zabbix_agent2 -t system.cpu.load[all,avg1]

A typical output:

0.15

This command directly queries Agent 2 locally and returns the average CPU load value over the last minute. It is useful for verifying if a specific plugin or item is working correctly before configuring it in Zabbix Server.

Common Errors and Troubleshooting

Error or exact message	Cause	Solution
`ZBX_TCP_READ_ERROR: [Closed by remote host]`	The firewall blocks the connection between Zabbix Server and Agent.	Ensure port 10050/TCP is open on the agent host for the Zabbix Server’s IP. Check `ufw status` or `firewall-cmd --list-all`.
`ZBX_NOTSUPPORTED`	The monitoring item is not supported by the agent or plugin.	Verify that the required plugin is installed (`zabbix-agent2-plugin-*`) and configured correctly. Check the key syntax in the Zabbix interface.
No data in Zabbix interface, but `agent.ping` works	`Hostname` in `zabbix_agent2.conf` does not match the host name in Zabbix Server.	Ensure that `Hostname` in the agent’s configuration file is identical to that configured in the Zabbix web interface. Restart the agent.
`Get value from agent failed: ZBX_TCP_READ_ERROR: [Timeout was reached]`	The agent does not respond in time or is overloaded.	Check the host’s load and the status of the `zabbix-agent2` service. Increase `Timeout` in `zabbix_agent2.conf` if the host is slow.
`Active checks are not enabled.` in agent log	`ServerActive` not configured or unreachable.	Ensure `ServerActive` is correctly set with the Zabbix Server’s IP and that port 10051/TCP is open on the Zabbix Server.

Frequently Asked Questions

Can I use Zabbix Agent 2 and the classic agent on the same host?

Technically yes, but it is strongly discouraged. Having two agents attempting to collect data from the same host can lead to conflicts, excessive resource consumption, and duplicate or erroneous data. It is always preferable to choose one of the two versions and stick to it for a given host, fully leveraging Agent 2’s capabilities, including its plugins.

What is the main difference between active and passive checks?

In passive checks, the Zabbix Server actively requests data from the agent. The agent listens and responds. In active checks, the agent itself connects to the server, asks what data it needs to collect, and sends it. Active checks are generally more efficient in environments with many items or with agents behind NAT/firewalls, as the agent initiates the connection.

Do I need to restart the service after every change to zabbix_agent2.conf?

Yes, after every modification to the zabbix_agent2.conf configuration file (or files included in the zabbix_agent2.d/ directory), it is mandatory to restart the zabbix-agent2 service to apply the new settings. The service does not automatically reload the configuration, so a restart is the only way to make them effective.

How can I monitor logs with Zabbix Agent 2?

Zabbix Agent 2 supports log file monitoring using keys like log[] or logrt[]. These keys allow you to search for specific patterns in logs and send only the relevant lines to the Zabbix Server. This is an effective way to detect errors or critical events in real-time without having to manually analyze large log files. Read also: logrotate: Configure Log Rotation on Linux

Is it possible to upgrade a classic Zabbix Agent to Zabbix Agent 2?

Yes, it is possible, but it is not a simple “upgrade” in the traditional sense. It requires uninstalling the classic agent and installing Zabbix Agent 2, following the steps described in this article. It is advisable to plan the operation, test it in a staging environment, and ensure that the templates associated with the host are compatible with Agent 2 to avoid monitoring interruptions.

Conclusions with Operational Takeaways

Zabbix Agent 2 represents a significant step forward in host monitoring, offering greater efficiency and unprecedented flexibility thanks to its plugin-based architecture. Adopting this version allows you to consolidate the monitoring of operating systems, databases, and Docker containers with a single agent, reducing complexity and improving data collection.

The main operational takeaways are:

Prioritize Agent 2 for new deployments: For its performance and wide range of native plugins, it is the best choice for monitoring modern environments.
Full plugin installation: Don’t limit yourself to the base agent; always install zabbix-agent2-plugin-* to have all functionalities at hand.
Critical Hostname configuration: Ensure the Hostname in zabbix_agent2.conf exactly matches the one configured in the Zabbix Server to avoid communication issues.
Firewall is non-negotiable: Port 10050/TCP must be open on the host’s firewall to allow passive checks from the Zabbix Server.
Leverage zabbix_get: This tool is your best friend for troubleshooting and quickly verifying the agent’s and its items’ operation.

By correctly implementing Zabbix Agent 2, you will gain deeper and more responsive visibility into the health and performance of your systems, allowing you to intervene proactively and maintain operational stability.

Sources

Updated: October 2026