Parámetros de usuario

Descripción general

Un parámetro de usuario permite definir una clave de item personalizada y el comando utilizado para obtener su valor cuando ningún item integrado del Zabbix agent proporciona los datos necesarios. Un parámetro de usuario es un comando definido por el usuario al que se hace referencia mediante una clave de item definida por el usuario y que el Zabbix agent ejecuta cuando se comprueba el item correspondiente.

En los sistemas UNIX, el agent ejecuta los comandos de los parámetros de usuario mediante /bin/sh, con la cuenta del sistema operativo que ejecuta el agent (normalmente zabbix). Esta cuenta debe tener permisos suficientes para ejecutar el comando y acceder a los archivos, sockets o credenciales que utilice.

Hay dos tipos de parámetros de usuario:

  • Los parámetros de usuario simples no aceptan argumentos; definen una clave de item fija y un comando que se ejecutará.
  • Los parámetros de usuario flexibles aceptan argumentos (especificados como parámetros en la clave de item) y los pasan al comando, lo que permite que una sola definición sirva para varios items.

Configuración de parámetros de usuario

Un parámetro de usuario se define mediante el parámetro de configuración UserParameter.

Un parámetro de usuario tiene la siguiente sintaxis:

UserParameter=<key>,<shell command>

donde:

  • <key>: una clave de item única que identifica el parámetro de usuario.
    Al configurar un item, especifique esta clave para hacer referencia al comando definido por el parámetro de usuario.
    Para un parámetro de usuario simple, la clave es fija y no acepta argumentos. Para un parámetro de usuario flexible, añada [*] a la clave (por ejemplo, mysql.status[*]) para indicar que acepta argumentos. Especifique estos argumentos como parámetros en la clave del item al configurar el item. El comando puede hacer referencia a los parámetros mediante referencias posicionales $1–$9.
  • <shell command>: un comando de shell o una ruta a un script personalizado que el agent ejecuta para obtener el valor del item.
    Para el parámetro de usuario flexible, el comando puede utilizar referencias posicionales $1–$9 para hacer referencia a los parámetros correspondientes de la clave del item (por ejemplo, UserParameter=mysql.status[*],mysqladmin status --user=$1 --password=$2). Zabbix analiza los parámetros incluidos entre [] en la clave del item (es decir, mysql.status[zabbix,{$MYSQL.PASSWORD}]) y sustituye las referencias posicionales del comando según corresponda.
    $0 se sustituye por el comando original antes de expandir las referencias posicionales. Las referencias posicionales se interpretan independientemente de si están incluidas entre comillas dobles (") o simples ('). Para utilizar referencias posicionales sin sustitución, especifique un signo de dólar doble. Por ejemplo, awk '{print $$2}' pasa $2 al comando sin cambios.
    Tenga en cuenta que el agent de Zabbix busca y sustituye las referencias posicionales precedidas por $ únicamente en los parámetros de usuario flexibles. En los parámetros de usuario simples, las referencias posicionales no se procesan, por lo que no es necesario escapar $.

De forma predeterminada, ciertos caracteres no se pueden pasar como argumentos. Para consultar la lista completa de caracteres, consulte UnsafeUserParameters.

UserParameter debe configurarse en cada agent de Zabbix que lo utilice:

Se puede definir más de un UserParameter por agent, ya que se pueden incluir varios archivos con diferentes conjuntos de parámetros. Cada parámetro de usuario debe tener una clave de item única dentro del host supervisado.

El parámetro de configuración UserParameterDir permite especificar el directorio de trabajo para ejecutar comandos UserParameter. Si está configurado, el agent cambia su directorio de trabajo al directorio especificado antes de ejecutar un comando. Los comandos se pueden especificar mediante una ruta relativa con el prefijo ./, por ejemplo, UserParameter=mykey,./myscript.sh.

Para configurar un parámetro de usuario:

  1. Escriba un script personalizado o un comando para recuperar los datos necesarios.
  2. Añada el comando y su clave de item única al parámetro de configuración UserParameter en el archivo de configuración del agent de Zabbix (zabbix_agentd.conf).
  3. Recargue los parámetros de usuario desde el archivo de configuración ejecutando el comando de control en tiempo de ejecución:

    zabbix_agentd -R userparameter_reload

    Como alternativa, reinicie el agent para aplicar los cambios de configuración.

  4. Cree un item nuevo en el host supervisado con la clave del item definida en UserParameter.
    Establezca el tipo del item como Zabbix Agent o Zabbix Agent (active).
    Asegúrese de que el Type of information del item esté configurado correctamente; de lo contrario, Zabbix rechazará el valor devuelto.

Consulte Extending Zabbix agents para ver un ejemplo de configuración y uso de parámetros de usuario.

Los parámetros de usuario están sujetos al tiempo de espera de las comprobaciones del agent de Zabbix. Si se alcanza el tiempo de espera, se termina el proceso que ejecuta el parámetro de usuario. Consulte Command execution para obtener más información.

Tenga en cuenta que los scripts de larga duración pueden consumir recursos del sistema y retrasar otras comprobaciones.

Resultado del comando

El valor de retorno del comando consta de la salida estándar y el error estándar generados por el comando.

Los parámetros de usuario que devuelven texto (el tipo de información Character, Log o Text) también pueden devolver espacios en blanco. Si el comando produce un resultado no válido, el item pasa a no ser compatible. Sin embargo, un item con uno de estos tipos de información no pasará a ser no compatible únicamente porque el comando produzca una salida en el error estándar.

El valor de retorno del comando está limitado a 16 MB, incluidos los espacios en blanco finales, que se truncan. Este límite se aplica antes de los pasos de preprocesamiento del valor del item. También se aplican los límites de la base de datos.

Ejemplos de parámetros de usuario

Esta sección proporciona ejemplos de parámetros de usuario simples y flexibles.

Los ejemplos siguientes son solo para fines demostrativos y no deben utilizarse en producción sin las medidas de protección adecuadas. Los parámetros de usuario flexibles definidos mediante [*] aceptan argumentos que pueden introducir riesgos de inyección de comandos si no se gestionan de forma segura.

Ejemplos de parámetros de usuario simples

Ejemplo 1: Valor constante

UserParameter=ping,echo 1

Un item con la clave ping siempre devuelve 1.

Ejemplo 2: Disponibilidad del server MySQL

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

Devuelve 1 si el server MySQL responde y 0 en caso contrario. La redirección 2>/dev/null descarta la salida de error estándar de mysqladmin. Sin ella, podría devolverse un mensaje de error junto con 0, lo que haría que un item con el tipo de información Numeric dejara de estar soportado (consulte Resultado del comando).
Este ejemplo supone que las credenciales de conexión de MySQL están configuradas para la cuenta del sistema operativo que ejecuta el Zabbix agent, por ejemplo, en un archivo de opciones de MySQL accesible para dicha cuenta.

Ejemplos de parámetros de usuario flexibles

Ejemplo 1: Devolver un parámetro

UserParameter=ping[*],echo $1

Puede definir varios items utilizando este parámetro de usuario, con claves en el formato ping[parameter]:

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

Ejemplo 2: disponibilidad de MySQL en un host especificado

Este parámetro se puede utilizar para supervisar la disponibilidad de un server MySQL en un host especificado.

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

El item con la clave mysql.ping[db1.example.com] devuelve 1 si el server MySQL de ese host responde y 0 en caso contrario.
Este ejemplo supone que las credenciales de conexión de MySQL están configuradas para la cuenta del sistema operativo que ejecuta el agent de Zabbix, por ejemplo, en un archivo de opciones de MySQL accesible para esa cuenta.

Ejemplo 3: Contar las líneas que coinciden con un patrón

Este parámetro se puede utilizar para contar el número de líneas de un archivo.

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

Devuelve el número de líneas del archivo especificado por el primer argumento que coinciden con la expresión regular especificada por el segundo argumento. Por ejemplo, grep.count[/etc/passwd,root] devuelve el número de líneas de /etc/passwd que coinciden con la expresión regular root.