Protocolli di controllo passivi e attivi

Questa sezione fornisce i dettagli del protocollo relativi ai controlli passivi e attivi eseguiti da Zabbix agent e Zabbix agent 2.

Zabbix utilizza un protocollo di comunicazione basato su JSON per comunicare con gli agent.

I protocolli di Zabbix agent e Zabbix agent 2 sono stati unificati a partire da Zabbix 7.0. La differenza tra le richieste/risposte di Zabbix agent e Zabbix agent 2 è espressa dal valore del tag "variant".

Controlli passivi

Un controllo passivo è una semplice richiesta di dati. Il server o il proxy Zabbix richiede alcuni dati (ad esempio, il carico della CPU) e l'agent Zabbix invia il risultato al server.

I controlli passivi vengono eseguiti in modo asincrono: non è necessario ricevere la risposta a una richiesta prima che vengano avviati altri controlli. Anche la risoluzione DNS è asincrona.

Il poller dell'agent tenterà di connettersi a tutti gli indirizzi restituiti dalla ricerca DNS. In questo modo, se un indirizzo IP non è raggiungibile, il poller proverà il successivo indirizzo disponibile, aumentando la probabilità di una connessione riuscita. Questo miglioramento si applica sia al server Zabbix sia al proxy.

La concorrenza massima dei controlli asincroni è 1000 (definita da MaxConcurrentChecksPerPoller).

Il numero di poller asincroni dell'agent è definito dal parametro StartAgentPollers.

Richiesta del server

Per la definizione dell'intestazione e della lunghezza dei dati, fare riferimento ai dettagli del protocollo.

{
  "request": "passive checks",
  "data": [
    {
      "key": "agent.version",
      "timeout": 3
    }
  ]
}

Risposta dell'agent

{
  "version": "8.0.0",
  "variant": 2,
  "data": [
    {
      "value": "8.0.0"
    }
  ]
}

Ad esempio, per gli item supportati:

1. Il server apre una connessione TCP
2. Il server invia <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]}
3. L'agent legge la richiesta e risponde con <HEADER><DATALEN>{"version":"8.0.0","variant":2,"data":[{"value":1}]}
4. Il server elabora i dati per ottenere il valore, '1' nel nostro caso
5. La connessione TCP viene chiusa

Per gli item non supportati:

1. Il server apre una connessione TCP
2. Il server invia <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size[/nono]","timeout":3}]}
3. L'agent legge la richiesta e risponde con <HEADER><DATALEN>{"version":"8.0.0","variant":2,"data":[{"error":"Unsupported item key."}]}
4. Il server elabora i dati, cambia lo stato dell'item in non supportato con il messaggio di errore specificato
5. La connessione TCP viene chiusa

Failover al vecchio protocollo

Per garantire che Zabbix server o proxy possano funzionare con agent delle versioni precedenti alla 7.2, che utilizzano il protocollo in testo semplice, è stato implementato un failover al vecchio protocollo.

I controlli passivi vengono eseguiti usando il protocollo JSON (7.0 e versioni successive) dopo il riavvio o quando la configurazione dell'interfaccia viene modificata.
Se non viene ricevuta alcuna risposta JSON valida (l'agent ha inviato "ZBX_NOTSUPPORTED"), Zabbix memorizzerà nella cache l'interfaccia come vecchio protocollo e ritenterà il controllo inviando solo la chiave dell'item.

Si noti che ogni ora Zabbix server/proxy proverà nuovamente a lavorare con il nuovo protocollo con tutte le interfacce, tornando al vecchio protocollo se necessario.

Controlli attivi

I controlli attivi richiedono un'elaborazione più complessa. L'agent deve prima recuperare dal server/proxy un elenco di item e/o comandi remoti per l'elaborazione indipendente.

I server/proxy da cui ottenere i controlli attivi sono elencati nel parametro 'ServerActive' del file di configurazione dell'agent. La frequenza con cui vengono richiesti questi controlli è impostata dal parametro 'RefreshActiveChecks' nello stesso file di configurazione. Tuttavia, se l'aggiornamento dei controlli attivi non riesce, il tentativo viene ripetuto dopo 60 secondi predefiniti.

L'agent invia quindi periodicamente i nuovi valori al server. Se l'agent ha ricevuto dei comandi remoti da eseguire, verrà inviato anche il risultato dell'esecuzione. Si noti che l'esecuzione di comandi remoti su un agent attivo è supportata a partire da Zabbix agent 7.0.

Ottenere l'elenco degli item

Richiesta dell'agent

La richiesta di active checks viene utilizzata per ottenere gli active checks da elaborare da agent.
Questa richiesta viene inviata dall'agent all'avvio e poi a intervalli di RefreshActiveChecks.

{
  "request": "active checks",
  "host": "Zabbix server",
  "host_metadata": "mysql,nginx",
  "interface": "zabbix.server.lan",
  "ip": "159.168.1.1",
  "port": 12050,
  "version": "8.0.0",
  "variant": 2,
  "config_revision": 1,
  "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
}

Risposta del server

La risposta degli active checks viene inviata dal server a agent dopo l'elaborazione della richiesta di active checks.

{
  "response": "success",
  "config_revision": 2,
  "data": [
    {
      "key": "system.uptime",
      "itemid": 1234,
      "delay": "10s",
      "lastlogsize": 0,
      "mtime": 0
    },
    {
      "key": "agent.version",
      "itemid": 5678,
      "delay": "10m",
      "lastlogsize": 0,
      "mtime": 0,
      "timeout": "30s"
    }
  ],
  "commands": [
    {
      "command": "df -h --output=source,size / | awk 'NR>1 {print $2}'",
      "id": 1324,
      "wait": 1
    }
  ]
}

Il server deve rispondere con success.

Ad esempio:

1. Agent apre una connessione TCP
2. Agent richiede l'elenco dei check
3. Server risponde con un elenco di item e dei comandi remoti da eseguire
4. Agent analizza la risposta
5. La connessione TCP viene chiusa
6. Agent avvia la raccolta periodica dei dati ed esegue i comandi remoti (supportato da Zabbix agent 7.0)

Invio dei dati raccolti

Agent invia

La richiesta di dati dell'agent contiene i valori degli item raccolti e i valori dei comandi remoti eseguiti (se presenti).

{
  "request": "agent data",
  "data": [
    {
      "id": 1,
      "itemid": 5678,
      "value": "7.0.0",
      "clock": 1712830783,
      "ns": 76808644
    },
    {
      "id": 2,
      "itemid": 1234,
      "value": "69672",
      "clock": 1712830783,
      "ns": 77053975
    }
  ],
  "commands": [
    {
      "id": 1324,
      "value": "16G"
    }
  ],
  "session": "8495cd52070e6ca52b371f29c8574165",
  "host": "Zabbix server",
  "version": "8.0.0",
  "variant": 2
}

A ogni valore viene assegnato un ID virtuale. L'ID del valore è un semplice contatore crescente, univoco all'interno di una singola sessione di dati (identificata dal token di sessione). Questo ID viene usato per scartare i valori duplicati che potrebbero essere inviati in ambienti con connettività scarsa.

Risposta del server

La risposta dei dati dell'agent viene inviata dal server all'agent dopo l'elaborazione della richiesta di dati dell'agent.

{
  "response": "success",
  "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
}

Ad esempio:

1. L'agent apre una connessione TCP
2. L'agent invia un elenco di valori
3. Il server elabora i dati e invia lo stato indietro
4. La connessione TCP viene chiusa

Messaggio heartbeat

Agent invia

Il messaggio heartbeat viene inviato da un agent attivo a server/proxy Zabbix ogni HeartbeatFrequency secondi (configurato nel file di configurazione di Zabbix agent/agent 2).

Viene utilizzato per monitorare la disponibilità dei controlli attivi.

{
  "request": "active check heartbeat",
  "host": "Zabbix server",
  "heartbeat_freq": 60,
  "version": "8.0.0",
  "variant": 2
}

Risposta di reindirizzamento

Quando un host è stato riassegnato, il server può indicare all'agent di reindirizzare il proprio heartbeat (e i successivi controlli attivi) a un'altra istanza di proxy o server.

  {
    "response": "failed",
    "redirect": {
      "revision": 2,
      "address": "192.0.2.1:10055"
    }
  }

Vecchio protocollo XML