Kompilieren dynamischer Drittanbietermodule für NGINX und NGINX Plus

Owen GarrettSenior Director, Produktmanagement

Redaktion – Der Blogbeitrag, in dem die ursprüngliche Veröffentlichung der Unterstützung für dynamische Module (in NGINX Open Source 1.9.11, Februar 2016) angekündigt wurde, verweist nun auf diese Seite. Der in diesem Beitrag beschriebene Build-Prozess ist veraltet.

Dieser Beitrag ist Teil einer zweiteiligen Reihe über die Verwendung dynamischer Module von Drittanbietern mit NGINX Open Source und NGINX Plus.

• Dieser Beitrag enthält eine Schritt-für-Schritt-Anleitung zum Kompilieren dynamischer Module von Drittanbietern, die zur Laufzeit von NGINX Open Source oder NGINX Plus geladen werden können.
• Der zweite Beitrag enthält Anleitungen und Tools zur Automatisierung der Erstellung dynamischer Module von Drittanbietern für eine Produktionsumgebung. Er erläutert, wie sich installierbare Pakete für dynamische Module von Drittanbietern erstellen lassen, die eine Überprüfung der Versionsabhängigkeiten beinhalten.

NGINX Open Source 1.11.5 und NGINX Plus Release R11 führten die Binärkompatibilität für dynamische Module ein. In diesem Artikel wird erläutert, wie Sie Module von Drittanbietern für die Verwendung mit NGINX Open Source und NGINX Plus in einer Entwicklungsumgebung kompilieren. Anweisungen zum Erstellen, Bereitstellen und Aktualisieren dynamischer Module von Drittanbietern in einer Produktionsumgebung finden Sie unter „Erstellen installierbarer Pakete für dynamische Module“.

Der Kürze halber wird im weiteren Verlauf dieses Beitrags nur auf NGINX Plus Bezug genommen, außer wenn der Unterschied zu NGINX Open Source relevant ist. Sofern nicht anders angegeben, gelten alle Aussagen zu NGINX Plus auch für NGINX Open Source.

Übersicht über dynamische Module

Module, die in NGINX Plus geladen werden können, sind in C geschrieben und entsprechen der API, die unter „NGINX erweitern“ im NGINX-Wiki beschrieben ist. Es gibt ein großes Ökosystem von Drittanbietermodulen, das von Sprachinterpretern bis hin zu Sicherheitslösungen reicht. Einige davon sind in NGINX Plus enthalten und werden unterstützt.

Andere Drittanbietermodule sowie Module, die Sie selbst erstellt haben, müssen separat kompiliert und zur Laufzeit dynamisch in NGINX Plus geladen werden. Sie können diese Module für die Verwendung mit NGINX Plus kompilieren, indem Sie sie anhand von NGINX Open Source erstellen, wie in den beiden folgenden Beispielen gezeigt:

1. Die passende Version von NGINX Open Source beziehen
2. Beziehen Sie die Modulquellen und ändern Sie bei Bedarf die config-Datei des Moduls
3. Erstellen Sie das dynamische Modul für die NGINX Open Source-Version mit dem Argument --with-compat für den Befehl configure command
4. Laden Sie das resultierende dynamische Modul (die .so-Datei) in NGINX Plus und verwenden Sie es wie ein integriertes Modul

Beispiel: Ein einfaches „Hallo Welt“-Modul

In diesem Beispiel wird ein einfaches „Hello World“-Modul verwendet, um zu zeigen, wie Sie den Quellcode eines Moduls aktualisieren und es in NGINX Plus laden. Das „Hello World“-Modul implementiert eine einfache Direktive (hello_world), die auf Anfragen mit einer einfachen Nachricht antwortet.

Schritt 1: NGINX Open Source-Release beziehen

1. Ermitteln Sie die Version von NGINX Open Source, die Ihrer NGINX Plus-Installation entspricht. In diesem Beispiel ist es NGINX 1.11.5.

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

1. Laden Sie das entsprechende NGINX Open Source-Paket unter nginx.org/download herunter:

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

Schritt 2: Modulquellen herunterladen

1. Rufen Sie den Quellcode für das NGINX-Modul „Hello World“ von GitHub ab:

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

1. Die Shell-Datei config eines Moduls legt fest, wie es erstellt wird, und ihr Format unterscheidet sich bei dynamischen Modulen von dem bei Modulen, die statisch in eine NGINX Open Source-Binärdatei eingebunden werden. Ändern Sie die Datei nginx-hello-world-module/config so, dass sie Folgendes enthält:

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

Ausführliche Informationen zum Kompilieren dynamischer Module sowie Anweisungen zum Aktualisieren der config-Datei eines Moduls aus dem alten Format finden Sie im NGINX Wiki.

Schritt 3: Dynamisches Modul kompilieren

1. Kompilieren Sie das Modul, indem Sie zunächst das Skript configure mit dem Argument --with-compat ausführen. Dadurch wird eine Standard-Build-Umgebung erstellt, die sowohl von NGINX Open Source als auch von NGINX Plus unterstützt wird. Führen Sie anschließend make modules aus, um das Modul zu erstellen:

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

1. Kopieren Sie die Modulbibliothek (.so-Datei) nach /etc/nginx/modules:

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

Schritt 4: Modul laden und verwenden

1. Um das Modul in NGINX Plus zu laden, fügen Sie die Direktive load_module im übergeordneten (Haupt-)Kontext Ihrer Konfigurationsdatei nginx.conf hinzu (nicht innerhalb des Kontexts http oder stream):

load_module modules/ngx_http_hello_world_module.so;

1. Fügen Sie im http-Kontext einen location-Block mit der vom Hello-World-Modul bereitgestellten Direktive hello_world hinzu. Anfragen an diesen Speicherort geben die Antwort hello world zurück.

server {
    listen 80;

    location / {
         hello_world;
    }
}

1. Laden Sie Ihre NGINX Plus-Konfiguration neu und testen Sie sie mit einer einfachen Anfrage:

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

Beispiel: Die NAXSI-Webanwendungs-Firewall

NAXSI ist eine benutzerfreundliche, leistungsstarke Web Application Firewall (WAF), die mithilfe von Heuristiken und einem Bewertungssystem verdächtige Anfragen wie XSS- und SQL-Injection-Angriffe erkennt.

Der NAXSI-Quellcode wurde aktualisiert, um dem neuen Format der Shell-Datei config zu entsprechen, sodass sich ein dynamisches Modul für NGINX Plus problemlos erstellen lässt. Der Vorgang basiert auf der NAXSI-Installationsanleitung:

$ 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

Laden Sie das Modul in den NGINX Plus-Kern, indem Sie die Direktive load_module zum Hauptkontext Ihrer Datei nginx.conf hinzufügen:

load_module modules/ngx_http_naxsi_module.so;

Die NAXSI-Konfiguration wird ausführlich in der Projektdokumentation beschrieben. Die folgende NGINX-Konfiguration veranschaulicht das Modul im Einsatz:

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

Sie können die korrekte Funktionsweise von NAXSI mit zwei einfachen HTTP-Anfragen überprüfen:

• curl http://localhost/ gibt die standardmäßige NGINX Plus-Indexseite zurück, die unter /usr/share/nginx/html gespeichert ist.
• curl "http://localhost/?a=<>" löst die XSS-Erkennung von NAXSI aus und blockiert die Anfrage. Dabei wird die standardmäßige Fehlerseite 50x.html aus /usr/share/nginx/html zurückgegeben. Außerdem wird eine Meldung im error_log protokolliert.

Für Produktivumgebungen können Sie auch signierte NAXSI-Versionen herunterladen unter https://github.com/nbs-system/naxsi/tags und sie auf ähnliche Weise kompilieren.

So unterstützen wir dynamische Module in NGINX Plus

Hinweis: Die Informationen in diesem Abschnitt gelten nur für NGINX Plus. Die in vorkompilierten NGINX Open Source-Paketen enthaltenen dynamischen Module können sich von den mit NGINX Plus ausgelieferten Modulen unterscheiden. Mit NGINX Open Source verwendete dynamische Module werden unterstützt wie der NGINX-Quellcode und die vorkompilierten Binärdateien.

NGINX Plus wird mit einer Reihe dynamischer Module ausgeliefert, die Sie auch direkt aus unserem Modul-Repository herunterladen können. Eine Liste finden Sie auf der Seite „Dynamische Module“. Es gibt zwei Arten dieser Module:

• NGINX Plus modules werden vom NGINX-Entwicklungsteam entwickelt und/oder gepflegt. Sie sind aus technischen Gründen (beispielsweise aufgrund zusätzlicher Abhängigkeiten) oder wegen ihres Vorschaustatus nicht in NGINX Plus enthalten. Vorschaumodule befinden sich in aktiver Entwicklung und sollten nur mit größter Sorgfalt bereitgestellt werden. Abgesehen davon werden NGINX Plus-Module vollständig von NGINX unterstützt. Um eine Liste anzuzeigen, filtern Sie auf der Seite „NGINX“ nach dem Autor „Dynamische Module“.
• Zertifizierte Community-Module für NGINX Plus sind beliebte Module von Drittanbietern, die von NGINX getestet und vertrieben werden und für die wir Unterstützung bei der Installation und grundlegenden Konfiguration bieten. Wir gewährleisten, dass diese Module den ordnungsgemäßen Betrieb von NGINX Plus nicht beeinträchtigen, und aktualisieren sie bei Bedarf mit jeder neuen Version von NGINX Plus oder bei einem Sicherheitsupdate. Um eine Liste anzuzeigen, filtern Sie nach dem Autor „Community“ auf der Seite „Dynamische Module“.

Darüber hinaus zertifiziert NGINX Module kommerzieller Anbieter, die an unserem Programm „NGINX Plus Certified Modules“ teilnehmen. Diese Module werden von den jeweiligen Anbietern vertrieben und unterstützt. Um eine Liste anzuzeigen, filtern Sie auf der Seite „Certified Partner“ nach Autor Dynamic Modules.

NGINX testet oder unterstützt keine Module, die Sie selbst kompilieren (andere Community-Module, Module von Drittanbietern, die nicht am Programm „NGINX Plus Certified Modules“ teilnehmen, sowie benutzerdefinierte Module). Wenn Sie technische Unterstützung bei einem Problem benötigen, werden Sie vom NGINX-Supportteam im Rahmen unseres technischen Supportprozesses möglicherweise aufgefordert, ein nicht unterstütztes Modul zu entfernen und den Fehler zu reproduzieren, damit überprüft werden kann, ob der Fehler durch das nicht unterstützte Modul verursacht wird.

Zusammenfassung

Der Build-Prozess für dynamische Module von NGINX Plus ermöglicht es Ihnen, das breite Ökosystem der NGINX Open Source-Module zu nutzen und diese auf dem funktionsreichen und vollständig unterstützten NGINX Plus-Kern auszuführen.

Wenn Sie derzeit NGINX Open Source mit Erweiterungen von Drittanbietern verwenden, können diese Erweiterungen höchstwahrscheinlich kompiliert und in NGINX Plus geladen werden.

Wenn Sie kommerzielle oder Community-Module entwickeln, können Ihre Benutzer diese dank des neuen Build-Prozesses mit NGINX Plus bereitstellen. Informationen zur Zertifizierung eines kommerziellen Moduls finden Sie unter „NGINX Plus Certified Modules“.

Wenn Sie Unterstützung bei der Entwicklung eines Moduls oder der Aktualisierung der zugehörigen config-Shell-Datei benötigen, nutzen Sie bitte die folgenden Ressourcen:

• Emillers Leitfaden zur Entwicklung von NGINX-Modulen von Evan Miller
• Entwicklung dynamischer Module vom NGINX-Entwickler Ruslan Ermilov
• NGINX erweitern im NGINX Wiki
• Statische Module in dynamische Module konvertieren im NGINX Wiki
• NGINX-Tutorial: Entwicklung von Modulen von Aaron Bedra
• Installierbare Pakete für dynamische Module erstellen in unserem Blog

Die NGINX-Developers-Mailingliste ist die erste Anlaufstelle für Unterstützung durch die Community. Auch unser Professional-Services-Team hilft Ihnen gerne weiter.

Wenn Sie dynamische Module mit NGINX Plus selbst ausprobieren möchten, starten Sie noch heute eine kostenlose 30-Tage-Testversion oder kontaktieren Sie uns, um Ihre Anwendungsfälle zu besprechen.

Über den Autor

Owen GarrettSenior Director, Produktmanagement

Weitere Blogbeiträge von Owen Garrett