Zabbix Agent 2: Instalación, Configuración y Plugins

Q: ¿Es posible actualizar un Zabbix Agent clásico a Zabbix Agent 2?

Sí, es posible, pero no es una simple "actualización" en el sentido tradicional. Requiere la desinstalación del agent clásico y la instalación de Zabbix Agent 2, siguiendo los pasos descritos en este artículo. Es aconsejable planificar la operación, probarla en un entorno de staging y asegurarse de que las plantillas asociadas al host sean compatibles con el Agent 2 para evitar interrupciones en el monitoreo.

Zabbix Agent 2 es la última evolución del cliente de monitoreo de Zabbix, diseñado para ofrecer mayor eficiencia y funcionalidades extendidas en comparación con su contraparte clásica. La instalación y configuración correctas de este componente son fundamentales para garantizar un monitoreo fiable y granular de tus hosts, desde servidores web hasta bases de datos y contenedores Docker.

Zabbix Agent 2 en 60 segundos

Para quienes tienen prisa, aquí están los pasos esenciales para instalar y configurar Zabbix Agent 2 en un sistema basado en Debian/Ubuntu:

# 1. Descarga el paquete del repositorio (ej. para 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. Instala Zabbix Agent 2 y los plugins
sudo apt install zabbix-agent2 zabbix-agent2-plugin-*

# 3. Modifica el archivo de configuración
sudo nano /etc/zabbix/zabbix_agent2.conf
# Configura Server, ServerActive y Hostname con la IP de tu Zabbix Server y el nombre del host

# 4. Habilita e inicia el servicio
sudo systemctl enable --now zabbix-agent2

# 5. Abre el puerto 10050 en el firewall (si usas UFW)
sudo ufw allow from 10.0.0.10 to any port 10050 proto tcp # Reemplaza 10.0.0.10 con la IP de tu Zabbix Server

# 6. Verifica el funcionamiento desde el Zabbix Server
zabbix_get -s web01 -k agent.ping # Reemplaza web01 con el Hostname del agent

El monitoreo proactivo es una piedra angular de la gestión de TI, esencial para prevenir interrupciones del servicio y optimizar el rendimiento. En entornos complejos, donde cada milisegundo cuenta, disponer de herramientas eficientes como Zabbix Agent 2 marca la diferencia. Este agent, reescrito en Go, no solo ofrece un rendimiento superior, sino que también integra un sistema de plugins flexible que extiende sus capacidades mucho más allá del monitoreo básico. Desde la gestión de métricas del sistema hasta los detalles de bases de datos como PostgreSQL o MySQL, pasando por la observación de contenedores Docker, Zabbix Agent 2 está diseñado para simplificar la recopilación de datos. Este artículo te guiará a través de la instalación, configuración y uso de los plugins, proporcionando una base sólida para un monitoreo eficaz de tus sistemas.

Versiones de referencia: Zabbix Agent 2 (versión 6.4) · documentación consultada en octubre de 2026

Requisitos Previos

Antes de iniciar la instalación de Zabbix Agent 2, asegúrate de tener los siguientes requisitos previos:

Un sistema operativo Linux (estos ejemplos se basan en Debian/Ubuntu, pero los conceptos son similares para CentOS/RHEL).
Acceso con privilegios de sudo o root en el host a monitorear.
Un Zabbix Server funcionando y accesible desde la red del host.
La dirección IP del Zabbix Server (será necesaria para la configuración).
Conocimiento básico de las operaciones de terminal Linux.

Agent 2 o agent clásico: qué cambia

La elección entre Zabbix Agent clásico y Zabbix Agent 2 no es solo una cuestión de versión, sino de arquitectura y funcionalidad. El Agent clásico, escrito en C, es robusto y probado, ideal para el monitoreo básico de los recursos del sistema. Sin embargo, para extender sus capacidades, a menudo requiere scripts externos o módulos adicionales.

Zabbix Agent 2, en cambio, ha sido completamente reescrito en Go. Este rediseño aporta varias ventajas significativas:

Arquitectura basada en plugins: El Agent 2 soporta un sistema de plugins nativo que permite extender fácilmente las capacidades de monitoreo para servicios específicos como Docker, PostgreSQL, MySQL y más, sin la necesidad de scripts externos complejos. Estos plugins están escritos directamente en Go y se benefician de la arquitectura del agent.
Eficiencia: Al estar escrito en Go, el Agent 2 es generalmente más eficiente en términos de consumo de recursos (CPU y memoria) y más rápido en la recopilación de datos, especialmente cuando se gestionan muchos ítems de monitoreo simultáneamente.
Controles activos robustos: El Agent 2 está particularmente optimizado para los controles activos (Zabbix Server pide al agent que envíe los datos). Esta modalidad reduce la carga en el Zabbix Server y permite al agent recopilar datos de forma más autónoma.
Menos dependencias: El Agent 2 tiene menos dependencias externas que la versión clásica, lo que simplifica la instalación y reduce posibles conflictos. Lee también: Docker Espacio Disco: Prune, Logs y Imágenes

En resumen, si necesitas monitorear aplicaciones específicas (bases de datos, contenedores) con mayor eficiencia y flexibilidad, el Agent 2 es la opción recomendada para los nuevos despliegues. Para hosts con requisitos mínimos o donde el Agent clásico ya está en uso y funciona bien, no es obligatorio un upgrade inmediato, pero evalúa los beneficios a largo plazo.

Instalar desde el repositorio oficial

Para garantizar estabilidad y recibir las actualizaciones de seguridad, siempre es aconsejable instalar Zabbix Agent 2 desde los repositorios oficiales de Zabbix. Este método asegura que estás utilizando paquetes probados y compatibles con tu distribución Linux.

1. Añadir el repositorio Zabbix:

Para los sistemas basados en Debian/Ubuntu, el primer paso es añadir el repositorio Zabbix. Esto varía ligeramente según la versión del sistema operativo. Para Ubuntu 22.04 (Jammy Jellyfish) y Zabbix 6.4, los comandos son los siguientes:

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

Asegúrate de consultar la página oficial de descarga de Zabbix (https://www.zabbix.com/download_agents) para obtener la URL correcta del paquete zabbix-release para tu distribución específica y versión de Zabbix.

2. Instalar Zabbix Agent 2 y los plugins:

Una vez añadido el repositorio, puedes proceder con la instalación del agent y sus plugins. Es buena práctica instalar el paquete zabbix-agent2-plugin-* para tener todos los plugins disponibles desde el principio, incluso si no los usarás inmediatamente. Esto evita tener que instalarlos más tarde.

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

Este comando instalará el agent y todos los plugins oficiales disponibles. Una vez completada la instalación, el servicio zabbix-agent2 probablemente ya estará iniciado, pero será necesario configurarlo.

Configurar Server, ServerActive y Hostname

La configuración de Zabbix Agent 2 se realiza a través del archivo zabbix_agent2.conf. Este archivo se encuentra típicamente en /etc/zabbix/. Las tres directivas más importantes a configurar son Server, ServerActive y Hostname.

Abre el archivo de configuración con un editor de texto:

sudo nano /etc/zabbix/zabbix_agent2.conf

Busca y modifica las siguientes líneas (podrían estar comentadas con un #): Lee también: UFW Firewall Ubuntu: Configuración Completa Paso a Paso

Server: Esta directiva especifica la dirección IP o el nombre DNS del Zabbix Server o proxy desde donde el agent aceptará conexiones para los controles pasivos. Si tienes varios Zabbix Servers o proxies, puedes especificarlos separados por comas.

    Server=10.0.0.10

Reemplaza 10.0.0.10 con la IP efectiva de tu Zabbix Server.

ServerActive: Esta directiva es crucial para los controles activos. Especifica la dirección IP o el nombre DNS del Zabbix Server o proxy al que el agent se conectará para recuperar los ítems de monitoreo activos y enviar los datos. También aquí, puedes especificar varios servers/proxies. El puerto por defecto para ServerActive es 10051.

    ServerActive=10.0.0.10

De nuevo, 10.0.0.10 debe ser la IP de tu Zabbix Server.

Hostname: Este es el nombre único del host que se mostrará en la interfaz web de Zabbix. Es fundamental que este Hostname coincida exactamente con el nombre de host configurado en el Zabbix Server para el host en cuestión. Si no coinciden, el monitoreo no funcionará.

    Hostname=web01

Reemplaza web01 con un nombre descriptivo y único para tu host.

Después de guardar los cambios en el archivo zabbix_agent2.conf, reinicia el servicio Zabbix Agent 2 para aplicarlos:

sudo systemctl restart zabbix-agent2

Para asegurarte de que el servicio se inicie automáticamente al arrancar el sistema, habilítalo:

sudo systemctl enable --now zabbix-agent2

Controles activos y pasivos

Zabbix Agent 2 soporta dos modos principales de recopilación de datos:

Controles pasivos: El Zabbix Server (o proxy) interroga al agent para obtener un valor específico (ej. agent.ping). El agent escucha en el puerto TCP 10050 y responde a las solicitudes. Este modo es útil para controles ad-hoc o para ítems que no requieren una recopilación frecuente.
Controles activos: El agent se conecta periódicamente al Zabbix Server (o proxy) en el puerto TCP 10051, solicita una lista de ítems de monitoreo activos configurados para ese host y envía los datos recopilados. Este modo es más eficiente para un gran número de ítems y para el monitoreo de datos que cambian frecuentemente, ya que el agent gestiona autónomamente la planificación de la recopilación. Es el modo preferido para la mayoría de las plantillas modernas.

La directiva Server gestiona los controles pasivos, mientras que ServerActive gestiona los controles activos. Es buena práctica configurar ambas para la máxima flexibilidad y robustez del monitoreo.

Firewall y puerto 10050

Un error común que impide el correcto funcionamiento de Zabbix Agent 2 es la falta de configuración del firewall. El agent se comunica con el Zabbix Server (y viceversa) en puertos específicos:

Puerto 10050/TCP: Utilizado para los controles pasivos. El Zabbix Server se conecta a este puerto en el agent.
Puerto 10051/TCP: Utilizado para los controles activos. El agent se conecta a este puerto en el Zabbix Server.

Es esencial configurar el firewall en el host donde está instalado Zabbix Agent 2 para permitir las conexiones entrantes en el puerto 10050 desde el Zabbix Server. Si usas ufw (Uncomplicated Firewall) en Ubuntu, el comando es:

sudo ufw allow from 10.0.0.10 to any port 10050 proto tcp

Reemplaza 10.0.0.10 con la dirección IP de tu Zabbix Server. Si no especificas from, el puerto estará abierto a cualquier IP, lo que es menos seguro. Lee también: SSH Linux sin Password: Configura Claves en 5 Minutos

Si utilizas un firewall diferente (ej. firewalld en CentOS/RHEL o iptables), deberás adaptar el comando en consecuencia. Verifica siempre el estado del firewall después de las modificaciones para asegurarte de que la regla se haya aplicado correctamente.

Plugins: PostgreSQL, MySQL, Docker

Uno de los mayores puntos fuertes de Zabbix Agent 2 es su sistema de plugins integrado, que extiende las capacidades de monitoreo para servicios específicos. Si has instalado el paquete zabbix-agent2-plugin-*, ya tienes a tu disposición muchos de estos plugins.

Para habilitar y configurar un plugin, a menudo es necesario modificar el archivo zabbix_agent2.conf y añadir las directivas Plugins y PluginConf.

Ejemplo: Plugin PostgreSQL

Para monitorear una base de datos PostgreSQL, debes configurar el plugin PostgreSQL y proporcionar las credenciales de acceso. Un ejemplo de configuración podría ser:

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

# Ejemplo de configuración para una instancia PostgreSQL
# El archivo de configuración específico del plugin puede crearse en /etc/zabbix/zabbix_agent2.d/
# Ejemplo: /etc/zabbix/zabbix_agent2.d/postgresql.conf

# Conexión a la base de datos (usuario, contraseña, host, puerto, dbname)
# Asegúrate de que el usuario Zabbix tenga los permisos de lectura necesarios
PluginConf.PostgreSQL.User=zabbix_monitor
PluginConf.PostgreSQL.Password=very_secret_password
PluginConf.PostgreSQL.ConnString=host=localhost port=5432 dbname=postgres

Después de modificar el archivo de configuración (o crear un archivo .conf en zabbix_agent2.d/), reinicia el agent. Luego, en la interfaz web de Zabbix, vincula el host a una plantilla como PostgreSQL by Zabbix agent 2.

Ejemplo: Plugin Docker

Para Docker, el plugin permite monitorear contenedores, imágenes, volúmenes y rendimiento. A menudo no requiere configuración adicional en el zabbix_agent2.conf si Docker está instalado y el usuario zabbix tiene los permisos para acceder al socket Docker (añadiendo el usuario zabbix al grupo docker).

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

Luego, vincula el host a la plantilla Docker by Zabbix agent 2 en la interfaz web de Zabbix.

Ejemplo: Plugin MySQL

De manera similar a PostgreSQL, el plugin MySQL requiere credenciales para acceder a la base de datos. Puedes configurarlas en zabbix_agent2.conf o en un archivo separado en 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

Reinicia el agent y vincula la plantilla MySQL by Zabbix agent 2.

Es fundamental consultar la documentación oficial de Zabbix para cada plugin específico, ya que los parámetros de configuración y los requisitos pueden variar ligeramente.

Vincular el host a la plantilla en Zabbix

Una vez que Zabbix Agent 2 está instalado y configurado en el host, el siguiente paso es vincular el host al Zabbix Server y asignarle las plantillas de monitoreo apropiadas.

Añade el host: Accede a la interfaz web de Zabbix. Ve a Configuration > Hosts y haz clic en Create host.
Configura los detalles del host:

Host name: Introduce el Hostname exacto que configuraste en el archivo zabbix_agent2.conf (ej. web01).
Visible name: Un nombre más descriptivo para la interfaz.
Groups: Asigna el host a uno o más grupos (ej. Linux servers, Web servers).
Interfaces: Haz clic en Add junto a Agent interfaces. Selecciona Agent como tipo, introduce la dirección IP del host y deja el puerto 10050 (por defecto).

Vincula las plantillas: Ve a la pestaña Templates. Haz clic en Select y busca las plantillas que deseas aplicar. Para un servidor Linux con Agent 2, un buen punto de partida es Linux by Zabbix agent y Zabbix agent 2. Si estás monitoreando servicios específicos, añade también las plantillas pertinentes (ej. PostgreSQL by Zabbix agent 2, Docker by Zabbix agent 2).
Añade el host: Haz clic en Add para guardar los cambios.

Después de unos minutos, Zabbix Server comenzará a interrogar al agent y a recopilar los datos. Puedes verificar el estado del monitoreo en la sección Monitoring > Latest data.

Verificar con zabbix_get

El comando zabbix_get es una herramienta de diagnóstico esencial para verificar que Zabbix Agent 2 está respondiendo correctamente y que está recopilando los datos deseados. zabbix_get se ejecuta desde el Zabbix Server o desde un host con los zabbix-frontend-php instalados.

La sintaxis básica es:

zabbix_get -s <IP_O_HOSTNAME_AGENT> -k <KEY_ITEM_MONITORING>

-s: Especifica la dirección IP o el Hostname del agent a interrogar.
-k: Especifica la clave del ítem de monitoreo a recuperar.

Para probar la conectividad básica y la respuesta del agent:

zabbix_get -s web01 -k agent.ping

Una salida típica:

El valor 1 indica que el agent está activo y responde. Si no recibes nada o un error, verifica la configuración del firewall, que el agent esté en ejecución y que Server esté configurado correctamente en el zabbix_agent2.conf.

Para probar un ítem más específico, por ejemplo, la carga de la CPU:

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

Una salida típica:

0.15

Este comando interroga directamente al agent 2 localmente y devuelve el valor de la carga media de la CPU en el último minuto. Es útil para verificar si un plugin o un ítem específico funciona correctamente antes de configurarlo en Zabbix Server.

Errores Comunes y Resolución de Problemas

Error o mensaje exacto	Causa	Solución
`ZBX_TCP_READ_ERROR: [Closed by remote host]`	El firewall bloquea la conexión entre Zabbix Server y Agent.	Asegúrate de que el puerto 10050/TCP esté abierto en el host del agent para la IP del Zabbix Server. Comprueba `ufw status` o `firewall-cmd --list-all`.
`ZBX_NOTSUPPORTED`	El ítem de monitoreo no es compatible con el agent o el plugin.	Verifica que el plugin requerido esté instalado (`zabbix-agent2-plugin-*`) y configurado correctamente. Comprueba la sintaxis de la clave en la interfaz Zabbix.
Ningún dato en la interfaz Zabbix, pero `agent.ping` funciona	`Hostname` en `zabbix_agent2.conf` no coincide con el nombre de host en Zabbix Server.	Asegúrate de que `Hostname` en el archivo de configuración del agent sea idéntico al configurado en la interfaz web de Zabbix. Reinicia el agent.
`Get value from agent failed: ZBX_TCP_READ_ERROR: [Timeout was reached]`	El agent no responde a tiempo o está sobrecargado.	Comprueba la carga del host y el estado del servicio `zabbix-agent2`. Aumenta `Timeout` en `zabbix_agent2.conf` si el host es lento.
`Active checks are not enabled.` en el log del agent	`ServerActive` no configurado o no alcanzable.	Asegúrate de que `ServerActive` esté configurado correctamente con la IP del Zabbix Server y que el puerto 10051/TCP esté abierto en el Zabbix Server.

Preguntas frecuentes

¿Puedo usar Zabbix Agent 2 y el agent clásico en el mismo host?

Técnicamente sí, pero está totalmente desaconsejado. Tener dos agents que intentan recopilar datos del mismo host puede llevar a conflictos, consumo excesivo de recursos y datos duplicados o erróneos. Siempre es preferible elegir una de las dos versiones y atenerse a ella para un determinado host, aprovechando al máximo las capacidades del Agent 2, incluidos sus plugins.

¿Cuál es la diferencia principal entre los controles activos y pasivos?

En los controles pasivos, el Zabbix Server solicita activamente los datos al agent. El agent está a la escucha y responde. En los controles activos, el propio agent se conecta al server, pregunta qué datos debe recopilar y los envía. Los controles activos son generalmente más eficientes en entornos con muchos ítems o con agents detrás de NAT/firewall, ya que el agent inicia la conexión.

¿Debo reiniciar el servicio después de cada modificación al zabbix_agent2.conf?

Sí, después de cada modificación al archivo de configuración zabbix_agent2.conf (o a los archivos incluidos en el directorio zabbix_agent2.d/), es obligatorio reiniciar el servicio zabbix-agent2 para aplicar las nuevas configuraciones. El servicio no recarga automáticamente la configuración, por lo que un reinicio es la única forma de que sean efectivas.

¿Cómo puedo monitorear los logs con Zabbix Agent 2?

Zabbix Agent 2 soporta el monitoreo de los archivos de log mediante claves como log[] o logrt[]. Estas claves permiten buscar patrones específicos en los logs y enviar solo las líneas pertinentes al Zabbix Server. Es una forma eficaz de detectar errores o eventos críticos en tiempo real sin tener que analizar manualmente los archivos de log de gran tamaño. Lee también: logrotate Linux: Configurar Rotación de Logs

¿Es posible actualizar un Zabbix Agent clásico a Zabbix Agent 2?

Sí, es posible, pero no es una simple «actualización» en el sentido tradicional. Requiere la desinstalación del agent clásico y la instalación de Zabbix Agent 2, siguiendo los pasos descritos en este artículo. Es aconsejable planificar la operación, probarla en un entorno de staging y asegurarse de que las plantillas asociadas al host sean compatibles con el Agent 2 para evitar interrupciones en el monitoreo.

Conclusiones con Puntos Clave Operativos

Zabbix Agent 2 representa un significativo paso adelante en el monitoreo de hosts, ofreciendo mayor eficiencia y una flexibilidad sin precedentes gracias a su arquitectura basada en plugins. La adopción de esta versión te permite consolidar el monitoreo de sistemas operativos, bases de datos y contenedores Docker con un único agente, reduciendo la complejidad y mejorando la recopilación de datos.

Los puntos clave operativos principales son:

Prioriza Agent 2 para los nuevos despliegues: Por su rendimiento y la amplia gama de plugins nativos, es la mejor opción para monitorear entornos modernos.
Instalación completa de los plugins: No te limites al agent base; instala siempre zabbix-agent2-plugin-* para tener todas las funcionalidades a mano.
Configuración Hostname crítica: Asegúrate de que el Hostname en el zabbix_agent2.conf coincida exactamente con el configurado en el Zabbix Server para evitar problemas de comunicación.
Firewall no negociable: El puerto 10050/TCP debe estar abierto en el firewall del host para permitir los controles pasivos desde el Zabbix Server.
Aprovecha zabbix_get: Esta herramienta es tu mejor amigo para la resolución de problemas y la verificación rápida del funcionamiento del agent y sus ítems.

Implementando correctamente Zabbix Agent 2, obtendrás una visibilidad más profunda y reactiva sobre la salud y el rendimiento de tus sistemas, permitiéndote intervenir proactivamente y mantener la estabilidad operativa.

Fuentes

Actualizado: octubre de 2026