Paramètres utilisateur

Présentation générale

Un paramètre utilisateur vous permet de définir une clé d'élément personnalisée et la commande utilisée pour récupérer sa valeur lorsqu'aucun élément intégré de l'agent Zabbix ne fournit les données dont vous avez besoin. Un paramètre utilisateur est une commande définie par l'utilisateur, référencée par une clé d'élément définie par l'utilisateur, et exécutée par l'agent Zabbix lors de la vérification de l'élément correspondant.

Sur les systèmes UNIX, l'agent exécute les commandes des paramètres utilisateur à l'aide de /bin/sh, sous le compte du système d'exploitation qui exécute l'agent (généralement zabbix). Ce compte doit disposer des autorisations suffisantes pour exécuter la commande et accéder aux fichiers, sockets ou identifiants qu'elle utilise.

Il existe deux types de paramètres utilisateur :

  • Les paramètres utilisateur simples n'acceptent pas d'arguments ; ils définissent une clé d'élément fixe et une commande à exécuter.
  • Les paramètres utilisateur flexibles acceptent des arguments (spécifiés comme paramètres dans la clé d'élément) et les transmettent à la commande, ce qui permet à une seule définition de servir pour plusieurs éléments.

Configuration des paramètres utilisateur

Un paramètre utilisateur est défini à l'aide du paramètre de configuration UserParameter.

Un paramètre utilisateur utilise la syntaxe suivante :

UserParameter=<key>,<shell command>

où :

  • <key> - une clé d'élément unique qui identifie le paramètre utilisateur.
    Lors de la configuration d'un élément, indiquez cette clé pour référencer la commande définie par le paramètre utilisateur.
    Pour un paramètre utilisateur simple, la clé est fixe et n'accepte pas d'arguments. Pour un paramètre utilisateur flexible, ajoutez [*] à la clé (par exemple, mysql.status[*]) pour indiquer qu'elle accepte des arguments. Indiquez ces arguments comme paramètres dans la clé de l'élément lors de la configuration de l'élément. La commande peut faire référence aux paramètres à l'aide des références positionnelles $1–$9.
  • <shell command> - une commande shell ou un chemin vers un script personnalisé que l'agent exécute pour obtenir la valeur de l'élément.
    Pour le paramètre utilisateur flexible, la commande peut utiliser les références positionnelles $1–$9 pour faire référence aux paramètres correspondants dans la clé de l'élément (par exemple, UserParameter=mysql.status[*],mysqladmin status --user=$1 --password=$2). Zabbix analyse les paramètres placés entre [] dans la clé de l'élément (c'est-à-dire mysql.status[zabbix,{$MYSQL.PASSWORD}]) et remplace les références positionnelles dans la commande en conséquence.
    $0 est remplacé par la commande d'origine avant l'expansion des références positionnelles. Les références positionnelles sont interprétées, qu'elles soient placées entre guillemets doubles (") ou simples ('). Pour utiliser des références positionnelles sans substitution, indiquez un double signe dollar. Par exemple, awk '{print $$2}' transmet $2 à la commande sans modification.
    Notez que les références positionnelles précédées de $ sont recherchées et remplacées par l'agent Zabbix uniquement dans les paramètres utilisateur flexibles. Pour les paramètres utilisateur simples, les références positionnelles ne sont pas traitées ; il n'est donc pas nécessaire d'échapper $.

Certains caractères ne peuvent pas être transmis comme arguments par défaut. Pour obtenir la liste complète des caractères, consultez UnsafeUserParameters.

UserParameter doit être configuré sur chaque agent Zabbix qui l'utilise :

  • Directement dans le fichier de configuration de l'agent Zabbix (zabbix_agentd.conf ou zabbix_agent2.conf).
  • Dans un fichier *.conf distinct, à condition que le fichier soit inclus par la configuration de l'agent.

Plusieurs UserParameter peuvent être définis par agent, car plusieurs fichiers peuvent être inclus avec différents ensembles de paramètres. Chaque paramètre utilisateur doit avoir une clé d'élément unique au sein de l'hôte surveillé.

Le paramètre de configuration UserParameterDir permet de spécifier le répertoire de travail pour l'exécution des commandes UserParameter. S'il est configuré, l'agent modifie son répertoire de travail pour utiliser le répertoire spécifié avant d'exécuter une commande. Les commandes peuvent être spécifiées à l'aide d'un chemin relatif avec le préfixe ./, par exemple, UserParameter=mykey,./myscript.sh.

Pour configurer un paramètre utilisateur :

  1. Écrivez un script ou une commande personnalisé(e) pour récupérer les données requises.
  2. Ajoutez la commande et sa clé d'élément unique au paramètre de configuration UserParameter dans le fichier de configuration de l'agent Zabbix (zabbix_agentd.conf).

  3. Rechargez les paramètres utilisateur depuis le fichier de configuration en exécutant la commande de contrôle à l'exécution :

    zabbix_agentd -R userparameter_reload

    Vous pouvez également redémarrer l'agent pour appliquer les modifications de configuration.

  4. Créez un nouvel élément sur l'hôte surveillé avec la clé d'élément définie dans UserParameter.
    Définissez le type de l'élément sur Zabbix Agent ou Zabbix Agent (active).
    Assurez-vous que le Type d'information de l'élément est configuré correctement ; sinon, Zabbix rejettera la valeur renvoyée.

Consultez Extension des agents Zabbix pour obtenir un exemple de configuration et d'utilisation des paramètres utilisateur.

Les paramètres utilisateur sont soumis au délai d'expiration des contrôles de l'agent Zabbix. Si le délai d'expiration est atteint, le processus qui exécute le paramètre utilisateur est arrêté. Consultez Exécution des commandes pour plus d'informations.

Notez que les scripts de longue durée peuvent consommer des ressources système et retarder d'autres contrôles.

Résultat de la commande

La valeur de retour de la commande se compose de la sortie standard et de l'erreur standard produites par la commande.

Les paramètres utilisateur qui renvoient du texte (type d'information Caractère, Journal ou Texte) peuvent également renvoyer des espaces. Si la commande produit un résultat non valide, l'élément devient non pris en charge. Cependant, un élément utilisant l'un de ces types d'information ne devient pas non pris en charge uniquement parce que la commande produit une sortie sur l'erreur standard.

La valeur de retour de la commande est limitée à 16 Mo, espaces de fin compris, qui sont tronqués. Cette limite s'applique avant les étapes de prétraitement de la valeur de l'élément. Les limites de la base de données s'appliquent également.

Exemples de paramètres utilisateur

Cette section fournit des exemples de paramètres utilisateur simples et flexibles.

Les exemples ci-dessous sont fournis uniquement à des fins de démonstration et ne doivent pas être utilisés en production sans mesures de protection appropriées. Les paramètres utilisateur flexibles définis à l'aide de [*] acceptent des arguments qui peuvent introduire des risques d'injection de commandes s'ils ne sont pas traités de manière sécurisée.

Exemples de paramètres utilisateur simples

Exemple 1 : Valeur constante

UserParameter=ping,echo 1

Un élément avec la clé ping renvoie toujours 1.

Exemple 2 : Disponibilité du serveur MySQL

UserParameter=mysql.ping,mysqladmin ping 2>/dev/null | grep -c alive

Renvoie 1 si le serveur MySQL répond et 0 dans le cas contraire. La redirection 2>/dev/null ignore la sortie d'erreur standard de mysqladmin. Sans cette redirection, un message d'erreur pourrait être renvoyé avec 0, ce qui rendrait non pris en charge un élément dont le type d'information est Numérique (voir Résultat de la commande).
Cet exemple suppose que les identifiants de connexion MySQL sont configurés pour le compte du système d'exploitation qui exécute l'agent Zabbix, par exemple dans un fichier d'options MySQL accessible à ce compte.

Exemples de paramètres utilisateur flexibles

Exemple 1 : Retourner un paramètre

UserParameter=ping[*],echo $1

Vous pouvez définir plusieurs éléments à l’aide de ce paramètre utilisateur, avec des clés au format ping[parameter] :

  • ping[0] - renvoie 0.
  • ping[hello] - renvoie hello.

Exemple 2 : disponibilité de MySQL sur un hôte spécifié

Ce paramètre peut être utilisé pour surveiller la disponibilité d'un serveur MySQL sur un hôte spécifié.

UserParameter=mysql.ping[*],mysqladmin -h "$1" ping 2>/dev/null | grep -c alive

L'élément avec la clé mysql.ping[db1.example.com] renvoie 1 si le serveur MySQL sur cet hôte répond, et 0 dans le cas contraire.
Cet exemple suppose que les identifiants de connexion MySQL sont configurés pour le compte du système d'exploitation exécutant l'agent Zabbix, par exemple dans un fichier d'options MySQL accessible à ce compte.

Exemple 3 : Compter les lignes correspondant à un motif

Ce paramètre peut être utilisé pour compter le nombre de lignes dans un fichier.

UserParameter=grep.count[*],grep -c "$2" "$1"

Renvoie le nombre de lignes du fichier spécifié par le premier argument qui correspondent à l'expression régulière spécifiée par le deuxième argument. Par exemple, grep.count[/etc/passwd,root] renvoie le nombre de lignes dans /etc/passwd qui correspondent à l'expression régulière root.