NGINX Unit begrüßt den Herbst 2022 mit neuen Funktionen (einer Statistik-Engine!) und spannenden Plänen

Artem Konev

Das Wichtigste zuerst: Es ist schon eine ganze Weile her, dass wir Neuigkeiten vom NGINX Unit-Team veröffentlicht haben – diese turbulenten Zeiten haben uns alle getroffen, und wir bilden da keine Ausnahme. Im März dieses Jahres beschlossen zwei Gründungsmitglieder des Unit-Teams, Valentin Bartenev und Maxim Romanov, sich neuen Aufgaben zuzuwenden, nachdem sie jahrelange Arbeit und jede Menge Kreativität in NGINX Unit gesteckt hatten. Ehre, wem Ehre gebührt: Ohne sie wäre NGINX Unit heute nicht da, wo es ist. Hut ab, Jungs.

Dennoch bleiben unsere Entschlossenheit und unser Engagement ungebrochen, die ursprünglichen Ziele des NGINX-Mitbegründers Igor Sysoev für NGINX Unit zu verwirklichen. Mit Alejandro Colomar und Andrew Clayton sind zwei neue Mitglieder zum Team gestoßen und haben die Entwicklungsarbeit vorangebracht. Daher können wir Ihnen nun einige bemerkenswerte Neuerungen aus den NGINX-Unit-Versionen 1.25 bis 1.28 vorstellen.

Observability ist jetzt ein Thema

Eines der wichtigsten Ziele von Unit war schon immer die Beobachtbarkeit. Version 1.28.0 enthält nun die erste Ausbaustufe einer der am sehnlichsten erwarteten Funktionen: einer Statistik-Engine. Ihre Ausgabe ist über den neuen API-Endpunkt /status verfügbar:

$ curl --unix-socket /var/run/control.unit.sock http://localhost/status

{
    "connections": {
        "accepted": 1067,
        "active": 13,
        "idle": 4,
        "closed": 1050
    },

    "requests": {
        "total": 1307
    },

    "applications": {
        "wp": {
            "processes": {
                "running": 14,
                "starting": 0,
                "idle": 4
            },

            "requests": {
                "active": 10
            }
        }
    }
}

Die meisten Felder hier sind selbsterklärend: connections (Zeile 2) und requests (Zeile 9) liefern instanzweite Daten, während das Objekt applications (Zeile 13) /config/applications widerspiegelt und Prozesse sowie Anfragen umfasst, die speziell die Anwendung betreffen.

Die Zeilen 3–6 zeigen die vier Kategorien von Verbindungen, die von NGINX Unit erfasst werden: accepted, active, idle und closed. Die Kategorien für Prozesse lauten running, starting und idle (Zeilen 16–18). Diese Kategorien entsprechen der internen Darstellung von Verbindungen und Prozessen, sodass Sie darüber nun genauso viel wissen wie Ihr Server.

Klingt knapp? Mehr gibt es dazu vorerst eigentlich nicht zu wissen. Natürlich arbeiten wir daran, weitere nützliche Metriken bereitzustellen. Sie können diese API jedoch bereits über die Befehlszeile abfragen, um zu sehen, was auf Ihrem Server vor sich geht, und die Ausgabe sogar in ein Dashboard oder eine andere Lösung Ihrer Wahl einbinden, wenn Sie es etwas ausgefallener mögen. Sie haben kein Dashboard? Nun, zu unseren Plänen gehört auch, ein integriertes Dashboard bereitzustellen. Folgen Sie uns also, um zu erfahren, wie sich das entwickelt.

Weitere Informationen finden Sie unter „Nutzungsstatistiken“ in der Dokumentation zu NGINX Unit.

Mehr Variablen, mehr Einsatzmöglichkeiten

Die Liste der seit Version 1.24 eingeführten Variablen ist recht umfangreich und umfasst $body_bytes_sent, $header_referer, $header_user_agent, $remote_addr, $request_line, $request_uri, $status und $time_local.

Die meisten davon sind recht selbsterklärend, aber einige sind besonders erwähnenswert:

• $request_uri enthält den Pfad und die Abfrageparameter des angeforderten URI, wobei die Browserkodierung beibehalten wird
• Die ähnlich benannte Variable „$request_line“ enthält die gesamte Anfrage, beispielsweise GET /docs/help.html HTTP/1.1, und ist für die Protokollierung vorgesehen…
• Ebenso wie $status – diese Variable enthält den HTTP-Antwortstatuscode

Ist es Ihnen aufgefallen? Wir haben Antworten erwähnt. Ja, auch in diesen Bereich stoßen wir nun vor: In früheren Unit-Versionen konzentrierten sich die Variablen auf eingehende Anfragen, doch jetzt gibt es auch Variablen, die Eigenschaften der Antwort erfassen, wie etwa $status und $body_bytes_sent.

Was neue Einsatzmöglichkeiten für Variablen betrifft, ist zunächst das neue anpassbare Format für Zugriffsprotokolle zu nennen. Möchten Sie JSON in den Protokolleinträgen von NGINX Unit verwenden? Neben der Angabe einer einfachen Pfadzeichenfolge kann die Option „access_log“ auch ein Objekt sein, das zusätzlich das Format der Protokolleinträge festlegt:

{ 
    "access_log": {
        "path": "/var/log/unit/access.log", 
        "format": "{ \"remote_addr\":\"$remote_addr\", "time\":\"$time_local\", \"request\":\"$request_line\", \"response\":\"$status\", \"header_referer\":\"$header_referer\", \"header_user_agent\":\"$header_user_agent\" }" 
    } 
}

So können Sie das übliche Protokollformat ganz nach Belieben erweitern.

Ein weiterer erwähnenswerter Anwendungsfall für Variablen ist der location-Wert einer Routen-action:

{ 
    "action": { 
        "return": 301, 
        "location": "https://$host$request_uri" 
    } 
 }

Hier verwenden wir $request_uri, um die Anfrage einschließlich des Abfrageteils über HTTPS an dieselbe Website weiterzuleiten.

Die Option „chroot“ unterstützt nun ebenso wie die Option „share“ Variablen, was nur logisch ist:

{ 
    "action": { 
        "share": "/www$uri",
        "chroot": "/www/data/$host/" 
    } 
} 

NGINX Unit unterstützt jetzt auch dynamische Variablen. Anfrageargumente, Cookies und Header werden als Variablen bereitgestellt: So führt beispielsweise die Abfragezeichenfolge Type=car&Color=red zu zwei Argumentvariablen, $arg_Type und $arg_Color. Zur Laufzeit werden diese Variablen durch dynamische Werte ersetzt. Wird auf eine nicht vorhandene Variable verwiesen, gilt sie als leer.

Weitere Informationen finden Sie unter „Variablen“ in der NGINX Unit-Dokumentation.

Umfassende Unterstützung für die X-Forwarded-*-Header

Sie haben danach gefragt, und wir haben geliefert. Seit Version 1.25.0 bietet NGINX Unit einige Möglichkeiten zur TLS-Konfiguration seiner Listener, darunter auch eine gewisse Unterstützung für X-Forwarded-*; nun können Sie in der Konfiguration Ihrer Listener Client-IP-Adressen und die Protokollersetzung festlegen:

{
    "listeners": {
        "*:80": {
            "pass": "routes/my-app",
            "forwarded": {
                "client_ip": "X-Forwarded-For",
                "protocol": "X-Forwarded-Proto",
                "recursive": false,
                "source": [
                    "198.51.100.1-198.51.100.254",
                    "!198.51.100.128/26",
                    "203.0.113.195"
                ]
            }
        }
    },
    ...
}

Hinweis: Diese neue Syntax ersetzt die bisherige client_ip-Syntax, die in einer zukünftigen Version entfernt wird.

Weitere Informationen finden Sie unter „IP- und Protokollweiterleitung“ in der Dokumentation zu NGINX Unit.

Die überarbeitete share-Option

Mit NGINX Unit Version 1.11.0 wurde die Routing-Option „share“ zum Bereitstellen statischer Inhalte eingeführt. Sie ist mit der Direktive „root“ in NGINX vergleichbar:

{
    "share": "/path/to/dir/"
}

Ursprünglich gab die Option share das sogenannte Dokumentstammverzeichnis an. Um zu bestimmen, welche Datei ausgeliefert werden sollte, hängte Unit einfach den URI aus der Anfrage an diesen share-Pfad an. Beispielsweise lieferte Unit bei einer einfachen GET-Anfrage für /some/file.html die Datei /path/to/dir/some/file.html aus. Allerdings stießen wir immer wieder auf Grenzfälle, die eine genauere Kontrolle über den Dateipfad erforderten. Daher beschlossen wir, die Funktionsweise weiterzuentwickeln. Seit Version 1.26.0 gibt die Option share den vollständigen Pfad zu einer freigegebenen Datei an und nicht mehr nur das Dokumentstammverzeichnis.

Sie möchten eine bestimmte Datei ausliefern? Kein Problem:

{
    "share": "/path/to/a/file.html"
}

Variablen innerhalb des Pfads verwenden? Klar, kein Problem:

{
    "share": "/www/data/$host/app.html"
}

Aber wie lässt sich das Verhalten nachbilden, das Sie bereits von NGINX und früheren Unit-Versionen gewohnt sind? Sie wissen schon, die Sache mit dem Dokumentenstammverzeichnis, die wir ein paar Absätze zuvor für überholt erklärt haben? Wir haben eine Lösung.

Sie können Konfigurationen nun wie folgt umschreiben:

{
    "share": "/www/data/"
}

wie folgt, wobei der angeforderte URI explizit an den Pfad angehängt wird!

{
    "share": "/www/data/$uri"
}

Schließlich kann die share-Direktive nun ein Array von Pfaden akzeptieren, die sie nacheinander durchsucht, bis sie eine Datei findet:

{
    "share": [
        "/www/$host$uri",
        "/www/static$uri",
        "/www/app.html"
    ]
}

Wenn keine Datei gefunden wird, wird das Routing an eine fallback-Aktion übergeben. Ist kein fallback vorhanden, wird der Statuscode 404 (Not Found) zurückgegeben.

Weitere Informationen finden Sie unter „Statische Dateien“ in der Dokumentation zu NGINX Unit.

Pläne: njs, URI-Umschreibung, Aktionsverkettung, OpenAPI

Während Sie dies lesen, arbeiten wir bereits an der nächsten Version. Hier erhalten Sie einen kleinen Vorgeschmack auf das, was wir in petto haben.

Zunächst integrieren wir NGINX Unit mit dem NGINX-JavaScript-Modul (njs), einem weiteren leistungsstarken Projekt, das bei NGINX aktiv weiterentwickelt wird. Kurz gesagt bedeutet dies, dass NGINX Unit den Aufruf von JavaScript-Modulen unterstützen wird. Sehen wir uns dazu Folgendes an:

var hellonjs = {}

hellonjs.hello = function(vars) {
    if ('unitvar' in vars) {
        return vars.unitvar;

    } else {
        return 'default';
    }
}

export default hellonjs

Nachdem Sie das Modul in NGINX Unit importiert haben, können Sie einige praktische Dinge mit der Konfiguration anstellen:

{
    "match": {
        "uri": "~(?.*)" }, "action": { "share": "`/www/html${hellonjs.hello(vars)}`" } }

Außerdem möchten wir etwas Ähnliches wie die allseits beliebte NGINX-rewrite-Direktive einführen:

{
    "match": {
        "uri": "/app/old_path"
     },
     
    "action": {
        "rewrite": "/app/new_path",
        "pass": "routes"
    }
}

Unsere Pläne gehen jedoch noch weiter. Wie wäre es, das Routing von NGINX Unit mit der Ausgabe der Anwendungen selbst zu verknüpfen (auch bekannt als „action chaining“)?

{
    "action": [
        {
            "pass": "applications/auth_check"
        },
        {
            "pass": "applications/my_app"
        }
    ]
}

Die Idee dabei ist, dass die Anwendung auth_check die eingehende Anfrage authentifiziert und einen Statuscode zurückgibt, der das Ergebnis angibt. Bei erfolgreicher Authentifizierung wird 200 OK zurückgegeben und die Anfrage an my_app weitergeleitet.

Unterdessen arbeiten wir auch an einer OpenAPI-Spezifikation, um die API von NGINX Unit und ihre genauen Funktionen ein für alle Mal zu definieren. Wünschen Sie uns Glück, denn dies ist ein gewaltiges Unterfangen.

Falls das noch immer nicht ausreicht, um Ihre Neugier zu stillen, werfen Sie einen Blick auf unsere Roadmap mit einer detaillierten Aufschlüsselung unserer Pläne. Sie ist interaktiv, daher freuen wir uns über jeden Beitrag von Ihnen, liebe Leserinnen und Leser.

Über den Autor

Artem Konev

Weitere Blogbeiträge von Artem Konev