NGINX Discovery

Este documento describe el uso y configuración del plugin de discovery para NGINX.

Introducción

Este plugin de discovery de NGINX para Pandora FMS está diseñado para automatizar la monitorización de tus servidores NGINX, aprovechando la información que proporciona el módulo ngx_http_stub_status_module (stub_status). Al interactuar con dicho endpoint, el plugin puede recopilar métricas en tiempo real que son cruciales para entender el rendimiento y la salud de tu entorno NGINX, incluyendo conexiones activas, conexiones aceptadas y gestionadas, peticiones procesadas, y el estado de las conexiones en lectura, escritura y espera. Por cada URL de NGINX se creará un agente en Pandora FMS, con un módulo por cada métrica disponible.

Prerrequisitos

Parámetros

Modo simple

--urlsURLs del endpoint stub_status de NGINX, separadas por comas. Cada URL generará un agente.
--usernombre del usuario si el endpoint de NGINX requiere autenticación básica HTTP, opcional
--passwordcontraseña si el endpoint de NGINX requiere autenticación básica HTTP, opcional
--sslpara verificar si la URL tiene certificado HTTPS o no, opcional (por defecto true)
--prefixprefijo para los nombres de los módulos, opcional
--transfer_modemodo de transferencia de datos (native o tentacle), opcional
--tentacle_ipip del tentacle, opcional
--tentacle_portpuerto del tentacle, opcional
--intervalintervalo de monitorización en segundos, opcional
--allow_listexpresión regular para incluir únicamente los módulos cuyo nombre coincida, opcional
--deny_listexpresión regular para excluir módulos cuyo nombre coincida, opcional
--timeouttiempo máximo de espera para la petición HTTP en segundos, opcional (por defecto 10)

Modo avanzado

--confruta del archivo de configuración
--targets_fileruta del archivo con las URLs de NGINX (obligatorio al usar --conf)

Archivo de configuración (--conf)

username= nombre del usuario si el endpoint de NGINX requiere autenticación básica HTTP, opcional
password= contraseña si el endpoint de NGINX requiere autenticación básica HTTP, opcional
verify_ssl= para verificar si la URL tiene certificado HTTPS o no, opcional
prefix= prefijo para los nombres de los módulos, opcional
transfer_mode= modo de transferencia de datos (native o tentacle), opcional
tentacle_ip= ip del tentacle, opcional
tentacle_port= puerto del tentacle, opcional
agents_group= nombre del grupo de agentes al que se asignarán los agentes creados, opcional
agents_group_id= id del grupo de agentes al que se asignarán los agentes creados, opcional
interval= intervalo de monitorización en segundos, opcional
allow_list= expresión regular para incluir únicamente los módulos cuyo nombre coincida, opcional
deny_list= expresión regular para excluir módulos cuyo nombre coincida, opcional
timeout= tiempo máximo de espera para la petición HTTP en segundos, opcional

Ejemplo

[CONF]
username=pandora
password=pandora
verify_ssl=false
prefix=nginx_
transfer_mode=native
tentacle_ip=127.0.0.1
tentacle_port=41121
interval=300
allow_list=
deny_list=
timeout=10

Archivo de targets (--targets_file):

http://192.168.0.10/nginx_status
http://192.168.0.11/nginx_status

Configuración de NGINX

Para que el plugin pueda obtener las estadísticas, NGINX debe exponer el endpoint stub_status. La habilitación se realiza editando el fichero de configuración de NGINX (por defecto en /etc/nginx/nginx.conf o /etc/nginx/sites-available/default).

El módulo ngx_http_stub_status_module no se incluye en todas las compilaciones de NGINX. Para verificar si está disponible, ejecuta nginx -V 2>&1 | grep stub_status. La mayoría de las distribuciones Linux lo incluyen por defecto.

Configuración mínima (sin autenticación, sin SSL)

Añade una location dedicada al estado dentro de tu server:

server {
    listen 80;
    server_name _;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 192.168.1.50;   # IP del servidor de Pandora FMS
        deny all;
    }
}

Con esta configuración el plugin consumirá la URL:

http://<IP_SERVIDOR>/nginx_status

Configuración con autenticación básica

Para proteger el endpoint con usuario y contraseña, define auth_basic y auth_basic_user_file en la location de status:

server {
    listen 80;
    server_name _;

    location /nginx_status {
        stub_status on;
        access_log off;
        auth_basic "NGINX Status";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

Genera el fichero .htpasswd con htpasswd o openssl:

htpasswd -c /etc/nginx/.htpasswd admin
# o bien
openssl passwd -apr1 mypassword > /etc/nginx/.htpasswd

En el plugin se deberá facilitar ese mismo username y password mediante --user / --password (o los campos username / password del archivo de configuración).

Configuración con SSL/TLS

Para servir las estadísticas sobre HTTPS configura el certificado en el server:

server {
    listen 443 ssl;
    server_name _;

    ssl_certificate     /etc/nginx/certs/status.pem;
    ssl_certificate_key /etc/nginx/certs/status.key;

    location /nginx_status {
        stub_status on;
        access_log off;
        allow 192.168.1.50;
        deny all;
    }
}

Genera un certificado autofirmado de pruebas con:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/nginx/certs/status.key \
  -out /etc/nginx/certs/status.crt \
  -subj "/CN=localhost"
cat /etc/nginx/certs/status.crt /etc/nginx/certs/status.key > /etc/nginx/certs/status.pem

En el plugin se indicará la URL con esquema https:// y el parámetro --ssl (o verify_ssl) según se quiera validar el certificado:

Configuración completa (SSL + autenticación)

server {
    listen 443 ssl;
    server_name _;

    ssl_certificate     /etc/nginx/certs/status.pem;
    ssl_certificate_key /etc/nginx/certs/status.key;

    location /nginx_status {
        stub_status on;
        access_log off;
        auth_basic "NGINX Status";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

server {
    listen 80;
    server_name _;
    return 301 https://$host$request_uri;
}

Tras modificar la configuración de NGINX recarga el servicio para aplicar los cambios:

sudo systemctl reload nginx

Verificación

Para comprobar que el endpoint responde correctamente, puedes hacer una petición manual a la página de estado:

curl -u admin:mypassword http://192.168.0.10/nginx_status

La salida debe ser texto plano con el siguiente formato:

Active connections: 291
server accepts handled requests
 16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106

Ejecución manual

El formato de la ejecución del plugin es el siguiente:

./pandora_nginx --urls <urls del endpoint de NGINX separadas por comas> --user <usuario> --password <contraseña> --ssl <true|false> --prefix <prefijo> --transfer_mode <native|tentacle> --tentacle_ip <ip del tentacle> --tentacle_port <puerto del tentacle> --interval <intervalo> --allow_list <regex> --deny_list <regex> --timeout <segundos> --conf <ruta al fichero de configuración> --targets_file <ruta al fichero de URLs>

Ejemplos:

para ejecutar el modo simple

./pandora_nginx --urls http://192.168.0.10/nginx_status,http://192.168.0.11/nginx_status --user admin --password 12345 --ssl false --transfer_mode native --tentacle_ip 127.0.0.1 --tentacle_port 41121

para ejecutar el modo avanzado

./pandora_nginx --conf /etc/pandora/nginx.conf --targets_file /etc/pandora/nginx_targets.conf

La ejecución devolverá una salida en formato JSON con información sobre la ejecución, y generará un fichero XML por cada agente monitorizado (en modo tentacle) que enviará al servidor de Pandora FMS por el método de transferencia indicado en la configuración. En modo native los datos se exponen en el campo monitoring_data del JSON de salida para que los consuma el servidor de Discovery.

Discovery

Este plugin puede integrarse con el Discovery de Pandora FMS.

Para ello se debe cargar el paquete ".disco" que puede descargar desde la librería de Pandora FMS:

https://pandorafms.com/library/

Una vez cargado, se podrán monitorizar las instancias de NGINX creando tareas de Discovery desde la sección Management > Discovery > Application > NGINX

Para cada tarea se solicitarán los siguientes datos mínimos en el paso NGINX Basic:

En el paso NGINX Advanced se podrán configurar opciones adicionales:

Las tareas completadas con éxito tendrán un resumen de ejecución con la siguiente información:

Agentes y módulos generados por el plugin

El plugin creará un agente por cada URL de NGINX indicada. El nombre del agente se calcula aplicando un hash MD5 sobre el netloc de la URL (host:port), y el alias se corresponde con dicho netloc (por ejemplo, 192.168.0.10). En cada agente se incluirán los módulos obtenidos al parsear el texto plano del endpoint stub_status de NGINX.

El módulo Status se crea siempre para cada agente, con valor 1 si el endpoint es alcanzable, indicando que NGINX está funcionando. Si el endpoint no es alcanzable, el plugin reporta el error en la información de ejecución. El resto de campos numéricos se incluyen como módulos generic_data (valores instantáneos) o generic_data_inc (contadores incrementales con cálculo de tasa por segundo), siguiendo el formato <prefix><MetricName>.

Los campos disponibles en el stub_status de NGINX, y que dan lugar a módulos, son:

Status: Estado del endpoint stub_status (1=UP, 0=DOWN) — siempre se monitoriza (generic_proc).
Active_connections: Conexiones activas totales, incluyendo las en espera (generic_data).
Accepts: Conexiones aceptadas acumuladas desde el inicio de NGINX (generic_data_inc, tasa por segundo).
Handled: Conexiones gestionadas acumuladas desde el inicio de NGINX (generic_data_inc, tasa por segundo).
          Si el valor es menor que Accepts, NGINX está descartando tráfico.
Requests: Peticiones de cliente procesadas acumuladas desde el inicio de NGINX (generic_data_inc, tasa por segundo).
Reading: Conexiones leyendo cabeceras de petición del cliente (generic_data).
Writing: Conexiones escribiendo respuesta al cliente o procesando petición (generic_data).
Waiting: Conexiones keep-alive inactivas esperando la siguiente petición (generic_data).

Mapeo de tipos de módulo

Métrica Tipo de módulo Pandora FMS Descripción
Status generic_proc Estado del endpoint (1=reachable, 0=DOWN). Permite configurar alertas críticas cuando el valor es 0.
Active_connections generic_data Conexiones activas actuales (gauge). Incluye conexiones en lectura, escritura y espera.
Accepts generic_data_inc Conexiones aceptadas acumuladas. Pandora FMS calcula la tasa por segundo automáticamente.
Handled generic_data_inc Conexiones gestionadas acumuladas. Pandora FMS calcula la tasa por segundo automáticamente. Si la tasa es menor que la de Accepts, NGINX está descartando conexiones.
Requests generic_data_inc Peticiones procesadas acumuladas. Pandora FMS calcula la tasa por segundo automáticamente (peticiones/s).
Reading generic_data Conexiones en estado de lectura de cabeceras (gauge).
Writing generic_data Conexiones en estado de escritura de respuesta (gauge).
Waiting generic_data Conexiones keep-alive inactivas (gauge). Un valor alto es normal con keep-alive habilitado.

Marcadores extra_data

El plugin asigna identificadores estables en el campo extra_data de cada agente y módulo, siguiendo el formato nginx:<kind>:<identifier>, para permitir su identificación posterior desde la consola, dashboards, extensiones o consultas SQL:

Estos marcadores no contienen ni el nombre del agente ni el del módulo, sino el identificador externo (la URL del target), que es estable y significativo a nivel de dominio.