2 Vérifications passives et actives de l'agent

Vue d’ensemble

Cette section fournit des informations détaillées sur les vérifications passives et actives effectuées par Zabbix agent et Zabbix agent 2.

Zabbix utilise un protocole de communication basé sur JSON pour communiquer avec les agents.

Les protocoles de Zabbix agent et de Zabbix agent 2 sont unifiés depuis Zabbix 7.0. La différence entre les requêtes/réponses de Zabbix agent et de Zabbix agent 2 est exprimée par la valeur de la balise « variant ».

Vérifications passives

Une vérification passive est une simple demande de données. Le serveur ou le proxy Zabbix demande certaines données (par exemple, la charge du processeur) et l'agent Zabbix renvoie le résultat au serveur.

Les vérifications passives sont exécutées de manière asynchrone : il n'est pas nécessaire de recevoir la réponse à une demande avant de démarrer d'autres vérifications. La résolution DNS est également asynchrone.

Le poller de l'agent tentera de se connecter à toutes les adresses renvoyées par la recherche DNS. Ainsi, si une adresse IP est inaccessible, le poller essaiera l'adresse disponible suivante, ce qui augmente la probabilité d'une connexion réussie. Cette amélioration s'applique au serveur et au proxy Zabbix.

La concurrence maximale des vérifications asynchrones est de 1000 (définie par MaxConcurrentChecksPerPoller).

Le nombre de pollers d'agent asynchrones est défini par le paramètre StartAgentPollers.

Demande du serveur

Pour la définition de l'en-tête et de la longueur des données, consultez les détails du protocole.

{
  "request": "passive checks",
  "data": [
    {
      "key": "agent.version",
      "timeout": 3
    }
  ]
}
Field Type Mandatory Value
request string yes "passive checks"
data array of object yes Élément de vérification passive.
key string yes Clé de l'élément avec les macros développées.
timeout number yes Délai d'expiration de la communication.

Réponse de l'agent

{
  "version": "7.4.0",
  "variant": 2,
  "data": [
    {
      "value": "7.4.0"
    }
  ]
}
Field Type Mandatory Value
version string yes Numéro de version de l'agent.
variant number yes Variante de l'agent (1 - agent Zabbix, 2 - agent Zabbix 2).
data array of object yes Contient le résultat de la vérification.
value string no Valeur de l'élément si la vérification a réussi.
error string no Message d'erreur si la vérification a échoué.

Par exemple, pour les éléments pris en charge :

  1. Le serveur ouvre une connexion TCP
  2. Le serveur envoie <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]}
  3. L'agent lit la demande et répond avec <HEADER><DATALEN>{"version":"7.4.0","variant":2,"data":[{"value":1}]}
  4. Le serveur traite les données pour obtenir la valeur, « 1 » dans notre cas
  5. La connexion TCP est fermée

Pour les éléments non pris en charge :

  1. Le serveur ouvre une connexion TCP
  2. Le serveur envoie <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size[/nono]","timeout":3}]}
  3. L'agent lit la demande et répond avec <HEADER><DATALEN>{"version":"7.4.0","variant":2,"data":[{"error":"Unsupported item key."}]}
  4. Le serveur traite les données et définit l'état de l'élément sur « non pris en charge » avec le message d'erreur spécifié
  5. La connexion TCP est fermée
Basculement vers l'ancien protocole

Pour garantir que le serveur ou le proxy Zabbix puisse fonctionner avec des agents des versions antérieures à la 7.2, qui utilisent un protocole en texte brut, un basculement vers l'ancien protocole est implémenté.

Les vérifications passives sont effectuées à l'aide du protocole JSON (version 7.0 et ultérieure) après un redémarrage ou lorsque la configuration de l'interface est modifiée. Si aucune réponse JSON valide n'est reçue (l'agent a envoyé « ZBX_NOTSUPPORTED »), Zabbix met en cache l'interface comme utilisant l'ancien protocole et réessaie la vérification en envoyant uniquement la clé de l'élément.

Notez que toutes les heures, le serveur/proxy Zabbix essaie à nouveau d'utiliser le nouveau protocole avec toutes les interfaces et revient à l'ancien protocole si nécessaire.

Vérifications actives

Les vérifications actives nécessitent un traitement plus complexe. L'agent doit d'abord récupérer auprès du serveur/proxy une liste d'éléments et/ou de commandes à distance à traiter indépendamment.

Les serveurs/proxy auprès desquels récupérer les vérifications actives sont indiqués dans le paramètre 'ServerActive' du fichier de configuration de l'agent. La fréquence de demande de ces vérifications est définie par le paramètre 'RefreshActiveChecks' dans le même fichier de configuration. Cependant, si l'actualisation des vérifications actives échoue, une nouvelle tentative est effectuée après 60 secondes, valeur codée en dur.

Depuis Zabbix 6.4, l'agent (en mode actif) ne reçoit plus du serveur/proxy une copie complète de la configuration toutes les deux minutes (par défaut). À la place, afin de réduire le trafic réseau et l'utilisation des ressources, une synchronisation incrémentielle de la configuration est effectuée toutes les 5 secondes (par défaut), au cours de laquelle le serveur/proxy fournit une copie complète de la configuration uniquement si l'agent ne l'a pas encore reçue, ou si quelque chose a changé dans la configuration de l'hôte, les macros globales ou les expressions régulières globales.

L'agent envoie ensuite périodiquement les nouvelles valeurs au(x) serveur(s). Si l'agent a reçu des commandes à distance à exécuter, le résultat de leur exécution sera également envoyé. Notez que l'exécution de commandes à distance sur un agent actif est prise en charge depuis Zabbix agent 7.0.

Si un agent se trouve derrière un pare-feu, vous pouvez envisager d'utiliser uniquement les vérifications actives, car dans ce cas, vous n'aurez pas besoin de modifier le pare-feu pour autoriser les connexions entrantes initiales.

Obtention de la liste des éléments

Requête de l'agent

La requête des contrôles actifs est utilisée pour obtenir les contrôles actifs à traiter par l'agent. Cette requête est envoyée par l'agent au démarrage, puis selon les intervalles RefreshActiveChecks.

{
  "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"
}
Champ Type Obligatoire Valeur
request string oui active checks
host string oui Nom de l'hôte.
host_metadata string non Valeur du paramètre de configuration HostMetadata ou de la métrique HostMetadataItem.
interface string non Valeur du paramètre de configuration HostInterface ou de la métrique HostInterfaceItem.
ip string non Première adresse IP du paramètre de configuration ListenIP, si elle est définie.
port number non Valeur du paramètre de configuration ListenPort si elle est définie et différente du port d'écoute par défaut de l'agent.
version string oui Numéro de version de l'agent.
variant number oui Variante de l'agent (1 - agent Zabbix, 2 - agent Zabbix 2).
config_revision number non Identifiant de configuration pour la synchronisation incrémentielle de la configuration.
session string non Identifiant de session pour la synchronisation incrémentielle de la configuration.

Réponse du serveur

La réponse aux contrôles actifs est envoyée par le serveur à l'agent après le traitement de la requête des contrôles actifs.

{
  "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
    }
  ]
}
Champ Type Obligatoire Valeur
response string oui success | failed
info string non Informations sur l'erreur en cas d'échec.
data array of objects non Éléments de contrôle actif. Omis si la configuration de l'hôte n'a pas changé.
key string non Clé de l'élément avec les macros développées.
itemid number non Identifiant de l'élément.
delay string non Intervalle de mise à jour de l'élément.
Les intervalles flexibles et de planification sont pris en charge par l'agent Zabbix et l'agent Zabbix 2 depuis Zabbix 7.0.
lastlogsize number non lastlogsize de l'élément.
mtime number non mtime de l'élément.
timeout string non Délai d'expiration de l'élément.
refresh_unsupported number non Intervalle d'actualisation des éléments non pris en charge.
regexp array of objects non Expressions régulières globales.
name string non Nom de l'expression régulière globale.
expression string non Expression régulière globale.
expression_type number non Type d'expression régulière globale.
exp_delimiter string non Délimiteur de l'expression régulière globale.
case_sensitive number non Paramètre de sensibilité à la casse de l'expression régulière globale.
commands array of objects non Commandes distantes à exécuter. Incluses si l'exécution d'une commande distante a été déclenchée par une opération d'action ou par l'exécution manuelle d'un script. Notez que l'exécution de commandes distantes sur un agent actif est prise en charge depuis Zabbix agent 7.0. Les agents actifs plus anciens ignoreront toutes les commandes distantes incluses dans la réponse du serveur aux contrôles actifs.
command string non Commande distante.
id number non Identifiant de la commande distante.
wait number non Mode d'exécution de la commande distante (« 0 » (nowait) pour les commandes provenant des opérations d'une action ; « 1 » (wait) pour les commandes provenant de l'exécution d'un script manuel).
timeout number non Délai d'expiration de l'exécution de la commande distante dans la configuration du serveur/proxy.
config_revision number non Identifiant de configuration pour la synchronisation incrémentielle de la configuration. Omis si la configuration de l'hôte n'a pas changé. Incrémenté si la configuration de l'hôte est modifiée.

Le serveur doit répondre avec le statut de réussite.

Par exemple :

  1. L'agent ouvre une connexion TCP
  2. L'agent demande la liste des contrôles
  3. Le serveur répond avec une liste d'éléments et de commandes distantes à exécuter
  4. L'agent analyse la réponse
  5. La connexion TCP est fermée
  6. L'agent commence la collecte périodique des données et exécute les commandes distantes (prise en charge depuis Zabbix agent 7.0)

Notez que des données de configuration (sensibles) peuvent devenir accessibles aux parties ayant accès au port trapper du serveur Zabbix lors de l'utilisation d'un contrôle actif. Cela est possible, car n'importe qui peut se faire passer pour un agent actif et demander les données de configuration des éléments ; aucune authentification n'a lieu, sauf si vous utilisez les options de chiffrement.

Envoi des données collectées

L'agent envoie

La requête de données de l'agent contient les valeurs collectées des éléments ainsi que les valeurs des commandes distantes exécutées (le cas échéant).

{
  "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 Valeurs des éléments.
id number yes Identifiant de la valeur (compteur incrémental utilisé pour vérifier les valeurs dupliquées en cas de problèmes réseau).
itemid number yes Identifiant de l'élément.
value string no Valeur de l'élément.
lastlogsize number no lastlogsize de l'élément.
mtime number no mtime de l'élément.
state number no État de l'élément.
source string no Source du journal des événements de la valeur.
eventid number no eventid du journal des événements de la valeur.
severity number no Gravité du journal des événements de la valeur.
timestamp number no timestamp du journal des événements de la valeur.
clock number yes Horodatage de la valeur (secondes depuis l'epoch).
ns number yes Nanosecondes de l'horodatage de la valeur.
commands array of objects no Résultat de l'exécution des commandes distantes. Notez que l'exécution de commandes distantes sur un agent actif est prise en charge depuis Zabbix agent 7.0. Les agents actifs plus anciens ignoreront toutes les commandes distantes incluses dans la réponse du serveur relative aux vérifications actives.
id number no Identifiant de la commande distante.
value string no Résultat de l'exécution de la commande distante si l'exécution a réussi.
error string no Message d'erreur de l'exécution de la commande distante si l'exécution a échoué.
session string yes Identifiant de session unique généré à chaque démarrage de l'agent (32 chiffres hexadécimaux).
host string yes Nom du hôte.
version string yes Numéro de version de l'agent.
variant number yes Variante de l'agent (1 - Zabbix agent, 2 - Zabbix agent 2).

Un ID virtuel est attribué à chaque valeur. L'ID de la valeur est un simple compteur croissant, unique au sein d'une session de données (identifiée par le jeton de session). Cet ID est utilisé pour ignorer les valeurs dupliquées qui pourraient être envoyées dans des environnements où la connectivité est mauvaise.

Réponse du serveur

La réponse aux données de l'agent est envoyée par le serveur à l'agent après le traitement de la requête de données de l'agent.

{
  "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 Résultats du traitement des éléments.

Si l'envoi de certaines valeurs échoue sur le serveur (par exemple, parce que le hôte ou l'élément a été désactivé ou supprimé), l'agent ne réessaiera pas d'envoyer ces valeurs.

Par exemple :

  1. L'agent ouvre une connexion TCP
  2. L'agent envoie une liste de valeurs
  3. Le serveur traite les données et renvoie l'état
  4. La connexion TCP est fermée

Le message d'erreur sera tronqué à 2048 caractères côté serveur.

Message de pulsation

L'agent envoie

Le message de pulsation est envoyé par un agent actif au serveur/proxy Zabbix toutes les HeartbeatFrequency secondes (configurées dans le fichier de configuration de l'agent Zabbix/l'agent 2).

Il est utilisé pour surveiller la disponibilité des vérifications actives.

{
  "request": "active check heartbeat",
  "host": "Zabbix server",
  "heartbeat_freq": 60,
  "version": "7.4.0",
  "variant": 2
}
Champ Type Obligatoire Valeur
request string oui active check heartbeat
host string oui Le nom de l'hôte.
heartbeat_freq number oui La fréquence de pulsation de l'agent (paramètre de configuration HeartbeatFrequency).
version string oui Le numéro de version de l'agent.
variant number oui La variante de l'agent (1 - agent Zabbix, 2 - agent Zabbix 2).

Réponse de redirection

Lorsqu'un hôte a été réaffecté, le serveur peut demander à l'agent de rediriger sa pulsation (ainsi que les vérifications actives suivantes) vers une autre instance de proxy ou de serveur.

  {
    "response": "failed",
    "redirect": {
      "revision": 2,
      "address": "192.0.2.1:10055"
    }
  }
Champ Type Obligatoire Valeur
response string oui success | failed
redirect object oui Instructions de redirection.
revision number oui Identifiant de révision de la configuration.
address string oui Adresse du serveur/proxy cible.

Ancien protocole XML

Zabbix acceptera jusqu'à 16 Mo de données XML encodées en Base64, mais une valeur décodée ne doit pas dépasser 64 Ko ; sinon, elle sera tronquée à 64 Ko lors du décodage.