Compilation de modules dynamiques tiers pour NGINX et NGINX Plus

Éditeur – L’article de blog annonçant la sortie originale du support des modules dynamiques (dans NGINX Open Source 1.9.11, février 2016) redirige ici. Le processus de construction décrit dans cet article est obsolète.

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

• Cet article fournit des instructions étape par étape pour compiler des modules dynamiques tiers qui peuvent ê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 pour automatiser les builds de modules dynamiques tiers pour un environnement de production. Il explique comment créer des packages installables pour des modules dynamiques tiers qui incluent la vérification des dépendances de version.

NGINX Open Source 1.11.5 et NGINX Plus Release R11 ont introduit la compatibilité binaire pour les modules dynamiques. Cet article explique comment compiler des modules tiers à utiliser avec NGINX Open Source et NGINX Plus dans un environnement de développement. Pour obtenir des instructions sur la création, le déploiement et la mise à niveau de modules dynamiques tiers dans un environnement de production, consultez Création de packages installables pour les modules dynamiques .

Par souci de concision, le reste de cet article fait référence à NGINX Plus uniquement, sauf lorsque la différence entre celui-ci et NGINX Open Source est pertinente. Sauf indication contraire, toutes les déclarations 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 conformes à l'API décrite dans Extension de NGINX sur le Wiki NGINX. Il existe un vaste écosystème de modules tiers , allant des interprètes linguistiques aux solutions de sécurité, et certains d’entre eux sont inclus et pris en charge dans NGINX Plus.

Les autres modules tiers et les modules que vous avez créés vous-même doivent être compilés indépendamment 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 avec NGINX Open Source comme illustré dans les deux exemples ci-dessous :

1. Obtenez la version Open Source NGINX correspondante
2. Obtenez les sources du module et modifiez le fichier de configuration du module si nécessaire
3. Créez le module dynamique par rapport à la version Open Source de NGINX, avec l'argument --with-compat de la commande configure
4. Chargez le module dynamique résultant (le fichier .so ) dans NGINX Plus et utilisez-le comme s’il s’agissait d’un module intégré

Exemple: Un module simple « Hello World »

Cet exemple utilise un simple module Hello World pour montrer comment mettre à jour la 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 avec un message simple.

Étape 1 : Obtenez la version Open Source de NGINX

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

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

2. Téléchargez le package Open Source NGINX correspondant sur 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

3. Obtenez la source du module NGINX « Hello World » depuis GitHub :

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

4. Le fichier shell de configuration d'un module définit la manière dont il est construit, et son format est différent pour les modules dynamiques que pour les modules construits de manière statique dans un binaire NGINX Open Source.

   Modifiez le fichier nginx-hello-world-module/config pour qu'il contienne les éléments suivants :

   ngx_addon_name=ngx_http_hello_world_module
   
   si test -n "$ngx_module_link"; alors
   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
   sinon
   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 des informations détaillées sur la compilation de modules dynamiques, y compris des instructions sur la mise à jour du fichier de configuration d'un module à partir de l'ancien format, consultez le Wiki NGINX .

Étape 3 : Compiler le module dynamique

5. Compilez le module en exécutant d’abord le script de configuration avec l’argument --with-compat , qui crée un environnement de build standard pris en charge par NGINX Open Source et NGINX Plus. Exécutez ensuite make modules pour construire le module :

   $ cd nginx-1.11.5/ $ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module $ créer des modules
   

6. Copiez la bibliothèque de modules (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

7. 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 (pas dans le contexte http ou stream ) :

   charger_module modules/ngx_http_hello_world_module.so;
   

8. Dans le contexte http , ajoutez un bloc d'emplacement avec la directive hello_world fournie par le module Hello World. Les requêtes adressées à l'emplacement renvoient la réponse hello world .

   serveur {
   écoute 80 ;
   
   emplacement / {
   bonjour_monde ;
   }
   }
   

9. Rechargez votre configuration NGINX Plus et testez-la avec une simple requête :

   $ nginx -s recharger $ curl http://localhost/ bonjour le monde
   

Exemple: Le pare-feu d'application Web NAXSI

NAXSI est un pare-feu d'application Web (WAF) hautes performances et facile à utiliser qui utilise des heuristiques et un système de notation pour identifier les requêtes suspectes telles que les attaques XSS et par injection SQL.

La source NAXSI a été mise à jour pour se conformer au nouveau format du fichier shell de configuration , donc la création d'un module dynamique pour NGINX Plus est simple. Le processus est basé 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 $ créer des modules $ sudo cp objs/ngx_http_naxsi_module.so /etc/nginx/modules

Chargez le module dans le noyau NGINX Plus en ajoutant la directive load_module au contexte principal de votre fichier nginx.conf :

charger_module modules/ngx_http_naxsi_module.so;

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

# Modifiez cette directive 'include' pour qu'elle pointe vers votre fichier naxsi_core.rules
include /home/owen/src/naxsi/naxsi_config/naxsi_core.rules;

server {
listen 80;

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

# Activer NAXSI
SecRulesEnabled;

# Définir où vont les requêtes bloquées
DeniedUrl "/50x.html";

# CheckRules, déterminer quand NAXSI doit agir
CheckRule "$SQL >= 8" BLOCK;
CheckRule "$RFI >= 8" BLOCK;
CheckRule "$TRAVERSAL >= 4" BLOCK;
CheckRule "$EVADE >= 4" BLOCK;
CheckRule "$XSS >= 8" BLOCK;

# N'oubliez pas le journal des erreurs, où sont enregistrées les requêtes bloquées
error_log /tmp/naxsi.log;
}

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

Vous pouvez vérifier le bon fonctionnement de NAXSI avec une paire de requêtes HTTP simples :

• curl http://localhost/ renvoie la page d'index standard 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, renvoyant la page d'erreur standard 50x.html depuis /usr/share/nginx/html . Il enregistre également un message dans le journal des erreurs .

Pour les déploiements de production, vous pouvez également télécharger les versions NAXSI signées sur 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

Note: Les informations contenues dans cette section s'appliquent uniquement à NGINX Plus. L'ensemble de modules dynamiques fournis avec les packages NGINX Open Source prédéfinis 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 NGINX et les binaires prédéfinis.

NGINX Plus est livré avec un certain nombre de modules dynamiques que vous pouvez également télécharger directement depuis notre référentiel de modules. Pour une liste, voir la page Modules dynamiques . Ces modules sont de deux types :

• Les modules NGINX Plus sont écrits et/ou maintenus par l'équipe d'ingénierie NGINX. Nous ne les incluons pas dans NGINX Plus pour des raisons techniques (par exemple, ils ont des dépendances supplémentaires) ou parce qu'ils sont dans un état d'aperçu. Les modules d'aperçu sont en cours de développement actif et ne doivent être déployés qu'avec le plus grand soin. Sinon, les modules NGINX Plus sont entièrement pris en charge par NGINX. Pour obtenir une liste, filtrez par auteur NGINX sur la page Modules dynamiques .
• Les modules communautaires certifiés NGINX Plus sont des modules tiers populaires que NGINX teste et distribue, et pour lesquels nous fournissons une assistance pour l'installation et la configuration de base. Nous garantissons que ces modules n'interfèrent pas avec le bon fonctionnement de NGINX Plus, et nous les mettons à jour si nécessaire à chaque version de NGINX Plus ou lorsqu'il y a une mise à jour de sécurité. Pour obtenir une liste, filtrez par auteur Communauté sur la page Modules dynamiques .

De plus, NGINX certifie les modules des fournisseurs commerciaux qui participent à notre programme de modules certifiés NGINX Plus . Ces modules sont distribués et supportés par leurs fournisseurs. Pour obtenir une liste, filtrez par auteur 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 fournisseurs tiers qui ne font pas partie du programme de modules certifiés NGINX Plus et modules personnalisés). Si vous recherchez une assistance technique pour un problème, l'équipe d'assistance NGINX peut vous demander de supprimer un module non pris en charge et de reproduire le défaut dans le cadre de notre processus d'assistance technique, afin qu'elle puisse vérifier si le défaut est causé ou non par le module non pris en charge.

Résumé

Le processus de création de modules dynamiques pour NGINX Plus vous permet de profiter du vaste écosystème de modules Open Source NGINX, en les exécutant sur le cœur NGINX Plus riche et entièrement pris en charge.

Si vous utilisez actuellement NGINX Open Source avec des extensions tierces, ces extensions 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 construction signifie que vos utilisateurs peuvent 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 de configuration , veuillez consulter les ressources suivantes :

• Guide d'Emiller pour le développement de modules NGINX par Evan Miller
• Développement de modules dynamiques par le développeur NGINX Ruslan Ermilov
• Extension de NGINX sur le wiki NGINX
• Conversion de modules statiques en modules dynamiques sur le wiki NGINX
• Tutoriel NGINX : Développement de modules par Aaron Bedra
• Créer des packages installables pour les modules dynamiques sur notre blog

La liste de diffusion des développeurs NGINX est l’endroit idéal pour obtenir une assistance communautaire, et notre équipe de services professionnels est également heureuse de vous aider.

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