Migration von Nginx zu Caddy + Coraza WAF

Stellen Sie vor der Migration sicher, dass Ihre Gründe stichhaltig sind. Hier sind die validen:

• Wartungsaufwand von ModSecurity: ModSecurity aus dem Quellcode zu kompilieren, Konflikte mit C-Bibliotheken zu lösen und mit Sicherheitspatches Schritt zu halten, ist eine fortlaufende Arbeit. Coraza hat keinerlei C-Abhängigkeiten.
• EOL-Kurs von ModSecurity: seit Trustwave ModSecurity im Januar 2024 an die OWASP-Community übergeben hat, hat sich die Entwicklung deutlich verlangsamt. Bei Coraza findet die Entwicklung neuer WAF-Engines statt.
• Automatisches HTTPS: Caddy verwaltet Let's-Encrypt-Zertifikate automatisch. Keine certbot-Cronjobs, keine Erneuerungsskripte, keine Vorfälle mit abgelaufenen Zertifikaten.
• Einfachere Konfiguration: eine typische Nginx-Konfiguration lässt sich in Caddy mit einem Drittel der Zeilen abbilden. Weniger Konfiguration bedeutet weniger Fehler.
• Docker-nativ: Caddy + Coraza läuft als einzelner Container, ohne per Volume eingebundene Module oder mehrstufige Builds für ModSecurity.

Migrieren Sie nicht, wenn:

• Ihr Nginx-Setup komplex ist (starke Nutzung von Lua, njs, proxy_cache oder Stream-Modulen) und einwandfrei funktioniert
• Sie auf Funktionen von Nginx Plus angewiesen sind (Live-Dashboard, aktive Health Checks, die über das hinausgehen, was Caddy bietet)
• Ihr Team über tiefgreifende Nginx-Expertise verfügt und kein Interesse daran hat, Caddy zu lernen
• Sie eine große Flotte an Nginx-Servern betreiben und die Migrationskosten den Nutzen übersteigen

Bevor Sie irgendeine Konfiguration anfassen, inventarisieren Sie, was Sie haben:

1. Alle Sites und Konfigurationen auflisten

# Alle aktivierten Sites auflisten
ls /etc/nginx/sites-enabled/

# Alle Konfigurationsdateien finden, die tatsächlich geladen werden
nginx -T 2>/dev/null | grep "# configuration file" | sort -u

# Server-Blöcke zählen
grep -r "server_name" /etc/nginx/sites-enabled/ | sort

2. Ihre Upstream-Dienste dokumentieren

# Alle proxy_pass-Ziele finden
grep -rh "proxy_pass" /etc/nginx/sites-enabled/ | sort -u

3. Auf Funktionen prüfen, die eine Sonderbehandlung benötigen

# Lua-Module
grep -r "lua_" /etc/nginx/ | head

# Stream/TCP-Proxying
grep -r "stream" /etc/nginx/nginx.conf

# Cache-Zonen
grep -r "proxy_cache" /etc/nginx/ | head

# Rate Limiting
grep -r "limit_req" /etc/nginx/ | head

# Benutzerdefinierte Maps
grep -r "^[[:space:]]*map" /etc/nginx/ | head

4. Ihr SSL-Zertifikat-Setup notieren

# Zertifikatspfade finden
grep -r "ssl_certificate" /etc/nginx/sites-enabled/ | sort -u

# Prüfen, ob certbot sie verwaltet
ls /etc/letsencrypt/live/ 2>/dev/null

Speichern Sie dieses Inventar. Sie werden es während der Umstellung heranziehen und es nach der Migration als Verifizierungscheckliste verwenden.

Verwenden Sie die Tabelle zur Direktiven-Zuordnung aus unserem Nginx WAF Protection Guide, um jede Site-Konfiguration umzustellen. Nutzen Sie für komplexe Konfigurationen den KI-gestützten Umstellungs-Prompt aus jenem Guide.

Wichtige Umstellungsregeln:

• Jeder Nginx-server { }-Block wird zu einem Caddy-Site-Block: example.com { }
• proxy_pass wird zu reverse_proxy
• root + index + try_files wird zu root * /path + file_server
• Die SSL-Konfiguration entfällt vollständig (Caddy auto-HTTPS), sofern Sie keine benutzerdefinierten Zertifikate verwenden
• HTTP-zu-HTTPS-Weiterleitungen entfallen (in Caddy automatisch)
• add_header wird zu header
• location /path { } wird zu handle /path/* { } oder zu benannten Matchern

Fügen Sie jeder Site den Coraza-WAF-Block hinzu:

{
    order coraza_waf first
}

example.com {
    coraza_waf {
        load_owasp_crs
        directives `
        Include @coraza.conf-recommended
        Include @crs-setup.conf.example
        Include @owasp_crs/*.conf
        SecRuleEngine On
        `
    }

    # ... hier Ihre umgestellte Konfiguration ...
}

Stellen Sie die Produktion niemals ohne vorherigen Test um. So gehen Sie vor:

1. Das Caddy+Coraza-Image bauen

FROM caddy:2-builder AS builder
RUN xcaddy build --with github.com/corazawaf/coraza-caddy/v2

FROM caddy:2
COPY --from=builder /usr/bin/caddy /usr/bin/caddy

docker build -t caddy-coraza .

2. Die Syntax Ihres Caddyfile validieren

docker run --rm \
  -v ./Caddyfile:/etc/caddy/Caddyfile:ro \
  caddy-coraza caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile

3. Lokal ausführen und jede Site testen

docker run -d --name caddy-test -p 8443:443 -p 8080:80 \
  -v ./Caddyfile:/etc/caddy/Caddyfile:ro \
  -v ./site:/srv:ro \
  -v caddy_data:/data \
  caddy-coraza

4. Anhand Ihrer Inventar-Checkliste überprüfen

Überprüfen Sie für jeden Punkt in Ihrem Pre-Migration-Inventar:

• Statische Dateien werden korrekt geladen
• Reverse-Proxy-Ziele antworten
• Weiterleitungen funktionieren wie erwartet
• Header werden korrekt gesetzt (mit curl -I prüfen)
• Die WAF blockiert Angriffs-Payloads (SQLi, XSS, Scanner-Probes)
• Die WAF blockiert NICHT den legitimen Anwendungs-Datenverkehr

Schalten Sie bei Produktionsmigrationen nicht den gesamten Datenverkehr auf einmal um. Verwenden Sie einen dieser Ansätze:

Option 1: DNS-basierter Cutover (am einfachsten)

1. Betreiben Sie Caddy+Coraza auf einem separaten Host oder Port
2. Senken Sie die DNS-TTL einige Tage vorher auf 60 Sekunden
3. Verweisen Sie das DNS auf die Caddy-Instanz
4. Überwachen Sie 1 bis 2 Stunden lang auf Fehler
5. Bei Problemen: verweisen Sie das DNS zurück auf Nginx (wird innerhalb von 60 Sekunden wirksam)

Option 2: Load-Balancer-Aufteilung (sicherer)

1. Betreiben Sie sowohl Nginx als auch Caddy hinter einem Load Balancer
2. Senden Sie 10 % des Datenverkehrs an Caddy
3. Überwachen Sie Fehlerraten und Antwortzeiten
4. Erhöhen Sie schrittweise auf 25 %, 50 %, 100 %
5. Nehmen Sie Nginx außer Betrieb, sobald 100 % stabil sind

Option 3: Migration pro Site (für Multi-Site-Setups)

1. Migrieren Sie zuerst die Site mit dem geringsten Datenverkehr
2. Betreiben Sie sie einige Tage lang auf Caddy
3. Wenn stabil, migrieren Sie die nächste Site
4. Fahren Sie fort, bis alle Sites auf Caddy laufen

Dinge, die Sie vor Beginn des Cutovers bereithalten müssen:

• Backup der Nginx-Konfiguration: bewahren Sie eine vollständige Kopie Ihrer Nginx-Konfiguration, der SSL-Zertifikate und aller benutzerdefinierten Module auf
• Nginx läuft weiterhin: stoppen Sie Nginx nicht, bevor Caddy tagelang stabil war. Betreiben Sie beide möglichst parallel.
• DNS-TTL gesenkt: stellen Sie bei einem DNS-basierten Cutover sicher, dass die TTL vor dem Umschalten 60 Sekunden beträgt
• Monitoring-Alerts: richten Sie Alerts für steigende 5xx-Fehlerraten, Ausschläge bei den Antwortzeiten und WAF-False-Positive-Raten ein

Rollback-Vorgehen:

1. Verweisen Sie den Datenverkehr zurück auf Nginx (DNS-Änderung, Load-Balancer-Umschaltung oder Port-Remapping)
2. Überprüfen Sie, ob Nginx den Datenverkehr korrekt bedient
3. Untersuchen Sie, was beim Caddy-Setup schiefgelaufen ist
4. Beheben und erneut testen, bevor Sie einen weiteren Cutover-Versuch unternehmen

Der Rollback sollte weniger als 2 Minuten dauern, wenn Sie Nginx parallel am Laufen gehalten haben.

Sobald Caddy mindestens eine Woche lang stabil im Produktivbetrieb gelaufen ist:

• Entfernen Sie die certbot-Cronjobs (Caddy übernimmt die TLS-Erneuerung automatisch)
• Nehmen Sie die Nginx-Instanz außer Betrieb
• Aktualisieren Sie Deployment-Skripte und CI/CD-Pipelines
• Stellen Sie das Monitoring auf die Logs und Metriken von Caddy um
• Archivieren Sie die Nginx-Konfiguration (löschen Sie sie noch nicht, behalten Sie sie als Referenz)

Überwachen Sie im ersten Monat die WAF-Logs. CRS-Regeln können bei Anwendungs-Datenverkehr, den Nginx nicht inspiziert hat, False Positives auslösen. Feintuning erfolgt bei Bedarf mit SecRuleRemoveById-Direktiven.