2 Vérifications passives et actives de l'agent

Aperçu

Cette section fournit des détails sur les contrôles passifs et actifs effectués 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 requête de données. Le serveur Zabbix ou le proxy demande certaines données (par exemple, la charge CPU) 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 requête avant que d'autres vérifications ne soient lancées. La résolution DNS est également asynchrone.

Le collecteur de l'agent tentera de se connecter à toutes les adresses renvoyées par la recherche DNS. Cela garantit que si une adresse IP est inaccessible, le collecteur essaiera l'adresse disponible suivante, augmentant ainsi la probabilité d'une connexion réussie. Cette amélioration s'applique à la fois au serveur Zabbix et au proxy.

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

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

Requête du serveur

Pour la définition de l'en-tête et de la longueur des données, veuillez vous référer aux 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 macros développées.
timeout number yes Délai d'attente de communication.

Réponse de l'agent

{
  "version": "7.0.0",
  "variant": 2,
  "data": [
    {
      "value": "7.0.0"
    }
  ]
}
Field Type Mandatory Value
version string yes Le numéro de version de l'agent.
variant number yes La variante de l'agent (1 - Zabbix agent, 2 - Zabbix agent 2).
data array of object yes Contient le résultat de la vérification.
value string no La valeur de l'élément si la vérification a réussi.
error string no Le 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 requête et répond avec <HEADER><DATALEN>{"version":"7.0.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 requête et répond avec <HEADER><DATALEN>{"version":"7.0.0","variant":2,"data":[{"error":"Unsupported item key."}]}
  4. Le serveur traite les données, change l'état de l'élément en 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 Zabbix ou le proxy puisse fonctionner avec des agents des versions antérieures à 7.0, qui utilisent le 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 (7.0 et versions ultérieures) après le 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 mettra en cache l'interface comme utilisant l'ancien protocole et réessaiera la vérification en envoyant uniquement la clé de l'élément.

Notez que chaque heure, le serveur/proxy Zabbix tentera à nouveau de fonctionner avec le nouveau protocole pour toutes les interfaces, en revenant à 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 distantes pour un traitement indépendant.

Les serveurs/proxys à partir desquels obtenir les vérifications actives sont indiqués dans le paramètre 'ServerActive' du fichier de configuration de l'agent. La fréquence d'interrogation pour 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 codées 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 distantes à exécuter, le résultat de l'exécution sera également envoyé. Notez que l'exécution de commandes distantes sur un agent actif est prise en charge depuis Zabbix agent 7.0.

Si un agent se trouve derrière le pare-feu, vous pouvez envisager d'utiliser uniquement des contrôles actifs, car dans ce cas vous n'auriez 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 de vérifications actives est utilisée pour obtenir les vérifications actives à traiter par l'agent.
Cette requête est envoyée par l'agent au démarrage, puis à intervalles définis par RefreshActiveChecks.

{
  "request": "active checks",
  "host": "Zabbix server",
  "host_metadata": "mysql,nginx",
  "interface": "zabbix.server.lan",
  "ip": "159.168.1.1",
  "port": 12050,
  "version": "7.0.0",
  "variant": 2,
  "config_revision": 1,
  "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
}
Field Type Mandatory Value
request string yes active checks
host string yes Nom de l'hôte.
host_metadata string no Le paramètre de configuration HostMetadata ou la valeur de l'élément de surveillance HostMetadataItem.
interface string no Le paramètre de configuration HostInterface ou la valeur de l'élément de surveillance HostInterfaceItem.
ip string no La première adresse IP du paramètre de configuration ListenIP, si défini.
port number no La valeur du paramètre de configuration ListenPort, si définie et différente du port d'écoute par défaut de l'agent.
version string yes Le numéro de version de l'agent.
variant number yes La variante de l'agent (1 - Zabbix agent, 2 - Zabbix agent 2).
config_revision number no Identifiant de configuration pour la synchronisation incrémentielle de la configuration.
session string no Identifiant de session pour la synchronisation incrémentielle de la configuration.

Réponse du serveur

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

{
  "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 Informations sur l'erreur en cas d'échec.
data array of objects no Éléments de vérification active. Omis si la configuration de l'hôte est inchangée.
key string no Clé de l'élément avec macros développées.
itemid number no Identifiant de l'élément.
delay string no Intervalle de mise à jour de l'élément.
Les intervalles flexibles/de planification sont pris en charge par Zabbix agent et Zabbix agent 2 depuis Zabbix 7.0.
lastlogsize number no lastlogsize de l'élément.
mtime number no mtime de l'élément.
timeout string no Délai d'expiration de l'élément.
refresh_unsupported number no Intervalle d'actualisation des éléments non pris en charge.
regexp array of objects no Expressions régulières globales.
name string no Nom de l'expression régulière globale.
expression string no Expression régulière globale.
expression_type number no Type d'expression régulière globale.
exp_delimiter string no Délimiteur de l'expression régulière globale.
case_sensitive number no Paramètre de sensibilité à la casse de l'expression régulière globale.
commands array of objects no Commandes distantes à exécuter. Incluses si l'exécution de commandes distantes 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 anciens agents actifs ignoreront toute commande distante incluse dans la réponse du serveur aux vérifications actives.
command string no Commande distante.
id number no Identifiant de la commande distante.
wait number no Mode d'exécution de la commande distante ("0" (nowait) pour les commandes provenant des opérations d'action ; "1" (wait) pour les commandes provenant de l'exécution manuelle d'un script).
timeout number no Délai d'expiration de l'exécution de la commande distante dans la configuration du serveur/proxy.
config_revision number no Identifiant de configuration pour la synchronisation incrémentielle de la configuration. Omis si la configuration de l'hôte est inchangée. Incrémenté si la configuration de l'hôte est modifiée.

Le serveur doit répondre par success.

Par exemple :

  1. L'agent ouvre une connexion TCP
  2. L'agent demande la liste des vérifications
  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 démarre la collecte périodique des données et exécute les commandes distantes (pris en charge depuis Zabbix agent 7.0)

Notez que des données de configuration (sensibles) peuvent devenir accessibles à des tiers ayant accès au port trapper du serveur Zabbix lors de l'utilisation d'une vérification active. 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 ; l'authentification n'a pas lieu, sauf si vous utilisez des options de chiffrement.

Envoi des données collectées

L'agent envoie

La requête de données de l'agent contient les valeurs des éléments collectées et 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.0.0",
  "variant": 2
}
Field < Type Mandatory Value
request < string yes agent data
data < array of objects yes Valeurs des éléments.
id < number yes L'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 L'identifiant de l'élément.
^ value < string no La valeur de l'élément.
^ lastlogsize < number no Le lastlogsize de l'élément.
^ mtime < number no Le mtime de l'élément.
^ state < number no L'état de l'élément.
^ source < string no La source du journal d'événements de la valeur.
^ eventid < number no L'eventid du journal d'événements de la valeur.
^ severity < number no La severity du journal d'événements de la valeur.
^ timestamp < number no L'horodatage du journal d'événements de la valeur.
^ clock < number yes L'horodatage de la valeur (secondes depuis l'Epoch).
^ ns < number yes L'horodatage de la valeur en nanosecondes.
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 anciens agents actifs ignoreront toutes les commandes distantes incluses dans la réponse du serveur 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.
host < string yes Nom d'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 identifiant virtuel est attribué à chaque valeur. L'identifiant de valeur est un simple compteur croissant, unique au sein d'une session de données (identifiée par le jeton de session). Cet identifiant est utilisé pour ignorer les valeurs dupliquées qui peuvent être envoyées dans des environnements où la connectivité est médiocre.

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 l'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 symboles côté serveur.

Message de heartbeat

L'agent envoie

Le message de heartbeat est envoyé par un agent actif au serveur/proxy Zabbix toutes les HeartbeatFrequency secondes (configuré dans le fichier de configuration Zabbix agent/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.0.0",
  "variant": 2
}
Field Type Mandatory Value
request string yes active check heartbeat
host string yes Le nom de l'hôte.
heartbeat_freq number yes La fréquence de heartbeat de l'agent (paramètre de configuration HeartbeatFrequency).
version string yes Le numéro de version de l'agent.
variant number yes La variante de l'agent (1 - Zabbix agent, 2 - Zabbix agent 2).

Réponse de redirection

Lorsqu'un hôte a été réaffecté, le serveur peut demander à l'agent de rediriger son heartbeat (et 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"
    }
  }
Field Type Mandatory Value
response string yes success | failed
redirect object yes Instructions de redirection.
revision number yes Identifiant de révision de la configuration.
address string yes Adresse cible du serveur/proxy.

Ancien protocole XML

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