Compilación de módulos dinámicos de terceros para NGINX y NGINX Plus

Owen GarrettDirector sénior de Gestión de Producto

Editor – La entrada del blog que anunciaba el lanzamiento original de la compatibilidad con módulos dinámicos (en NGINX Open Source 1.9.11, febrero de 2016) redirige aquí. El proceso de compilación descrito en esa entrada está obsoleto.

Esta entrada forma parte de una serie de dos partes sobre el uso de módulos dinámicos de terceros con NGINX Open Source y NGINX Plus.

• Este artículo proporciona instrucciones paso a paso para compilar módulos dinámicos de terceros que NGINX Open Source o NGINX Plus pueden cargar en tiempo de ejecución.
• La segunda publicación ofrece orientación y herramientas para automatizar la compilación de módulos dinámicos de terceros para un entorno de producción. Explica cómo crear paquetes instalables para módulos dinámicos de terceros que incluyan la comprobación de dependencias de versión.

NGINX Open Source 1.11.5 y NGINX Plus versión R11 introdujeron la compatibilidad binaria para los módulos dinámicos. En este artículo se explica cómo compilar módulos de terceros para usarlos con NGINX Open Source y NGINX Plus en un entorno de desarrollo. Para obtener instrucciones sobre cómo compilar, implementar y actualizar módulos dinámicos de terceros en un entorno de producción, consulte Creación de paquetes instalables para módulos dinámicos.

En aras de la brevedad, en el resto de este artículo se hará referencia únicamente a NGINX Plus, salvo cuando sea pertinente señalar las diferencias entre este y NGINX Open Source. A menos que se indique lo contrario, todas las afirmaciones sobre NGINX Plus también se aplican a NGINX Open Source.

Descripción general de los módulos dinámicos

Los módulos que se pueden cargar en NGINX Plus están escritos en C y se ajustan a la API descrita en Ampliación de NGINX en la wiki de NGINX. Existe un amplio ecosistema de módulos de terceros, que abarca desde intérpretes de lenguajes hasta soluciones de seguridad, y algunos de ellos están incluidos y cuentan con soporte en NGINX Plus.

Otros módulos de terceros, así como los módulos que haya creado usted mismo, deben compilarse de forma independiente y cargarse dinámicamente en NGINX Plus durante la ejecución. Puede compilar estos módulos para utilizarlos con NGINX Plus compilándolos con NGINX Open Source, tal como se muestra en los dos ejemplos siguientes:

1. Obtenga la versión correspondiente de NGINX Open Source
2. Obtenga el código fuente del módulo y modifique el archivo config del módulo si es necesario
3. Compile el módulo dinámico con la versión de NGINX Open Source, utilizando el argumento --with-compat en el comando configure command
4. Cargue el módulo dinámico resultante (el archivo .so) en NGINX Plus y utilícelo como si fuera un módulo integrado

Ejemplo: un módulo sencillo «Hola, mundo»

Este ejemplo utiliza un sencillo módulo «Hola, mundo» para mostrar cómo actualizar el código fuente de un módulo y cargarlo en NGINX Plus. El módulo «Hola, mundo» implementa una directiva sencilla (hello_world) que responde a las solicitudes con un mensaje sencillo.

Paso 1: Obtenga la versión de NGINX Open Source

1. Determine la versión de NGINX Open Source que corresponde a su instalación de NGINX Plus. En este ejemplo, es NGINX 1.11.5.

$ nginx -vnginx version: nginx/1.11.5 (nginx-plus-r11)

1. Descargue el paquete de NGINX Open Source correspondiente en nginx.org/download:

$ wget https://nginx.org/download/nginx-1.11.5.tar.gz$ tar -xzvf nginx-1.11.5.tar.gz

Paso 2: Obtenga el código fuente del módulo

1. Obtenga el código fuente del módulo «Hello World» de NGINX desde GitHub:

$ git clone https://github.com/perusio/nginx-hello-world-module.git

1. El archivo de shell config de un módulo define cómo se compila, y su formato es diferente para los módulos dinámicos que para los módulos que se compilan estáticamente en un binario de NGINX Open Source. Modifique el archivo nginx-hello-world-module/config para que contenga lo siguiente:

ngx_addon_name=ngx_http_hello_world_module

if test -n "$ngx_module_link"; then
    ngx_module_type=HTTP
    ngx_module_name=ngx_http_hello_world_module
    ngx_module_srcs="$ngx_addon_dir/ngx_http_hello_world_module.c"

    . auto/module
else
    HTTP_MODULES="$HTTP_MODULES ngx_http_hello_world_module"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_world_module.c"
fi

Para obtener información detallada sobre la compilación de módulos dinámicos, incluidas las instrucciones para actualizar el archivo config de un módulo desde el formato antiguo, consulte la wiki de NGINX.

Paso 3: Compilar el módulo dinámico

1. Compile the module by first running the configure script with the --with-compat argument, which creates a standard build environment supported by both NGINX Open Source and NGINX Plus. Then run make modules to build the module:

$ cd nginx-1.11.5/$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module
$ make modules

1. Copie la biblioteca del módulo (.so) en /etc/nginx/modules:

$ sudo cp objs/ngx_http_hello_world_module.so /etc/nginx/modules/

Paso 4: Cargar y usar el módulo

1. Para cargar el módulo en NGINX Plus, añada la directiva load_module en el contexto de nivel superior (principal) de su archivo de configuración nginx.conf (no dentro del contexto http ni stream):

load_module modules/ngx_http_hello_world_module.so;

1. En el contexto http, añada un bloque location con la directiva hello_world proporcionada por el módulo Hello World. Las solicitudes a la ubicación devuelven la respuesta hello world.

server {
    listen 80;

    location / {
         hello_world;
    }
}

1. Vuelva a cargar la configuración de NGINX Plus y pruébela con una solicitud sencilla:

$ nginx -s reload$ curl http://localhost/
hello world

Ejemplo: el firewall de aplicaciones web NAXSI

NAXSI es un cortafuegos de aplicaciones web (WAF) fácil de usar y de alto rendimiento que utiliza métodos heurísticos y un sistema de puntuación para identificar solicitudes sospechosas, como ataques XSS y de inyección SQL.

El código fuente de NAXSI se ha actualizado para adaptarse al nuevo formato del archivo de shell config, por lo que compilar un módulo dinámico para NGINX Plus es sencillo. El proceso se basa en las instrucciones de instalación de NAXSI:

$ git clone https://github.com/nbs-system/naxsi.git$ cd nginx-1.11.5/
$ ./configure --with-compat --add-dynamic-module=../naxsi/naxsi_src
$ make modules
$ sudo cp objs/ngx_http_naxsi_module.so /etc/nginx/modules

Cargue el módulo en el núcleo de NGINX Plus añadiendo la directiva load_module al contexto principal de su archivo nginx.conf:

load_module modules/ngx_http_naxsi_module.so;

La configuración de NAXSI se describe detalladamente en la documentación del proyecto. La siguiente configuración de NGINX muestra el módulo en funcionamiento:

# Edit this 'include' directive to point to your naxsi_core.rules file
include /home/owen/src/naxsi/naxsi_config/naxsi_core.rules;

server {
    listen 80;

    location / {
        root /usr/share/nginx/html;

        # Enable NAXSI
        SecRulesEnabled;

        # Define where blocked requests go
        DeniedUrl "/50x.html";

        # CheckRules, determining when NAXSI needs to take action
        CheckRule "$SQL >= 8" BLOCK;
        CheckRule "$RFI >= 8" BLOCK;
        CheckRule "$TRAVERSAL >= 4" BLOCK;
        CheckRule "$EVADE >= 4" BLOCK;
        CheckRule "$XSS >= 8" BLOCK;

        # Don’t forget the error_log, where blocked requests are logged
        error_log /tmp/naxsi.log;
    }

    error_page   500 502 503 504  /50x.html;
}

Puedes comprobar que NAXSI funciona correctamente mediante un par de solicitudes HTTP sencillas:

• curl http://localhost/ devuelve la página de índice estándar de NGINX Plus almacenada en /usr/share/nginx/html.
• curl "http://localhost/?a=<>" activa la detección de XSS de NAXSI y bloquea la solicitud, devolviendo la página de error estándar 50x.html de /usr/share/nginx/html. También registra un mensaje en error_log.

Para implementaciones en producción, también puede descargar versiones firmadas de NAXSI desde https://github.com/nbs-system/naxsi/tags y compilarlas de forma similar.

Cómo ofrecemos compatibilidad con módulos dinámicos en NGINX Plus

Nota: La información de esta sección se aplica únicamente a NGINX Plus. El conjunto de módulos dinámicos incluido en los paquetes precompilados de NGINX Open Source puede diferir del incluido en NGINX Plus. Los módulos dinámicos utilizados con NGINX Open Source reciben soporte del mismo modo que el código fuente y los archivos binarios precompilados de NGINX.

NGINX Plus incluye varios módulos dinámicos que también puede descargar directamente desde nuestro repositorio de módulos. Para consultar la lista, visite la página Módulos dinámicos. Estos módulos son de dos tipos:

• Módulos de NGINX Plus están desarrollados o mantenidos por el equipo de ingeniería de NGINX. No se incluyen en NGINX Plus por motivos técnicos (por ejemplo, porque tienen dependencias adicionales) o porque se encuentran en fase preliminar. Los módulos en fase preliminar están en desarrollo activo y solo deben implementarse con mucha precaución. Por lo demás, los módulos de NGINX Plus cuentan con soporte completo de NGINX. Para ver una lista, filtre por el autor NGINX en la página Módulos dinámicos.
• Módulos de la comunidad certificados para NGINX Plus son módulos populares de terceros que NGINX prueba y distribuye, y para los que ofrecemos asistencia con la instalación y la configuración básica. Garantizamos que estos módulos no interfieren con el correcto funcionamiento de NGINX Plus y los actualizamos según sea necesario con cada versión de NGINX Plus o cuando se publica una actualización de seguridad. Para ver una lista, filtre por autor Comunidad en la página Módulos dinámicos.

Además, NGINX certifica módulos de proveedores comerciales que participan en nuestro programa de módulos certificados de NGINX Plus. Estos módulos son distribuidos y cuentan con el soporte de sus respectivos proveedores. Para ver una lista, filtre por autor Socio certificado en la página Módulos dinámicos.

NGINX no prueba ni ofrece soporte para los módulos que compile usted mismo (otros módulos de la comunidad, módulos proporcionados por proveedores externos que no forman parte del programa NGINX Plus Certified Modules y módulos personalizados). Si solicita asistencia técnica para un problema, el equipo de soporte de NGINX puede pedirle que elimine un módulo no compatible y reproduzca el fallo como parte de nuestro proceso de asistencia técnica, a fin de comprobar si el fallo se debe o no al módulo no compatible.

Resumen

El proceso de compilación de módulos dinámicos para NGINX Plus le permite aprovechar el amplio ecosistema de módulos de NGINX Open Source y ejecutarlos sobre el completo núcleo de NGINX Plus, que cuenta con soporte integral.

Si actualmente utiliza NGINX Open Source con extensiones de terceros, lo más probable es que estas extensiones se puedan compilar y cargar en NGINX Plus.

Si desarrolla módulos comerciales o comunitarios, el nuevo proceso de compilación permite a sus usuarios implementar sus módulos con NGINX Plus. Para obtener información sobre cómo certificar un módulo comercial, consulte Módulos certificados de NGINX Plus.

Si necesita ayuda para desarrollar un módulo o actualizar su archivo de shell config, consulte los siguientes recursos:

• Guía de Emiller para el desarrollo de módulos de NGINX de Evan Miller
• Desarrollo de módulos dinámicos por Ruslan Ermilov, desarrollador de NGINX
• Ampliación de NGINX en la wiki de NGINX
• Conversión de módulos estáticos en módulos dinámicos en la wiki de NGINX
• Tutorial de NGINX: desarrollo de módulos de Aaron Bedra
• Creación de paquetes instalables para módulos dinámicos en nuestro blog

La lista de correo de desarrolladores de NGINX es el principal punto de referencia para obtener ayuda de la comunidad, y nuestro equipo de Servicios Profesionales también estará encantado de ayudarle.

Para probar por su cuenta los módulos dinámicos con NGINX Plus, inicie una prueba gratuita de 30 días hoy mismo o póngase en contacto con nosotros para hablar sobre sus casos de uso.

Sobre el autor

Owen GarrettDirector sénior de Gestión de Producto

Más artículos de Owen Garrett