nginx-Config-Generator: HTTP/3, WebSocket, Security

Was macht der nginx-Config-Generator?

Der Generator ist ein Editor für nginx-Server-Blocks. Du wählst aus acht Block-Typen (statisches Hosting, SPA-Fallback, Reverse-Proxy, PHP-FPM, Load-Balancer, reine Weiterleitung, TCP-Stream, UDP-Stream), passt Felder wie server_name, root und upstream an, und der Generator setzt alle nötigen Direktiven in der korrekten Reihenfolge zusammen. Optional kannst du eine bestehende .htaccess einfügen, der Generator übersetzt Redirects, Rewrites, Header und ErrorDocuments automatisch in nginx-Direktiven. Alles passiert im Browser. Kein Upload, kein Account, kein Cookie-Banner.

Die sechs Voreinstellungen decken die häufigsten Stack-Konstellationen ab:

• SPA (statisches Hosting): Single-Page-App mit Astro/SvelteKit/Vite, Long-Cache für gehashte Assets, Fallback auf index.html, HTTP/3 aktiv.
• Node.js (Reverse-Proxy): Node-/Bun-Server hinter nginx mit korrekt verdrahtetem WebSocket-Upgrade.
• Python (Uvicorn/ASGI): FastAPI oder Starlette via Uvicorn, Rate-Limit „API”.
• WordPress (PHP-FPM): PHP-FPM über Unix-Socket, wp-config.php und .env gesperrt.
• Strict HTTPS (Audit-A): auf Mozilla-Observatory-A getrimmt, TLS 1.3, COOP/COEP/CORP.
• Load-Balancer (least_conn): nginx vor drei Backend-Knoten, Health-Failover über max_fails.

Welche Server-Block-Typen sind eingebaut?

Acht Block-Typen, gegliedert nach Anwendungsfall:

• Statisches Hosting: try_files $uri $uri/ =404;. Klassisch für Hugo, 11ty, plain HTML.
• SPA-Fallback: try_files $uri $uri/ /index.html; plus Long-Cache für gehashte Assets. Standard für jede Client-Side-Routing-App.
• Reverse-Proxy: proxy_pass auf eine Upstream-URL, mit allen üblichen X-Forwarded-*-Headern. Optional WebSocket-Upgrade.
• PHP-FPM: fastcgi_pass auf einen Unix-Socket, mit try_files-Permalinks und Deny-Regeln für wp-config.php, .env, .git.
• Load-Balancer: proxy_pass http://backend_pool; plus das passende upstream-Block-Template (auskommentiert, weil upstream {} außerhalb von server {} liegt).
• Reine Weiterleitung: return 301 https://www.example.com$request_uri;. Für www-Canonical- Umleitungen und Domain-Migrations.
• TCP-Stream: für stream {}-Scope, z. B. Postgres-/Redis-Proxying. Der Block kommentiert den Scope-Wechsel.
• UDP-Stream: analog für DNS oder QUIC-Forward.

Wie funktioniert die HTTP/3- und QUIC-Unterstützung?

HTTP/3 löst HTTP/2 ab und nutzt QUIC statt TCP als Transport. QUIC ist UDP-basiert, verlagert TLS in den Connection-Setup und eliminiert das Head-of-Line-Blocking von HTTP/2. nginx hat QUIC seit Version 1.25 im offiziellen Build (vorher nur im nginx-quic-Branch). Der Generator emittiert vier Direktiven, sobald du HTTP/3 aktivierst:

listen 443 quic reuseport;
listen [::]:443 quic reuseport;
http3 on;
ssl_early_data on;
add_header Alt-Svc 'h3=":443"; ma=86400' always;

Der Alt-Svc-Header signalisiert Browsern, dass HTTP/3 auf Port 443 verfügbar ist; ma=86400 cached diese Information für 24 Stunden. Browser, die HTTP/3 noch nicht beherrschen, ignorieren den Header und bleiben auf HTTP/2.

Was macht die WebSocket-Upgrade-Korrektheit aus?

WebSocket-Reverse-Proxying bricht in den meisten naiven nginx-Configs, weil der Connection-Upgrade fehlt. Der korrekte Pattern besteht aus vier Teilen:

1. map-Direktive auf http {}-Scope, übersetzt den vom Client gesendeten Upgrade-Header in einen passenden Connection-Wert:

   map $http_upgrade $connection_upgrade {
     default upgrade;
     ''      close;
   }

2. proxy_set_header Upgrade $http_upgrade;, reicht das Upgrade-Signal an den Backend-Server.
3. proxy_set_header Connection $connection_upgrade;, überschreibt das standardmäßige Connection: close, das nginx sonst beim Reverse-Proxying setzt.
4. proxy_read_timeout 86400s;, setzt das Read-Timeout auf 24 Stunden, damit Idle-WebSockets nicht nach 60 Sekunden (nginx-Default) getrennt werden.

Der Generator wickelt alle vier automatisch ein, sobald du die WebSocket-Checkbox in einem Reverse- Proxy- oder Load-Balancer-Block aktivierst. Das ist der häufigste Pain-Point in WebSocket-Setups, und der Hauptgrund für „warum bricht meine Verbindung ständig ab”-Bugs in Foren.

Welche Sicherheits-Header werden emittiert?

Sechs Header gehören in jeden modernen nginx-Block (siehe Mozilla Web Security Guidelines):

• Strict-Transport-Security: HSTS mit max-age=31536000; includeSubDomains; preload. Preload ist standardmäßig aktiv, ein Toggle erlaubt das Abschalten für Sub-Domains, die nicht ohne HTTP funktionieren.
• Content-Security-Policy: Starter-Wert mit default-src 'self', frame-ancestors 'none'. Toggle für Report-Only-Modus während der Einführung.
• Permissions-Policy: alles aus per Default (camera=(), microphone=(), geolocation=(), payment=(), usb=(), interest-cohort=(), browsing-topics=()).
• Cross-Origin-Opener-Policy: same-origin gegen window.opener-Attacken.
• Cross-Origin-Embedder-Policy: optional require-corp für SharedArrayBuffer-Use-Cases.
• Cross-Origin-Resource-Policy: same-origin blockiert Cross-Origin-Embeds eigener Assets.

Jeder Header trägt das always-Flag. Ohne always droppt nginx Header auf 4xx/5xx-Antworten, was viele Audit-Tools (Mozilla Observatory, securityheaders.com) als A-Level-Verstoß werten. Vor dem Deploy die CSP am externen CSP-Evaluator prüfen.

Wie funktioniert das Rate-Limit-Profil?

nginx-Rate-Limiting kombiniert zwei Direktiven:

• limit_req_zone auf http {}-Scope, reserviert Shared-Memory und definiert die Rate.
• limit_req zone=<name> burst=<n> nodelay; im Location-Block, referenziert die Zone.

Häufiger Fehler in publikem Online-Generatoren: Die Zone wird emittiert, aber die Location-Reference fehlt, die Zone bleibt komplett ungenutzt (siehe das offene Issue im populärsten Online-Generator). Der Generator emittiert beide zusammen und injiziert die Reference in den ersten location-Block des Server-Blocks. Drei Profile:

• Gentle: 30 r/s, burst 50, limit_conn 100. Für normale Webseiten mit echtem Nutzer-Traffic.
• API: 10 r/s, burst 20, limit_conn 50. Für REST-/GraphQL-APIs mit Token-basiertem Throttling.
• Strict: 5 r/s, burst 10, limit_conn 20. Für Login-Endpunkte, Webhook-Receiver, kritische Routen.

burst definiert, wie viele Requests zusätzlich zur Rate akzeptiert werden, bevor 429-Antworten fliegen. nodelay heißt: Burst-Requests werden sofort verarbeitet, nicht über die Rate gepuffert. Ohne nodelay würde nginx einen Burst-Request künstlich verzögern, was im Praxis-Use-Case meistens nicht das gewünschte Verhalten ist.

Was macht der .htaccess-zu-nginx-Konverter?

Apache und nginx haben unterschiedliche Konfigurations-Modelle: Apache liest .htaccess pro Request neu (kostet Performance, aber gibt Flexibilität), nginx parst seine Konfiguration einmal beim Reload (schneller, aber kein Per-Request-Override). Eine vollständige 1:1-Konvertierung gibt es nicht, aber die wichtigsten Direktiven sind mappbar:

Apache	nginx
Redirect 301 /old /new	rewrite ^/old$ /new permanent;
Redirect 302 /a /b	rewrite ^/a$ /b redirect;
RewriteRule ^foo$ /bar [L]	rewrite ^foo$ /bar last;
RewriteRule … [R=301,L]	rewrite … permanent;
Header always set X-Frame-Options DENY	add_header X-Frame-Options "DENY" always;
ErrorDocument 404 /404.html	error_page 404 /404.html;
Options -Indexes	autoindex off;
Require ip 192.168.1.1	allow 192.168.1.1;
Deny from 203.0.113.4	deny 203.0.113.4;
<IfModule>	wird flach kommentiert (nginx hat kein Module-Conditional)

Nicht-mappbare Direktiven kommen als # TODO (could not convert): …-Kommentar zurück. Der Konverter ist deterministisch, gleicher Input liefert immer gleichen Output, kein KI-Rate-Limit, keine Cloud-Roundtrips. Der Hinweis am Anfang („paste inside your nginx server { ... } block”) ist Pflicht-Lese-Stoff, die emittierten Direktiven gehören in den richtigen Scope.

Welche Pain-Points umgehe ich mit diesem Generator?

Vier Klassiker, die in nginx-Tutorials immer wieder auftauchen, und die der Generator vermeidet:

1. WebSocket bricht nach 60 Sekunden: die häufigste Ursache ist das fehlende proxy_read_timeout 86400s; plus die unkorrekten Upgrade-Header. Der Generator setzt beides automatisch.
2. Rate-Limit-Zone ohne Reference: die limit_req_zone wird emittiert, aber limit_req im Location-Block fehlt. Wirkung: Null. Der Generator emittiert beide zusammen.
3. Security-Header verschwinden auf Fehler-Seiten: ohne always droppt nginx Header auf 4xx/5xx-Responses. Der Generator setzt always auf jeden add_header.
4. HTTP/3 falsch konfiguriert: fehlendes reuseport, fehlendes ssl_early_data, kein Alt-Svc-Header. Der Generator emittiert alle vier Direktiven, sobald HTTP/3 aktiviert ist.

Wie ist die Privacy geregelt?

Pure-client. Der Generator läuft komplett im Browser. Es gibt keinen Server-Endpunkt für die Konfiguration-Validierung, keinen Telemetrie-Aufruf, keinen Cookie, keinen Account. Wenn du das Tab schließt, sind deine Einstellungen weg, der Generator persistiert nichts. Wer einen Verlauf braucht, lädt nach jedem Edit die nginx.conf herunter und versioniert sie im Repo.

Was ist absichtlich nicht gebaut?

• Keine Live-Validierung mit nginx -t: würde einen Server-Roundtrip oder einen WebAssembly-Port von nginx selbst benötigen. Stattdessen verweist der Generator-Header und der UI-Hinweis auf sudo nginx -t nach dem Deploy.
• Kein automatisches Let’s-Encrypt-Issuance: der Generator emittiert nur das Certbot-Webroot- Snippet. Das Aktivieren des Zertifikats braucht Server-Zugriff und ist außerhalb des Browser-Scopes.
• Kein Nginx-Proxy-Manager-GUI-Modus: wer einen GUI-First-Workflow will, nutzt Nginx Proxy Manager direkt. Dieser Generator ist für Devs, die Konfiguration als Code halten.
• Keine ngx_mod_security-Regeln: WAF-Tuning ist ein eigenes Tool (zu spezialisiert, zu ruleset-spezifisch).
• Keine Apache-2.2-Variante: .htaccess 2.2 deckt das Schwester-Tool htaccess-generator ab.
• Kein Caching-Profil-Editor: die emittierten gzip-Defaults und die Long-Cache-Regel im SPA-Block reichen für den 90-%-Use-Case.

Wo finde ich mehr Details?

• nginx-Dokumentation: offizielle Direktiven-Referenz
• nginx auf Wikipedia: Geschichte, Architektur, Einsatzgebiete
• Mozilla SSL Configuration Generator: TLS-Profile-Referenz
• hstspreload.org: Submission-Liste für HSTS-Preload-Domains
• CSP Evaluator: externer Validator für Content-Security-Policy
• RFC 9114 (HTTP/3), HTTP/3-Spezifikation
• Cloudflare Learning Center, WebSocket, WebSocket-Protokoll-Grundlagen