Compilation de modules dynamiques tiers pour NGINX et NGINX Plus

Owen GarrettDirecteur senior de la gestion des produits

Éditeur – L’article de blog annonçant la sortie initiale de la prise en charge des modules dynamiques (dans NGINX Open Source 1.9.11, en février 2016) redirige vers cette page. Le processus de compilation décrit dans cet article est obsolète.

Cet article fait partie d’une série en deux volets consacrée à l’utilisation de modules dynamiques tiers avec NGINX Open Source et NGINX Plus.

• Cet article fournit des instructions détaillées pour compiler des modules dynamiques tiers pouvant être chargés par NGINX Open Source ou NGINX Plus lors de l’exécution.
• Le deuxième article fournit des conseils et des outils permettant d’automatiser la compilation de modules dynamiques tiers pour un environnement de production. Il explique comment créer des paquets installables pour des modules dynamiques tiers, avec vérification des dépendances de version.

NGINX Open Source 1.11.5 et NGINX Plus version R11 ont introduit la compatibilité binaire pour les modules dynamiques. Cet article explique comment compiler des modules tiers destinés à être utilisés avec NGINX Open Source et NGINX Plus dans un environnement de développement. Pour savoir comment créer, déployer et mettre à niveau des modules dynamiques tiers dans un environnement de production, consultez Création de paquets installables pour les modules dynamiques.

Par souci de concision, la suite de cet article fait uniquement référence à NGINX Plus, sauf lorsque la différence avec NGINX Open Source est pertinente. Sauf indication contraire, toutes les affirmations concernant NGINX Plus s’appliquent également à NGINX Open Source.

Présentation des modules dynamiques

Les modules pouvant être chargés dans NGINX Plus sont écrits en C et respectent l’API décrite dans « Extension de NGINX » sur le wiki NGINX. Il existe un vaste écosystème de modules tiers, allant des interpréteurs de langages aux solutions de sécurité, et certains d’entre eux sont inclus et pris en charge dans NGINX Plus.

Les autres modules tiers, ainsi que les modules que vous avez créés vous-même, doivent être compilés séparément et chargés dynamiquement dans NGINX Plus lors de l’exécution. Vous pouvez compiler ces modules pour les utiliser avec NGINX Plus en les construisant à partir de NGINX Open Source, comme l’illustrent les deux exemples ci-dessous :

1. Obtenez la version correspondante de NGINX Open Source
2. Obtenez les sources du module et modifiez le fichier config du module si nécessaire
3. Compilez le module dynamique avec la version de NGINX Open Source, en passant l’argument « --with-compat » à la commande « configure »
4. Chargez le module dynamique obtenu (le fichier .so) dans NGINX Plus et utilisez-le comme s’il s’agissait d’un module intégré

Exemple : un module « Hello World » simple

Cet exemple utilise un simple module Hello World pour montrer comment mettre à jour le code source d’un module et le charger dans NGINX Plus. Le module « Hello World » implémente une directive simple (hello_world) qui répond aux requêtes par un message simple.

Étape 1 : obtenir la version de NGINX Open Source

1. Déterminez la version de NGINX Open Source correspondant à votre installation de NGINX Plus. Dans cet exemple, il s’agit de NGINX 1.11.5.

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

1. Téléchargez le paquet NGINX Open Source correspondant à l’adresse nginx.org/download :

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

Étape 2 : obtenir les sources du module

1. Récupérez le code source du module NGINX « Hello World » depuis GitHub :

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

1. Le fichier shell config d’un module définit la manière dont il est compilé, et son format diffère pour les modules dynamiques de celui des modules intégrés statiquement à un binaire NGINX Open Source. Modifiez le fichier nginx-hello-world-module/config afin qu’il contienne ce qui suit :

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

Pour obtenir des informations détaillées sur la compilation de modules dynamiques, notamment des instructions pour mettre à jour le fichier config d’un module depuis l’ancien format, consultez le wiki NGINX.

Étape 3 : compiler le module dynamique

1. Compilez le module en exécutant d’abord le script configure avec l’argument --with-compat, qui crée un environnement de compilation standard pris en charge à la fois par NGINX Open Source et NGINX Plus. Exécutez ensuite make modules pour compiler le module :

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

1. Copiez la bibliothèque du module (fichier « .so ») dans /etc/nginx/modules :

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

Étape 4 : charger et utiliser le module

1. Pour charger le module dans NGINX Plus, ajoutez la directive « load_module » dans le contexte de niveau supérieur (principal) de votre fichier de configuration nginx.conf (et non dans le contexte http ou stream) :

load_module modules/ngx_http_hello_world_module.so;

1. Dans le contexte http, ajoutez un bloc location avec la directive hello_world fournie par le module Hello World. Les requêtes envoyées à cet emplacement renvoient la réponse hello world.

server {
    listen 80;

    location / {
         hello_world;
    }
}

1. Rechargez votre configuration NGINX Plus et testez-la à l’aide d’une requête simple :

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

Exemple : le pare-feu applicatif web NAXSI

NAXSI est un pare-feu d’applications web (WAF) facile à utiliser et performant, qui s’appuie sur des heuristiques et un système de notation pour détecter les requêtes suspectes, telles que les attaques XSS et les injections SQL.

Le code source de NAXSI a été mis à jour pour être conforme au nouveau format du fichier shell config, ce qui facilite la création d’un module dynamique pour NGINX Plus. Le processus s’appuie sur les instructions d’installation 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

Chargez le module dans le cœur de NGINX Plus en ajoutant la directive « load_module » au contexte principal de votre fichier nginx.conf :

load_module modules/ngx_http_naxsi_module.so;

La configuration de NAXSI est décrite en détail dans la documentation du projet. La configuration NGINX suivante illustre le fonctionnement du module :

# 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;
}

Vous pouvez vérifier le bon fonctionnement de NAXSI à l’aide de deux requêtes HTTP simples :

• curl http://localhost/ renvoie la page d’index standard de NGINX Plus stockée dans /usr/share/nginx/html.
• curl "http://localhost/?a=<>" déclenche la détection XSS de NAXSI et bloque la requête, en renvoyant la page d’erreur standard 50x.html depuis /usr/share/nginx/html. Un message est également consigné dans le journal error_log.

Pour les déploiements en production, vous pouvez également télécharger les versions signées de NAXSI à l’adresse https://github.com/nbs-system/naxsi/tags et les compiler de manière similaire.

Comment nous prenons en charge les modules dynamiques dans NGINX Plus

Remarque : Les informations de cette section s’appliquent uniquement à NGINX Plus. L’ensemble des modules dynamiques fournis avec les packages NGINX Open Source précompilés peut différer de ceux fournis avec NGINX Plus. Les modules dynamiques utilisés avec NGINX Open Source sont pris en charge de la même manière que le code source de NGINX et les fichiers binaires précompilés.

NGINX Plus est fourni avec plusieurs modules dynamiques que vous pouvez également télécharger directement depuis notre dépôt de modules. Pour en obtenir la liste, consultez la page Modules dynamiques. Ces modules sont de deux types :

• NGINX Plus modules sont écrits et/ou maintenus par l’équipe d’ingénierie de NGINX. Nous ne les incluons pas dans NGINX Plus pour des raisons techniques (par exemple, parce qu’ils ont des dépendances supplémentaires) ou parce qu’ils sont en phase de préversion. Les modules en préversion sont en cours de développement actif et ne doivent être déployés qu’avec la plus grande prudence. Les autres modules NGINX Plus sont entièrement pris en charge par NGINX. Pour en afficher la liste, filtrez par auteur NGINX sur la page « Modules dynamiques ».
• Modules communautaires certifiés NGINX Plus sont des modules tiers populaires que NGINX teste et distribue, et pour lesquels nous fournissons une assistance à l’installation et à la configuration de base. Nous garantissons que ces modules n’entravent pas le bon fonctionnement de NGINX Plus et nous les mettons à jour si nécessaire à chaque nouvelle version de NGINX Plus ou lors de la publication d’une mise à jour de sécurité. Pour en obtenir la liste, filtrez par auteur : « Communauté » sur la page « Modules dynamiques ».

En outre, NGINX certifie les modules des fournisseurs commerciaux qui participent à notre programme « Modules certifiés NGINX Plus ». Ces modules sont distribués et pris en charge par leurs fournisseurs. Pour en afficher la liste, filtrez par auteur en sélectionnant « Partenaire certifié » sur la page « Modules dynamiques ».

NGINX ne teste ni ne prend en charge les modules que vous compilez vous-même (autres modules communautaires, modules fournis par des éditeurs tiers qui ne participent pas au programme NGINX Plus Certified Modules et modules personnalisés). Si vous sollicitez une assistance technique pour résoudre un problème, l’équipe d’assistance NGINX peut vous demander de supprimer un module non pris en charge et de reproduire le dysfonctionnement dans le cadre de notre processus d’assistance technique, afin de déterminer si celui-ci est dû ou non au module non pris en charge.

Résumé

Le processus de compilation des modules dynamiques pour NGINX Plus vous permet de tirer parti du vaste écosystème de modules NGINX Open Source, en les exécutant sur le cœur riche en fonctionnalités et entièrement pris en charge de NGINX Plus.

Si vous utilisez actuellement NGINX Open Source avec des extensions tierces, celles-ci peuvent très probablement être compilées et chargées dans NGINX Plus.

Si vous développez des modules commerciaux ou communautaires, le nouveau processus de compilation permet à vos utilisateurs de déployer vos modules avec NGINX Plus. Pour en savoir plus sur la certification d’un module commercial, consultez Modules certifiés NGINX Plus.

Si vous avez besoin d’aide pour développer un module ou mettre à jour son fichier shell config, consultez les ressources suivantes :

• Guide d’Emiller sur le développement de modules NGINX par Evan Miller
• Développement de modules dynamiques par Ruslan Ermilov, développeur NGINX
• Étendre NGINX sur le wiki NGINX
• Conversion de modules statiques en modules dynamiques sur le wiki NGINX
• Tutoriel NGINX : développer des modules par Aaron Bedra
• Création de paquets installables pour les modules dynamiques sur notre blog

La liste de diffusion NGINX Developers est la ressource incontournable pour obtenir l’aide de la communauté, et notre équipe de services professionnels se tient également à votre disposition.

Pour essayer vous-même les modules dynamiques avec NGINX Plus, commencez un essai gratuit de 30 jours dès aujourd’hui ou contactez-nous pour discuter de vos cas d’utilisation.

À propos de l’auteur

Owen GarrettDirecteur senior de la gestion des produits

Autres articles de Owen Garrett