[comment]: # ({a6d31bd3-a6d31bd3})
# 2 Controlli degli agenti passivi e attivi

[comment]: # ({/a6d31bd3-a6d31bd3})

[comment]: # ({1b7bc303-7bd0dd61})
#### Panoramica

Questa sezione fornisce dettagli sui controlli passivi e attivi eseguiti da
[Zabbix agent](/manual/concepts/agent) e [Zabbix agent 2](/manual/concepts/agent2).

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".

[comment]: # ({/1b7bc303-7bd0dd61})

[comment]: # ({f0a43b2b-e6db8dd6})
#### 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 restituisce 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](/manual/appendix/config/zabbix_server#maxconcurrentchecksperpoller)).

Il numero di poller asincroni dell'agent è definito dal parametro [StartAgentPollers](/manual/appendix/config/zabbix_server#startagentpollers).

**Richiesta del server**

Per la definizione della lunghezza dell'header e dei dati, fare riferimento ai [dettagli del protocollo](/manual/appendix/protocols/header_datalen).

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

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| request |<| _string_ | yes | `"passive checks"` |
| data |<| _array of object_ | yes | Passive check item. |
| | key | _string_ | yes | Item key with expanded macros. |
|^| timeout | _number_ | yes | Communication timeout. |

**Risposta dell'agent**

```json
{
  "version": "7.4.0",
  "variant": 2,
  "data": [
    {
      "value": "7.4.0"
    }
  ]
}
```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| version |<| _string_ | yes | The agent version number. |
| variant |<| _number_ | yes | The agent variant (*1* - Zabbix agent, *2* - Zabbix agent 2). |
| data |<| _array of object_ | yes |Contains the result of the check. |
| | value | _string_ | no | The item value if the check was successful. |
| | error | _string_ | no | The error message if the check was not successful. |

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":"7.4.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":"7.4.0","variant":2,"data":[{"error":"Unsupported item key."}]}**
4.  Il server elabora i dati, modifica lo stato dell'item in non supportato con il
    messaggio di errore specificato
5.  La connessione TCP viene chiusa

[comment]: # ({/f0a43b2b-e6db8dd6})

[comment]: # ({241f3b68-d33dfdd3})
##### Fallback 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 fallback al vecchio protocollo. 

I controlli passivi vengono eseguiti utilizzando il protocollo JSON (7.0 e successive) dopo un riavvio o quando viene modificata la configurazione dell'interfaccia.  
Se in risposta non viene ricevuto alcun JSON valido (l'agent ha inviato "ZBX_NOTSUPPORTED"), Zabbix memorizzerà 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 utilizzare il nuovo protocollo con tutte le interfacce, tornando al vecchio protocollo se necessario.

[comment]: # ({/241f3b68-d33dfdd3})

[comment]: # ({86593407-ecdd6e8e})
#### 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](/manual/config/notifications/action/operation/remote_command) per l'elaborazione indipendente.

I server/proxy da cui ottenere i controlli attivi sono elencati nel parametro 'ServerActive' del [file di configurazione](/manual/appendix/config/zabbix_agent2) 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, viene ritentato dopo 60 secondi codificati in modo fisso.

[comment]: # ({/86593407-ecdd6e8e})

[comment]: # ({e520c471-4c14cd28})
::: notetip
A partire da Zabbix 6.4, l'agent (in modalità attiva) non riceve più dal server/proxy una copia completa della configurazione una volta ogni due minuti (impostazione predefinita).
Invece, per ridurre il traffico di rete e l'utilizzo delle risorse, viene eseguita una sincronizzazione incrementale della configurazione ogni 5 secondi (impostazione predefinita), durante la quale il server/proxy fornisce una copia completa della configurazione **solo** se l'agent non l'ha ancora ricevuta oppure se è cambiato qualcosa nella configurazione dell'host, nelle macro globali o nelle espressioni regolari globali.
:::

[comment]: # ({/e520c471-4c14cd28})

[comment]: # ({63166bda-2f80420a})
L'agent invia quindi periodicamente i nuovi valori al server o ai server.
Se l'agent ha ricevuto dei [comandi remoti](/manual/config/notifications/action/operation/remote_command) 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.

::: notetip
Se un agent si trova dietro il firewall, si può prendere in considerazione
l'uso dei soli controlli attivi, perché in questo caso non sarebbe necessario
modificare il firewall per consentire le connessioni iniziali in ingresso.
:::

[comment]: # ({/63166bda-2f80420a})

[comment]: # ({426dc1ae-d898e135})
##### Ottenere l'elenco degli item

**Richiesta dell'agent**

La richiesta di active checks viene utilizzata per ottenere gli active checks da elaborare da parte dell'agent.  
Questa richiesta viene inviata dall'agent all'avvio e poi a intervalli di [RefreshActiveChecks](/manual/appendix/config/zabbix_agent2).

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

| Field | Type | Mandatory | Value |
|-|-|-|--------|
| request | _string_ | yes | `active checks` |
| host | _string_ | yes | Nome dell'host. |
| host_metadata | _string_ | no | Il parametro di configurazione HostMetadata o il valore della metrica HostMetadataItem. |
| interface | _string_ | no | Il parametro di configurazione HostInterface o il valore della metrica HostInterfaceItem. |
| ip | _string_ | no | Il primo indirizzo IP del parametro di configurazione ListenIP, se impostato. |
| port | _number_ | no | Il valore del parametro di configurazione ListenPort, se impostato e diverso dalla porta di ascolto predefinita dell'agent. |
| version | _string_ | yes | Il numero di versione dell'agent. |
| variant | _number_ | yes | La variante dell'agent (*1* - Zabbix agent, *2* - Zabbix agent 2). |
| config_revision | _number_ | no | Identificatore della configurazione per la [sincronizzazione incrementale della configurazione](#active-checks). |
| session | _string_ | no | Identificatore di sessione per la [sincronizzazione incrementale della configurazione](#active-checks). |
  
**Risposta del server**

La risposta degli active checks viene inviata dal server all'agent dopo l'elaborazione della richiesta di active checks.
  
```json
{
  "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
    }
  ]
}

```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| response |<| _string_ | yes | `success` \| `failed` |
| info |<| _string_ | no | Informazioni sull'errore in caso di fallimento. |
| data |<| _array of objects_ | no | Item di active check. Omesse se la configurazione dell'host non è cambiata. |
| | key | _string_ | no | Chiave dell'item con macro espanse. |
|^| itemid | _number_ | no | Identificatore dell'item. |
|^| delay | _string_ | no | Intervallo di aggiornamento dell'item.<br>Gli intervalli flessibili/scheduling sono supportati sia da Zabbix agent sia da Zabbix agent 2 a partire da Zabbix 7.0. |
|^| lastlogsize | _number_ | no | lastlogsize dell'item. |
|^| mtime | _number_ | no | mtime dell'item. |
|^| timeout | _string_ | no | Timeout dell'item. |
| refresh_unsupported |<| _number_ | no | Intervallo di aggiornamento per item non supportati. |
| regexp |<| _array of objects_ | no | Espressioni regolari globali. |
| | name | _string_ | no | Nome dell'espressione regolare globale. |
|^| expression | _string_ | no | Espressione regolare globale. |
|^| expression_type | _number_ | no | Tipo di espressione regolare globale. |
|^| exp_delimiter | _string_ | no | Delimitatore dell'espressione regolare globale. |
|^| case_sensitive | _number_ | no | Impostazione di sensibilità alle maiuscole/minuscole dell'espressione regolare globale. |
| commands |<| _array of objects_ | no | Comandi remoti da eseguire. Inclusi se l'esecuzione di un comando remoto è stata attivata da un'azione [operation](/manual/config/notifications/action/operation#operations) o dall'esecuzione manuale di uno [script](/manual/web_interface/frontend_sections/alerts/scripts). Si noti che l'esecuzione di comandi remoti su un agent attivo è supportata da Zabbix agent 7.0. Gli agent attivi più vecchi ignoreranno eventuali comandi remoti inclusi nella risposta del server agli active checks. |
| | command | _string_ | no | Comando remoto. |
|^| id | _number_ | no | Identificatore del comando remoto. |
|^| wait | _number_ | no | Modalità di esecuzione del comando remoto ("0" (nowait) per i comandi provenienti da [operations](/manual/config/notifications/action/operation#operations) di un'azione; "1" (wait) per i comandi provenienti dall'esecuzione manuale di uno [script](/manual/web_interface/frontend_sections/alerts/scripts)). |
|^| timeout | _number_ | no | Timeout di esecuzione del comando remoto nella configurazione di [server](/manual/appendix/config/zabbix_server#timeout)/[proxy](/manual/appendix/config/zabbix_proxy#timeout). |
| config_revision | < | _number_ | no | Identificatore della configurazione per la [sincronizzazione incrementale della configurazione](#active-checks). Omesse se la configurazione dell'host non è cambiata. Incrementata se la configurazione dell'host viene modificata. |
  
Il server deve rispondere con success.

Ad esempio:

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

::: noteimportant
Si noti che i dati di configurazione (sensibili) possono diventare disponibili a soggetti che hanno accesso alla porta trapper di Zabbix server quando si utilizza un active check. Ciò è possibile perché chiunque può fingersi un agent attivo e richiedere i dati di configurazione degli item; l'autenticazione non avviene a meno che non si utilizzino opzioni di [crittografia](/manual/encryption).
:::

[comment]: # ({/426dc1ae-d898e135})

[comment]: # ({4c963bbb-8c5ecfe1})
##### 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.
  
```json
{
  "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": "7.4.0",
  "variant": 2
}
```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| request |<| _string_ | yes | `agent data` |
| data |<| _array of objects_ | yes | Valori degli item. |
| | id | _number_ | yes | L'identificatore del valore (contatore incrementale usato per verificare valori duplicati in caso di problemi di rete). |
|^| itemid | _number_ | yes | L'identificatore dell'item. |
|^| value | _string_ | no | Il valore dell'item. |
|^| lastlogsize | _number_ | no | Il lastlogsize dell'item. |
|^| mtime | _number_ | no | Il mtime dell'item. |
|^| state | _number_ | no | Lo stato dell'item. |
|^| source | _string_ | no | La sorgente del value event log. |
|^| eventid | _number_ | no | L'eventid del value event log. |
|^| severity | _number_ | no | La severity del value event log. |
|^| timestamp | _number_ | no | Il timestamp del value event log. |
|^| clock | _number_ | yes | Il timestamp del valore (secondi dall'Epoch). |
|^| ns | _number_ | yes | I nanosecondi del timestamp del valore. |
| commands |<| _array of objects_ | no | Risultato dell'esecuzione dei comandi remoti. Si noti che l'esecuzione di comandi remoti su un agent attivo è supportata da Zabbix agent 7.0. Gli agent attivi precedenti ignoreranno eventuali comandi remoti inclusi nella risposta del server alle active checks. |
| | id | _number_ | no | Identificatore del comando remoto. |
|^| value | _string_ | no | Risultato dell'esecuzione del comando remoto se l'esecuzione è andata a buon fine. |
|^| error | _string_ | no | Messaggio di errore dell'esecuzione del comando remoto se l'esecuzione è fallita. |
| session |<| _string_ | yes | Identificatore univoco della sessione generato ogni volta che l'agent viene avviato. |
| host |<| _string_ | yes | Nome dell'host. |
| version |<| _string_ | yes | Numero di versione dell'agent. |
| variant |<| _number_ | yes | La variante dell'agent (*1* - Zabbix agent, *2* - Zabbix agent 2). |

A ogni valore viene assegnato un ID virtuale. L'ID del valore è un semplice contatore crescente, univoco all'interno di una 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 ai dati dell'agent viene inviata dal server all'agent dopo l'elaborazione della richiesta di dati dell'agent.
  
```json
{
  "response": "success",
  "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
}
```

| Field | Type | Mandatory | Value |
|-|-|-|--------|
| response | _string_ | yes | `success` \| `failed` |
| info | _string_ | yes | Risultati dell'elaborazione degli item. |
  
::: noteimportant
Se l'invio di alcuni valori fallisce sul server (ad esempio, perché host o item sono stati disabilitati o eliminati), l'agent non ritenterà l'invio di tali valori.
:::

Ad esempio:

1.  Agent apre una connessione TCP
2.  Agent invia un elenco di valori
3.  Server elabora i dati e invia lo stato indietro
4.  La connessione TCP viene chiusa

::: noteimportant
Il messaggio di errore verrà troncato a 2048 simboli sul lato server.
:::

[comment]: # ({/4c963bbb-8c5ecfe1})

[comment]: # ({a13ec4d9-ee2b7a2a})
##### Messaggio heartbeat

**L'agent invia**

Il messaggio heartbeat viene inviato da un agent attivo a Zabbix server/proxy ogni HeartbeatFrequency secondi (configurato nel file di configurazione [Zabbix agent](/manual/appendix/config/zabbix_agentd)/[agent 2](/manual/appendix/config/zabbix_agent2)).

Viene utilizzato per monitorare la disponibilità dei controlli attivi.

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

| Field | Type | Mandatory | Value |
|-|-|-|-|
| request | _string_ | yes | `active check heartbeat` |
| host | _string_ | yes | Il nome dell'host. |
| heartbeat_freq | _number_ | yes | La frequenza heartbeat dell'agent (parametro di configurazione HeartbeatFrequency). |
| version | _string_ | yes | Il numero di versione dell'agent. |
| variant | _number_ | yes | La variante dell'agent (*1* - Zabbix agent, *2* - Zabbix agent 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.

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

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| response |<| _string_ | yes | `success` \| `failed` |
| redirect |<| _object_ | yes | Istruzioni di reindirizzamento. |
| | revision | _number_ | yes | Identificatore della revisione della configurazione. |
|^| address | _string_ | yes | Indirizzo di destinazione di server/proxy. |

[comment]: # ({/a13ec4d9-ee2b7a2a})

[comment]: # ({e66043c4-e66043c4})
#### Protocollo XML precedente

::: noteclassic
Zabbix accetterà fino a 16 MB di dati XML codificati in Base64, ma
un singolo valore decodificato non deve superare 64 KB, altrimenti verrà
troncato a 64 KB durante la decodifica.
:::

[comment]: # ({/e66043c4-e66043c4})