NGINX Resolver Cache richtig konfigurieren

NGINX Resolver und DNS-Cache verstehen

Ein Reverse Proxy benötigt für ein Backend mit Hostnamen zunächst eine IP-Adresse. Der NGINX-Resolver fragt dafür die in der Konfiguration festgelegten Nameserver ab. Die erhaltene DNS-Antwort wird zwischengespeichert, damit NGINX den Namen während seiner Gültigkeitsdauer nicht für jede Anfrage erneut auflösen muss. Dieser Cache betrifft ausschließlich die Namensauflösung zum Zielsystem.

Die Direktive resolver enthält eine oder mehrere Resolver-Adressen beziehungsweise unterstützte Resolver-Bezeichner. Ohne abweichende Portangabe verwendet NGINX Port 53; bei mehreren eingetragenen Servern erfolgen die Anfragen laut Dokumentation im Round-Robin-Verfahren. Für eine robuste Bootstrap-Konfiguration sind feste IP-Adressen oft nachvollziehbar, weil ihre Auflösung nicht selbst von DNS abhängt.

Standardmäßig berücksichtigt NGINX IPv4- und IPv6-Adressen eines Namens. Das ist passend, wenn das Netzwerk beide Protokollfamilien bis zum Backend zuverlässig transportiert. Parameter wie ipv4=off oder ipv6=off schließen eine Familie gezielt aus, sind aber keine allgemeine Cache-Optimierung. Ob sie erforderlich sind, entscheidet die Erreichbarkeit des konkreten Backends und nicht die bloße Existenz eines AAAA-Records.

Der Resolver ist weder ein vollwertiger rekursiver DNS-Server noch eine automatische Übernahme aller Einstellungen aus /etc/resolv.conf. NGINX nutzt die explizit angegebenen Nameserver. Für interne Zonen und produktive Backend-Namen sollten das vertrauenswürdige, angemessen abgesicherte Resolver im eigenen Netzwerk sein. So bleiben Zuständigkeit für private Namen und Schutz vor manipulierten DNS-Antworten in einer kontrollierbaren Infrastruktur.

DNS-Cache ist kein HTTP-Cache

Der DNS-Response-Cache des Resolvers speichert Zuordnungen zwischen Namen und DNS-Antworten, etwa A- oder AAAA-Adressen. Sein Zweck ist, ein Backend erneut erreichen zu können, ohne jede Namensauflösung wiederholen zu müssen. Ändert sich eine Backend-IP, ist deshalb die Gültigkeit der DNS-Antwort relevant – nicht der Inhalt einer zuvor ausgelieferten HTTP-Antwort.

Davon getrennt speichert proxy_cache HTTP-Responses eines Upstreams. Der Schlüssel umfasst je nach Konfiguration beispielsweise URI, Host oder Header; ein Treffer liefert eine bereits gespeicherte Antwort an den Client. Probleme zeigen sich hier als veraltete Seiten, falsche Varianten oder unerwartete Cache-Hits. Diese Funktion entscheidet nicht, welche IP NGINX beim Aufbau einer neuen Backend-Verbindung verwendet.

Der Open-File-Cache ist eine dritte Ebene: Er hält Dateiinformationen und offene Deskriptoren für lokale Dateisystemzugriffe vor, aber weder DNS-Antworten noch HTTP-Inhalte. Wer diese Abgrenzung für statische Auslieferung vertiefen möchte, findet sie im Beitrag zur Konfiguration des NGINX Open File Cache. Für die Wahl einer Resolver-TTL liefert er jedoch keine Entscheidungsgrundlage.

Das Leeren, Purgen oder Abstimmen eines HTTP-Caches beschleunigt daher keine DNS-Änderung. Umgekehrt behebt eine neue DNS-Auflösung keine fehlerhaft gecachte HTTP-Antwort. Beim Reverse Proxy begrenzt der DNS-Cache sich zudem auf Namen und Adressen: Er prüft weder die Gesundheit einer Anwendung noch ersetzt er Load-Balancing, Retries oder die korrekte Timeout-Planung zum Upstream.

Wann NGINX Namen erneut auflösen muss

Ein Hostname kann NGINX bereits beim Einlesen der Konfiguration bekannt sein. Anders ist der Fall bei einem variablen Ziel, etwa proxy_pass http://$backend;. NGINX sucht den resultierenden Namen zunächst in definierten Upstream-Gruppen. Findet es dort keinen passenden Namen, braucht es zur Laufzeit einen konfigurierten Resolver, um die Zieladresse zu ermitteln.

Die Meldung no resolver defined weist in diesem Zusammenhang nicht auf einen fehlenden HTTP-Cache hin. Sie bedeutet, dass NGINX für die notwendige Laufzeitauflösung keinen DNS-Server kennt. resolver darf im Kontext http, server oder location stehen. Ein zentraler Eintrag im http-Block eignet sich, wenn mehrere virtuelle Hosts denselben Resolver nutzen; ein engerer Scope passt nur bei tatsächlich abweichenden Anforderungen.

Von dieser lang verfügbaren Laufzeitauflösung ist die dynamische Aktualisierung einer klassischen Upstream-Gruppe zu trennen. Die Resolver-Konfiguration direkt im upstream-Block sowie server hostname resolve sind laut Dokumentation in NGINX Open Source ab Version 1.27.3 verfügbar. Ältere Open-Source-Installationen dürfen nicht so behandelt werden, als unterstützten sie dieses Muster automatisch; entsprechende Funktionen waren historisch teilweise NGINX Plus vorbehalten.

Vor der Planung dynamischer Upstreams prüfst du die installierte Ausgabe und Build-Informationen. Der folgende Befehl gibt die NGINX-Version, die Compiler-Version und die beim Build verwendeten Configure-Parameter aus.

nginx -V

Vergleiche den angezeigten Stand bei kritischen Deployments mit der Dokumentation des konkret eingesetzten Pakets und dessen Anbieters. Maßgeblich ist, ob diese Installation die benötigte Funktion dokumentiert und bereitstellt. Erst danach ist ein dynamischer Upstream eine belastbare Architekturentscheidung.

TTL und valid bewusst festlegen

Der Resolver-Cache von NGINX richtet sich ohne eine zusätzliche Vorgabe nach der DNS-TTL in der Antwort des abgefragten Nameservers. Ändert der autoritative DNS-Betreiber die IP-Adresse eines Backends, nutzt NGINX die bisherige Antwort bis zu deren TTL-Ablauf. Erst wenn danach wieder eine Namensauflösung erforderlich ist, fragt NGINX den Resolver erneut ab. Damit bleibt die Gültigkeitsdauer dort steuerbar, wo die Namensdaten gepflegt werden.

Der Parameter valid ersetzt diese TTL vollständig durch den konfigurierten Zeitraum. Er begrenzt die DNS-TTL also nicht nur nach oben und definiert auch kein regelmäßiges Auffrischen zusätzlich zur TTL. Ein Wert von valid=30s kann eine längere DNS-TTL verkürzen, aber ebenso eine bewusst kurze TTL verlängern. Das muss zur Umzugs- und Deployment-Planung des Backends passen.

Wenn die Zone verlässlich gepflegt wird, ist eine Konfiguration ohne Override die nachvollziehbare Ausgangsbasis. Die Adresse im Beispiel ist gemäß den Dokumentationsnetzen gewählt und darf nicht als produktiver Resolver übernommen werden. Trage stattdessen die Adresse eines erreichbaren und vertrauenswürdigen DNS-Resolvers aus dem eigenen Netzwerk ein.

resolver 192.0.2.53;
resolver_timeout 5s;

Ein Override kann sinnvoll sein, wenn die DNS-TTL nicht beeinflussbar ist und eine dokumentierte betriebliche Vorgabe existiert. Dann macht die Abweichung ausdrücklich sichtbar, wie lange NGINX Antworten hält. Sie ist keine allgemeine Leistungsoptimierung: Kürzere Zeiten können mehr DNS-Abfragen auslösen, längere Zeiten können den Wechsel auf neue Backend-Adressen verzögern.

resolver 192.0.2.53 valid=30s;
resolver_timeout 5s;

Die Entscheidung beginnt daher nicht mit einer festen Sekundenangabe, sondern mit der Frage, wer DNS-Daten kontrolliert und wie schnell ein Backend-Wechsel wirksam werden muss. valid ist ein bewusster Eingriff in diese Regelung. Er eignet sich nicht als pauschaler Schalter, um den Reverse Proxy schneller zu machen oder DNS-Probleme zu verdecken.

Variablen in proxy_pass korrekt auflösen

Enthält proxy_pass eine Variable, muss NGINX den resultierenden Hostnamen zur Laufzeit behandeln. Zunächst sucht NGINX nach einer passenden Upstream-Gruppe; findet es keine, benötigt es für den Namen einen konfigurierten Resolver. Fehlt dieser, ist die typische Meldung no resolver defined kein Hinweis auf einen HTTP-Cache, sondern auf die fehlende DNS-Konfiguration für diesen Ausführungspfad.

Das folgende Muster macht die Laufzeitauflösung bewusst sichtbar. Der Resolver steht im http-Kontext und gilt dadurch für mehrere virtuelle Hosts, sofern keine spezifischere Einstellung ihn überschreibt. Die verwendete Dokumentationsadresse muss durch den internen Resolver der jeweiligen Umgebung ersetzt werden.

http {
    resolver 192.0.2.53;
    resolver_timeout 5s;

    server {
        listen 80;

        location / {
            set $backend api.internal.example;
            proxy_pass http://$backend;
        }
    }
}

Die Direktive resolver_timeout steuert nicht die Cache-Dauer. Sie begrenzt, wie lange NGINX auf eine Namensauflösung wartet; der dokumentierte Standard beträgt 30 Sekunden. Die Wahl gehört zu den übrigen Fehlerbudgets: Ein zu hoher Wert kann eine fehlgeschlagene Anfrage bis zur Fehlerantwort verzögern, ein zu niedriger Wert erzeugt bei zeitweise langsamen internen Resolvern vermeidbare Auflösungsfehler.

Für einen einzelnen, klar abgegrenzten Standort kann der Resolver im location-Block stehen. Benötigen mehrere Locations oder Server dieselbe Auflösung, ist ein gemeinsamer Scope im server– oder http-Block wartungsärmer. NGINX erlaubt die Direktive in allen drei Kontexten; der Geltungsbereich sollte die tatsächliche Betriebsstruktur abbilden, nicht nur eine einzelne Fehlermeldung kurzfristig beseitigen.

Auch bei variablen Zielen bleiben DNS-Timeout und Verbindung zum Backend getrennte Fehlerklassen. Eine erfolgreiche Namensauflösung beweist weder, dass der Zielport erreichbar ist, noch dass die Anwendung antwortet. Umgekehrt behebt ein höherer Upstream-Timeout keine nicht erreichbare Resolver-Adresse.

Dynamische Upstreams mit resolve konfigurieren

Für eine benannte Backend-Gruppe kann ein dynamischer Upstream lesbarer sein als ein variabler Zielwert in jeder Location. Das Muster trennt die Definition der Backend-Mitglieder vom Routing: proxy_pass verweist auf die Gruppe, während der Hostname im Upstream über DNS aktualisiert werden kann. Das ist besonders passend, wenn mehrere Routen dieselbe Anwendung ansprechen.

Der Parameter resolve für einen server-Eintrag existiert historisch seit NGINX 1.5.12. In NGINX Open Source ist er laut Dokumentation jedoch erst ab Version 1.27.3 verfügbar; zuvor war diese Funktion kommerziell beschränkt. Auch die Resolver-Konfiguration direkt im upstream-Block ist für Open Source ab 1.27.3 dokumentiert.

Die Shared-Memory-Zone ist dabei kein Cache-Timeout und kein DNS-Datenpfad. Sie stellt innerhalb von NGINX gemeinsamen Speicher bereit, den dynamisch veränderte Upstream-Konfigurationen benötigen. Erkennt NGINX bei der DNS-Auflösung andere Adressen für den Namen, kann die Upstream-Gruppe anhand dieses intern verwalteten Zustands ohne Neustart angepasst werden.

http {
    resolver 192.0.2.53;
    resolver_timeout 5s;

    upstream application_pool {
        zone application_pool 64k;
        server app.internal.example resolve;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://application_pool;
        }
    }
}

Wie bei allen Beispielen steht 192.0.2.53 nur für eine Dokumentationsadresse. In der Praxis muss der eingetragene Resolver interne Namen zuverlässig kennen, aus dem NGINX-Netz erreichbar sein und als vertrauenswürdig gelten. Vor der Übernahme ist außerdem der tatsächliche Funktionsumfang des installierten Pakets zu prüfen, statt die Konfiguration allein aus einem aktuellen Beispiel abzuleiten.

Ein Dienst, der ausschließlich über IPv4 erreichbar ist, kann eine gezielte Einschränkung rechtfertigen: resolver 192.0.2.53 ipv6=off; verhindert AAAA-Abfragen und die Auswahl einer IPv6-Adresse für diesen Resolver-Kontext. Das ist jedoch eine Netzarchitekturentscheidung. Bei funktionierendem Dual Stack sollte IPv6 nicht allein aus Gewohnheit deaktiviert werden; standardmäßig löst NGINX beide IP-Familien auf.

Konfiguration sicher prüfen und ausrollen

Vor einer Änderung prüfst du zunächst, an welcher Stelle die Resolver-Direktiven tatsächlich gelten. Suche dazu die aktive Konfiguration einschließlich eingebundener Dateien und kläre, ob der Resolver für das gesamte http-Kontext, nur für einen virtuellen Host oder lediglich für einen einzelnen Pfad vorgesehen ist. Ein zu enger Scope kann dazu führen, dass ein anderer variabler Proxy-Pfad keinen Resolver findet; ein zu weiter Scope erschwert dagegen die spätere Zuordnung von Änderungen.

Nach jeder Anpassung folgt der Syntaxcheck. Er liest die Konfiguration ein und versucht auch, referenzierte Dateien zu öffnen. Damit lassen sich Schreibfehler, ungültige Direktiven und Probleme in Include-Dateien vor einem Reload erkennen. Der Check beweist jedoch nicht, dass der eingetragene DNS-Server erreichbar ist, den erwarteten Namen kennt oder das Backend hinter einer aufgelösten Adresse Verbindungen annimmt.

nginx -t
nginx -s reload

Führe den Reload erst nach erfolgreicher Prüfung aus. nginx -s reload veranlasst NGINX, neue Worker mit der neuen Konfiguration zu starten und alte Worker kontrolliert zu beenden. Abhängig vom installierten Paket und Betriebssystem kann stattdessen der dort vorgesehene Service-Manager den Reload auslösen. Verwende dafür den dokumentierten Betriebsweg der Installation, statt Befehle aus einer fremden Umgebung zu übernehmen.

Plane anschließend eine fachliche Prüfung im vorgesehenen Änderungsfenster. Vergleiche die erwartete DNS-TTL mit dem Zeitpunkt, ab dem eine neue Backend-Adresse genutzt werden soll, und prüfe die Erreichbarkeit des Dienstes über die tatsächlich erlaubte IP-Familie. Dokumentiere außerdem Resolver-Adresse, gewählten Scope und ein mögliches valid-Override. So lässt sich bei einer Störung unterscheiden, ob DNS, Routing oder die Anwendung die Ursache ist.

Typische Resolver-Fehler systematisch eingrenzen

Beginne die Fehlersuche beim Zielausdruck in proxy_pass. Enthält er eine Variable, muss NGINX den darin enthaltenen Hostnamen zur Laufzeit auflösen, sofern dieser nicht zu einer definierten Upstream-Gruppe gehört. Die Meldung no resolver defined weist daher zunächst auf eine fehlende oder im wirksamen Kontext nicht sichtbare Resolver-Konfiguration hin. Ergänze einen vertrauenswürdigen Nameserver im passenden Kontext, statt den Hostnamen vorschnell durch eine feste IP zu ersetzen.

Ist ein Resolver konfiguriert, prüfst du als Nächstes dessen Adresse, Netzweg und Zuständigkeit für die verwendete Zone. Ein öffentlicher Resolver kann interne Namen nicht kennen; ein nicht erreichbarer Resolver erzeugt dagegen Auflösungs-Timeouts. Kontrolliere außerdem, ob die Direktive durch eine spezifischere Einstellung überschrieben wird. NGINX verwendet nur die ausdrücklich angegebenen Nameserver, nicht automatisch sämtliche Einstellungen aus /etc/resolv.conf.

Bleibt nach einem DNS-Wechsel eine alte Zieladresse aktiv, kontrolliere die Antwort-TTL und ein gesetztes valid. Ein langer Override ersetzt die TTL der DNS-Antwort und kann die Übernahme einer Änderung entsprechend verzögern. Die zulässige Korrektur ist keine pauschal möglichst kurze Dauer, sondern ein Wert, der zum Änderungsfenster und zur Belastbarkeit der DNS-Infrastruktur passt; oft ist das Weglassen von valid die sauberere Lösung.

Bei Verbindungsproblemen nach erfolgreicher Auflösung trennst du DNS von der Backend-Verbindung. Prüfe, ob A- und AAAA-Antworten vorliegen und ob das Ziel über IPv6 tatsächlich geroutet und erreichbar ist. ipv6=off ist nur für einen nachweislich IPv4-only betriebenen Architekturfall geeignet. Ein DNS-Timeout betrifft die Namensauflösung; ein Verbindungsfehler zur bereits bekannten IP verweist dagegen auf Routing, Firewall, Port oder Anwendung.

Für dynamische Upstreams müssen außerdem Versionsstand, Shared-Memory-Zone und resolve zusammenpassen. Die hierfür dokumentierte Open-Source-Unterstützung gilt ab NGINX 1.27.3; ältere Installationen dürfen nicht als gleichwertig behandelt werden. status_zone und API-basierte Resolver-Statistiken sind zudem keine allgemeine Monitoring-Lösung für NGINX Open Source, da die genannten Funktionen kommerziellen Umfang betreffen.

Resolver-Strategie für den Betrieb wählen

Die passende Strategie beginnt nicht mit einem pauschalen Cache-Wert, sondern mit DNS-Hoheit und Änderungsrate. Kann dein Team die autoritative Zone pflegen und bilden deren TTLs das Deployment-Fenster realistisch ab, ist eine TTL-gesteuerte Auflösung ohne valid meist der nachvollziehbarste Ausgangspunkt. DNS bleibt dann die maßgebliche Quelle dafür, wie lange eine Antwort verwendet wird.

Ein bewusst gesetztes valid kommt infrage, wenn du die TTL nicht beeinflussen kannst und eine abweichende Cache-Dauer betrieblich begründen kannst. Halte dabei fest, welche Ausfallfolge akzeptabel ist: Ein längerer Wert senkt mögliche DNS-Abfragen, kann aber nach einem Umzug auf eine nicht mehr passende Adresse zeigen. Er ist weder eine Obergrenze für die DNS-TTL noch ein allgemeiner Performance-Schalter.

Wähle das NGINX-Muster danach anhand der Routing-Struktur. Ein variabler proxy_pass eignet sich, wenn das Ziel pro Anfrage oder Konfiguration zur Laufzeit bestimmt wird; dafür ist ein Resolver im passenden Scope erforderlich. Für eine benannte Backend-Gruppe mit DNS-basierten Adressänderungen ist ein Upstream mit zone und resolve klarer, sofern NGINX Open Source 1.27.3 oder neuer tatsächlich verfügbar ist.

Erst anschließend bestimmst du Timeouts und IP-Familien. Der Resolver-Timeout muss zu Client- und Upstream-Timeouts passen, damit eine ausbleibende DNS-Antwort Fehler nicht unverhältnismäßig verzögert. IPv4 oder IPv6 schaltest du nur entsprechend der Netzarchitektur frei. Verwende ausschließlich abgesicherte Resolver, die interne Zonen zuverlässig beantworten können.

DNS-Auflösung und Upstream-Keepalive lösen unterschiedliche Aufgaben. Der Resolver entscheidet, welche Backend-Adresse NGINX verwenden kann; Keepalive hält bereits aufgebaute, inaktive Backend-Verbindungen zur Wiederverwendung vor. Eine Änderung an der Verbindungswiederverwendung ersetzt daher weder TTL-Planung noch Resolver-Prüfung. Für die Dimensionierung dieser Verbindungsebene ergänzt der Beitrag zu NGINX Upstream Keepalive die Resolver-Strategie.