Zabbix Agent 2: Installazione, Configurazione e Plugin

Q: Devo riavviare il servizio dopo ogni modifica al zabbix_agent2.conf?

Sì, dopo ogni modifica al file di configurazione zabbix_agent2.conf (o ai file inclusi nella directory zabbix_agent2.d/), è obbligatorio riavviare il servizio zabbix-agent2 per applicare le nuove impostazioni. Il servizio non ricarica automaticamente la configurazione, quindi un riavvio è l'unico modo per renderle effettive.

Zabbix Agent 2 è l’ultima evoluzione del client di monitoraggio di Zabbix, progettato per offrire maggiore efficienza e funzionalità estese rispetto alla sua controparte classica. L’installazione e la configurazione corrette di questo componente sono fondamentali per garantire un monitoraggio affidabile e granulare dei tuoi host, dai server web ai database, fino ai container Docker.

Zabbix Agent 2 in 60 secondi

Per chi ha fretta, ecco i passaggi essenziali per installare e configurare Zabbix Agent 2 su un sistema basato su Debian/Ubuntu:

# 1. Scarica il pacchetto repository (es. per 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. Installa Zabbix Agent 2 e i plugin
sudo apt install zabbix-agent2 zabbix-agent2-plugin-*

# 3. Modifica il file di configurazione
sudo nano /etc/zabbix/zabbix_agent2.conf
# Imposta Server, ServerActive e Hostname con l'IP del tuo Zabbix Server e il nome dell'host

# 4. Abilita e avvia il servizio
sudo systemctl enable --now zabbix-agent2

# 5. Apri la porta 10050 sul firewall (se usi UFW)
sudo ufw allow from 10.0.0.10 to any port 10050 proto tcp # Sostituisci 10.0.0.10 con l'IP del tuo Zabbix Server

# 6. Verifica il funzionamento dal Zabbix Server
zabbix_get -s web01 -k agent.ping # Sostituisci web01 con l'Hostname dell'agent

Il monitoraggio proattivo è una pietra angolare della gestione IT, essenziale per prevenire interruzioni di servizio e ottimizzare le performance. In ambienti complessi, dove ogni millisecondo conta, disporre di strumenti efficienti come Zabbix Agent 2 fa la differenza. Questo agent, riscritto in Go, non solo offre prestazioni superiori ma integra anche un sistema di plugin flessibile che estende le sue capacità ben oltre il monitoraggio base. Dalla gestione delle metriche di sistema ai dettagli di database come PostgreSQL o MySQL, fino all’osservazione dei container Docker, Zabbix Agent 2 è progettato per semplificare la raccolta dati. Questo articolo ti guiderà attraverso l’installazione, la configurazione e l’utilizzo dei plugin, fornendo una base solida per un monitoraggio efficace dei tuoi sistemi.

Versioni di riferimento: Zabbix Agent 2 (versione 6.4) · documentazione consultata a ottobre 2026

Prerequisiti

Prima di iniziare l’installazione di Zabbix Agent 2, assicurati di avere i seguenti prerequisiti:

Un sistema operativo Linux (questi esempi si basano su Debian/Ubuntu, ma i concetti sono simili per CentOS/RHEL).
Accesso con privilegi di sudo o root sull’host da monitorare.
Un Zabbix Server funzionante e accessibile dalla rete dell’host.
L’indirizzo IP del Zabbix Server (sarà necessario per la configurazione).
Conoscenza base delle operazioni da terminale Linux.

Agent 2 o agent classico: cosa cambia

La scelta tra Zabbix Agent classico e Zabbix Agent 2 non è solo una questione di versione, ma di architettura e funzionalità. L’Agent classico, scritto in C, è robusto e collaudato, ideale per il monitoraggio di base delle risorse di sistema. Tuttavia, per estendere le sue capacità, spesso richiede script esterni o moduli aggiuntivi.

Zabbix Agent 2, invece, è stato completamente riscritto in Go. Questa riprogettazione porta diversi vantaggi significativi:

Architettura basata su plugin: L’Agent 2 supporta un sistema di plugin nativo che permette di estendere facilmente le capacità di monitoraggio per servizi specifici come Docker, PostgreSQL, MySQL e altro ancora, senza la necessità di script esterni complessi. Questi plugin sono scritti direttamente in Go e beneficiano dell’architettura dell’agent.
Efficienza: Essendo scritto in Go, l’Agent 2 è generalmente più efficiente in termini di consumo di risorse (CPU e memoria) e più veloce nella raccolta dei dati, specialmente quando si gestiscono molti item di monitoraggio contemporaneamente.
Controlli attivi robusti: L’Agent 2 è particolarmente ottimizzato per i controlli attivi (Zabbix Server chiede all’agent di inviare i dati). Questa modalità riduce il carico sul server Zabbix e permette all’agent di raccogliere dati in modo più autonomo.
Meno dipendenze: L’Agent 2 ha meno dipendenze esterne rispetto alla versione classica, semplificando l’installazione e riducendo potenziali conflitti. Leggi anche: Docker Spazio Disco: Prune, Log e Immagini Inutilizzate

In sintesi, se hai bisogno di monitorare applicazioni specifiche (database, container) con maggiore efficienza e flessibilità, l’Agent 2 è la scelta consigliata per i nuovi deployment. Per host con requisiti minimi o dove l’Agent classico è già in uso e funziona bene, non è obbligatorio un upgrade immediato, ma valuta i benefici a lungo termine.

Installare dal repository ufficiale

Per garantire stabilità e ricevere gli aggiornamenti di sicurezza, è sempre consigliabile installare Zabbix Agent 2 dai repository ufficiali di Zabbix. Questo metodo assicura che tu stia utilizzando pacchetti testati e compatibili con la tua distribuzione Linux.

1. Aggiungere il repository Zabbix:

Per i sistemi basati su Debian/Ubuntu, il primo passo è aggiungere il repository Zabbix. Questo varia leggermente a seconda della versione del sistema operativo. Per Ubuntu 22.04 (Jammy Jellyfish) e Zabbix 6.4, i comandi sono i seguenti:

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

Assicurati di controllare la pagina ufficiale di download di Zabbix (https://www.zabbix.com/download_agents) per ottenere l’URL corretto del pacchetto zabbix-release per la tua specifica distribuzione e versione di Zabbix.

2. Installare Zabbix Agent 2 e i plugin:

Una volta aggiunto il repository, puoi procedere con l’installazione dell’agent e dei suoi plugin. È buona norma installare il pacchetto zabbix-agent2-plugin-* per avere tutti i plugin disponibili fin da subito, anche se non li userai immediatamente. Questo evita di doverli installare in un secondo momento.

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

Questo comando installerà l’agent e tutti i plugin ufficiali disponibili. Una volta completata l’installazione, il servizio zabbix-agent2 sarà probabilmente già avviato, ma sarà necessario configurarlo.

Configurare Server, ServerActive e Hostname

La configurazione di Zabbix Agent 2 avviene tramite il file zabbix_agent2.conf. Questo file si trova tipicamente in /etc/zabbix/. Le tre direttive più importanti da configurare sono Server, ServerActive e Hostname.

Apri il file di configurazione con un editor di testo:

sudo nano /etc/zabbix/zabbix_agent2.conf

Cerca e modifica le seguenti righe (potrebbero essere commentate con un #): Leggi anche: UFW Firewall Ubuntu: Configurazione Completa dalla A alla Z (2026)

Server: Questa direttiva specifica l’indirizzo IP o il nome DNS del Zabbix Server o proxy da cui l’agent accetterà connessioni per i controlli passivi. Se hai più server Zabbix o proxy, puoi specificarli separati da virgola.

    Server=10.0.0.10

Sostituisci 10.0.0.10 con l’IP effettivo del tuo Zabbix Server.

ServerActive: Questa direttiva è cruciale per i controlli attivi. Specifica l’indirizzo IP o il nome DNS del Zabbix Server o proxy a cui l’agent si connetterà per recuperare gli item di monitoraggio attivi e inviare i dati. Anche qui, puoi specificare più server/proxy. La porta di default per ServerActive è 10051.

    ServerActive=10.0.0.10

Ancora, 10.0.0.10 deve essere l’IP del tuo Zabbix Server.

Hostname: Questo è il nome univoco dell’host che verrà visualizzato nell’interfaccia web di Zabbix. È fondamentale che questo Hostname corrisponda esattamente al nome host configurato nel Zabbix Server per l’host in questione. Se non corrispondono, il monitoraggio non funzionerà.

    Hostname=web01

Sostituisci web01 con un nome descrittivo e univoco per il tuo host.

Dopo aver salvato le modifiche al file zabbix_agent2.conf, riavvia il servizio Zabbix Agent 2 per applicarle:

sudo systemctl restart zabbix-agent2

Per assicurarti che il servizio si avvii automaticamente all’avvio del sistema, abilitalo:

sudo systemctl enable --now zabbix-agent2

Controlli attivi e passivi

Zabbix Agent 2 supporta due modalità principali di raccolta dati:

Controlli passivi: Il Zabbix Server (o proxy) interroga l’agent per ottenere un valore specifico (es. agent.ping). L’agent ascolta sulla porta TCP 10050 e risponde alle richieste. Questa modalità è utile per controlli ad-hoc o per item che non richiedono una raccolta frequente.
Controlli attivi: L’agent si connette periodicamente al Zabbix Server (o proxy) sulla porta TCP 10051, richiede un elenco di item di monitoraggio attivi configurati per quell’host e invia i dati raccolti. Questa modalità è più efficiente per un gran numero di item e per il monitoraggio di dati che cambiano frequentemente, in quanto l’agent gestisce autonomamente la pianificazione della raccolta. È la modalità preferita per la maggior parte dei template moderni.

La direttiva Server gestisce i controlli passivi, mentre ServerActive gestisce i controlli attivi. È buona pratica configurare entrambe per la massima flessibilità e robustezza del monitoraggio.

Firewall e porta 10050

Un errore comune che impedisce il corretto funzionamento di Zabbix Agent 2 è la mancata configurazione del firewall. L’agent comunica con il Zabbix Server (e viceversa) su porte specifiche:

Porta 10050/TCP: Utilizzata per i controlli passivi. Il Zabbix Server si connette a questa porta sull’agent.
Porta 10051/TCP: Utilizzata per i controlli attivi. L’agent si connette a questa porta sul Zabbix Server.

È essenziale configurare il firewall sull’host dove è installato Zabbix Agent 2 per consentire le connessioni in entrata sulla porta 10050 dal Zabbix Server. Se usi ufw (Uncomplicated Firewall) su Ubuntu, il comando è:

sudo ufw allow from 10.0.0.10 to any port 10050 proto tcp

Sostituisci 10.0.0.10 con l’indirizzo IP del tuo Zabbix Server. Se non specifichi from, la porta sarà aperta a qualsiasi IP, il che è meno sicuro. Leggi anche: SSH Senza Password Linux: Configurare le Chiavi in 5 Minuti (2026)

Se utilizzi un firewall diverso (es. firewalld su CentOS/RHEL o iptables), dovrai adattare il comando di conseguenza. Verifica sempre lo stato del firewall dopo le modifiche per assicurarti che la regola sia stata applicata correttamente.

Plugin: PostgreSQL, MySQL, Docker

Uno dei maggiori punti di forza di Zabbix Agent 2 è il suo sistema di plugin integrato, che estende le capacità di monitoraggio per servizi specifici. Se hai installato il pacchetto zabbix-agent2-plugin-*, hai già a disposizione molti di questi plugin.

Per abilitare e configurare un plugin, è spesso necessario modificare il file zabbix_agent2.conf e aggiungere le direttive Plugins e PluginConf.

Esempio: Plugin PostgreSQL

Per monitorare un database PostgreSQL, devi configurare il plugin PostgreSQL e fornire le credenziali di accesso. Un esempio di configurazione potrebbe essere:

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

# Esempio di configurazione per un'istanza PostgreSQL
# Il file di configurazione specifico del plugin può essere creato in /etc/zabbix/zabbix_agent2.d/
# Esempio: /etc/zabbix/zabbix_agent2.d/postgresql.conf

# Connessione al database (utente, password, host, porta, dbname)
# Assicurati che l'utente Zabbix abbia i permessi di lettura necessari
PluginConf.PostgreSQL.User=zabbix_monitor
PluginConf.PostgreSQL.Password=very_secret_password
PluginConf.PostgreSQL.ConnString=host=localhost port=5432 dbname=postgres

Dopo aver modificato il file di configurazione (o creato un file .conf in zabbix_agent2.d/), riavvia l’agent. Poi, nell’interfaccia web di Zabbix, collega l’host a un template come PostgreSQL by Zabbix agent 2.

Esempio: Plugin Docker

Per Docker, il plugin permette di monitorare container, immagini, volumi e performance. Spesso non richiede configurazione aggiuntiva nel zabbix_agent2.conf se Docker è installato e l’utente zabbix ha i permessi per accedere al socket Docker (aggiungendo l’utente zabbix al gruppo docker).

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

Quindi, collega l’host al template Docker by Zabbix agent 2 nell’interfaccia web di Zabbix.

Esempio: Plugin MySQL

Similmente a PostgreSQL, il plugin MySQL richiede credenziali per accedere al database. Puoi configurarle in zabbix_agent2.conf o in un file separato 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

Riordina l’agent e collega il template MySQL by Zabbix agent 2.

È fondamentale consultare la documentazione ufficiale di Zabbix per ogni plugin specifico, poiché i parametri di configurazione e i requisiti possono variare leggermente.

Collegare l’host al template in Zabbix

Una volta che Zabbix Agent 2 è installato e configurato sull’host, il passo successivo è collegare l’host a Zabbix Server e assegnargli i template di monitoraggio appropriati.

Aggiungi l’host: Accedi all’interfaccia web di Zabbix. Vai su Configuration > Hosts e clicca su Create host.
Configura i dettagli dell’host:

Host name: Inserisci il Hostname esatto che hai configurato nel file zabbix_agent2.conf (es. web01).
Visible name: Un nome più descrittivo per l’interfaccia.
Groups: Assegna l’host a uno o più gruppi (es. Linux servers, Web servers).
Interfaces: Clicca su Add accanto a Agent interfaces. Seleziona Agent come tipo, inserisci l’indirizzo IP dell’host e lascia la porta 10050 (default).

Collega i template: Vai alla scheda Templates. Clicca su Select e cerca i template che vuoi applicare. Per un server Linux con Agent 2, un buon punto di partenza è Linux by Zabbix agent e Zabbix agent 2. Se stai monitorando servizi specifici, aggiungi anche i template pertinenti (es. PostgreSQL by Zabbix agent 2, Docker by Zabbix agent 2).
Aggiungi l’host: Clicca su Add per salvare le modifiche.

Dopo pochi minuti, Zabbix Server inizierà a interrogare l’agent e a raccogliere i dati. Puoi verificare lo stato del monitoraggio nella sezione Monitoring > Latest data.

Verificare con zabbix_get

Il comando zabbix_get è uno strumento diagnostico essenziale per verificare che Zabbix Agent 2 stia rispondendo correttamente e che stia raccogliendo i dati desiderati. zabbix_get viene eseguito dal Zabbix Server o da un host con i zabbix-frontend-php installati.

La sintassi base è:

zabbix_get -s <IP_O_HOSTNAME_AGENT> -k <KEY_ITEM_MONITORAGGIO>

-s: Specifica l’indirizzo IP o l’Hostname dell’agent da interrogare.
-k: Specifica la chiave dell’item di monitoraggio da recuperare.

Per testare la connettività di base e la risposta dell’agent:

zabbix_get -s web01 -k agent.ping

Un output tipico:

Il valore 1 indica che l’agent è attivo e risponde. Se non ricevi nulla o un errore, controlla la configurazione del firewall, che l’agent sia in esecuzione e che Server sia configurato correttamente nel zabbix_agent2.conf.

Per testare un item più specifico, ad esempio il carico CPU:

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

Un output tipico:

0.15

Questo comando interroga direttamente l’agent 2 localmente e restituisce il valore del carico CPU medio nell’ultimo minuto. È utile per verificare se un plugin o un item specifico funziona correttamente prima di configurarlo in Zabbix Server.

Errori comuni e troubleshooting

Errore o messaggio esatto	Causa	Soluzione
`ZBX_TCP_READ_ERROR: [Closed by remote host]`	Il firewall blocca la connessione tra Zabbix Server e Agent.	Assicurati che la porta 10050/TCP sia aperta sull’host dell’agent per l’IP del Zabbix Server. Controlla `ufw status` o `firewall-cmd --list-all`.
`ZBX_NOTSUPPORTED`	L’item di monitoraggio non è supportato dall’agent o dal plugin.	Verifica che il plugin richiesto sia installato (`zabbix-agent2-plugin-*`) e configurato correttamente. Controlla la sintassi della chiave nell’interfaccia Zabbix.
Nessun dato nell’interfaccia Zabbix, ma `agent.ping` funziona	`Hostname` nel `zabbix_agent2.conf` non corrisponde al nome host in Zabbix Server.	Assicurati che `Hostname` nel file di configurazione dell’agent sia identico a quello configurato nell’interfaccia web di Zabbix. Riavvia l’agent.
`Get value from agent failed: ZBX_TCP_READ_ERROR: [Timeout was reached]`	L’agent non risponde in tempo o è sovraccarico.	Controlla il carico dell’host e lo stato del servizio `zabbix-agent2`. Aumenta `Timeout` in `zabbix_agent2.conf` se l’host è lento.
`Active checks are not enabled.` nel log dell’agent	`ServerActive` non configurato o non raggiungibile.	Assicurati che `ServerActive` sia impostato correttamente con l’IP del Zabbix Server e che la porta 10051/TCP sia aperta sul Zabbix Server.

Domande frequenti

Posso usare Zabbix Agent 2 e l’agent classico sullo stesso host?

Tecnicamente sì, ma è fortemente sconsigliato. Avere due agent che tentano di raccogliere dati dallo stesso host può portare a conflitti, consumo eccessivo di risorse e dati duplicati o errati. È sempre preferibile scegliere una delle due versioni e attenersi ad essa per un determinato host, sfruttando appieno le capacità dell’Agent 2, inclusi i suoi plugin.

Qual è la differenza principale tra i controlli attivi e passivi?

Nei controlli passivi, il Zabbix Server richiede attivamente i dati all’agent. L’agent è in ascolto e risponde. Nei controlli attivi, l’agent stesso si connette al server, chiede quali dati deve raccogliere e li invia. I controlli attivi sono generalmente più efficienti in ambienti con molti item o con agent dietro NAT/firewall, poiché l’agent inizia la connessione.

Devo riavviare il servizio dopo ogni modifica al zabbix_agent2.conf?

Sì, dopo ogni modifica al file di configurazione zabbix_agent2.conf (o ai file inclusi nella directory zabbix_agent2.d/), è obbligatorio riavviare il servizio zabbix-agent2 per applicare le nuove impostazioni. Il servizio non ricarica automaticamente la configurazione, quindi un riavvio è l’unico modo per renderle effettive.

Come posso monitorare i log con Zabbix Agent 2?

Zabbix Agent 2 supporta il monitoraggio dei file di log tramite chiavi come log[] o logrt[]. Queste chiavi permettono di cercare pattern specifici nei log e di inviare solo le righe pertinenti al Zabbix Server. È un modo efficace per rilevare errori o eventi critici in tempo reale senza dover analizzare manualmente i file di log di grandi dimensioni. Leggi anche: logrotate: Configurare Rotazione Log su Linux

È possibile aggiornare un Zabbix Agent classico a Zabbix Agent 2?

Sì, è possibile, ma non è un semplice “aggiornamento” nel senso tradizionale. Richiede la disinstallazione dell’agent classico e l’installazione di Zabbix Agent 2, seguendo i passaggi descritti in questo articolo. È consigliabile pianificare l’operazione, testarla in un ambiente di staging e assicurarsi che i template associati all’host siano compatibili con l’Agent 2 per evitare interruzioni nel monitoraggio.

Conclusioni con takeaway operativi

Zabbix Agent 2 rappresenta un significativo passo avanti nel monitoraggio degli host, offrendo maggiore efficienza e una flessibilità senza precedenti grazie alla sua architettura basata su plugin. L’adozione di questa versione ti permette di consolidare il monitoraggio di sistemi operativi, database e container Docker con un unico agente, riducendo la complessità e migliorando la raccolta dati.

I takeaway operativi principali sono:

Prioritizza Agent 2 per i nuovi deployment: Per le sue performance e l’ampia gamma di plugin nativi, è la scelta migliore per monitorare ambienti moderni.
Installazione completa dei plugin: Non limitarti all’agent base; installa sempre zabbix-agent2-plugin-* per avere tutte le funzionalità a portata di mano.
Configurazione Hostname critica: Assicurati che il Hostname nel zabbix_agent2.conf corrisponda esattamente a quello configurato nel Zabbix Server per evitare problemi di comunicazione.
Firewall non negoziabile: La porta 10050/TCP deve essere aperta sul firewall dell’host per consentire i controlli passivi dal Zabbix Server.
Sfrutta zabbix_get: Questo strumento è il tuo migliore amico per il troubleshooting e la verifica rapida del funzionamento dell’agent e dei suoi item.

Implementando correttamente Zabbix Agent 2, otterrai una visibilità più profonda e reattiva sulla salute e le performance dei tuoi sistemi, permettendoti di intervenire proattivamente e mantenere la stabilità operativa.

Fonti

Aggiornato: ottobre 2026