Home 🔄 Migration 001: Traefik ab v3.6 mit CrowdSec installieren und konfigurieren

🔄 Migration 001: Traefik ab v3.6 mit CrowdSec installieren und konfigurieren

von psycho0verload
von psycho0verload

Diese Anleitung richtet sich an alle, die den Artikel bereits umgesetzt haben. Stand: 15. März 2025 (Version 0.1.0).

🔍 Musst du etwas tun?

Mit dem Update auf Version 0.1.1 wurde die Art, wie das CrowdSec-Plugin seinen API-Key und seine Einstellungen bekommt, grundlegend geändert. Statt fester Werte direkt in der YAML-Konfiguration werden die Werte jetzt über Umgebungsvariablen (kurz: Variablen in der .env-Datei) an das Plugin übergeben. Außerdem wurde das Bouncer-Plugin auf Version v1.5.1 aktualisiert und die WAF-Konfiguration (Web Application Firewall) angepasst.

Dein Setup ist betroffen, wenn du Folgendes umgesetzt hast:

  • Du hast die Middleware-Datei http.middlewares.crowdsec.plugin.yml aus dem Artikel angelegt
  • Du hast die .env-Datei im Traefik-Verzeichnis konfiguriert
  • Du nutzt optional die WAF-Funktion (Kapitel 13.1)

✅ Nicht betroffen? Du musst nichts tun.

⚠️ Betroffen? Lies weiter 👇

📋 Übersicht der Änderungen

#Was hat sich geändertDringlichkeitKapitel
1Neue Variablen in der Traefik .env ergänzen🔴 NotwendigKapitel 7.3.4: .env-Datei für Traefik
2Middleware-Konfiguration auf Template-Variablen umstellen (Plugin-Version auf v1.5.1)🔴 NotwendigKapitel 7.4.3: Konfiguration von http.middlewares.*
3WAF-Konfiguration angepasst (nur bei aktiver WAF relevant)🟡 EmpfohlenKapitel 13.1: WAF mit CrowdSec AppSec

🔴 Notwendig = ohne Update funktioniert das CrowdSec-Plugin nicht mehr korrekt
🟡 Empfohlen = Verbesserung, kein Zwang
🟢 Optional = nice to have

🛠️ Was musst du anpassen?

Schritt 1: Neue Variablen in die Traefik .env eintragen

📖 Kapitel im Artikel: Kapitel 7.3.4: .env-Datei für Traefik
⏱️ Aufwand: ca. 5 Minuten
🎯 Dringlichkeit: 🔴 Notwendig

Was hat sich geändert?
Die Middleware-Konfiguration liest ihre Einstellungen ab sofort aus Umgebungsvariablen (Variablen in der .env-Datei) statt aus fest eingetragenen Werten in der YAML-Datei. Dein bestehender BOUNCER_KEY_TRAEFIK-Wert bleibt unverändert — du ergänzt nur neue Zeilen darunter.

Warum ist das wichtig?
Ohne die neuen Variablen kann die Middleware-Konfiguration (Schritt 2) die Platzhalter nicht auflösen und das CrowdSec-Plugin startet nicht korrekt.

So gehst du vor:

  1. Öffne die Traefik .env-Datei:
nano /opt/containers/traefik-crowdsec-stack/data/traefik/.env
  1. Füge die folgenden Zeilen am Ende der Datei hinzu — ersetze dabei nichts, nur ergänzen:
SERVICES_TRAEFIK_ENV_CROWDSEC_ENABLED=${SERVICES_TRAEFIK_ENV_CROWDSEC_ENABLED:-true}
SERVICES_TRAEFIK_ENV_CROWDSEC_MODE=${SERVICES_TRAEFIK_ENV_CROWDSEC_MODE:-live}
SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_ENABLED=${SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_ENABLED:-false}
SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_FAILURE_BLOCK=${SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_FAILURE_BLOCK:-true}
SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_UNREACHABLE_BLOCK=${SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_UNREACHABLE_BLOCK:-true}
SERVICES_TRAEFIK_ENV_CROWDSEC_LAPI_KEY=${BOUNCER_KEY_TRAEFIK:-}Code-Sprache: JavaScript (javascript)

💡 Tipp: Die Syntax ${VARIABLE:-Standardwert} bedeutet: „Nutze den gesetzten Wert — oder falls nicht gesetzt, den Standardwert.” So funktioniert alles auch ohne manuelle Anpassung der neuen Variablen.

💡 Tipp: Die letzte Zeile SERVICES_TRAEFIK_ENV_CROWDSEC_LAPI_KEY=${BOUNCER_KEY_TRAEFIK:-} greift automatisch auf deinen bereits vorhandenen BOUNCER_KEY_TRAEFIK-Wert zurück. Du musst den API-Key nicht erneut eintragen.

Schritt 2: Middleware-Konfiguration aktualisieren

📖 Kapitel im Artikel: Kapitel 7.4.3: Konfiguration von http.middlewares.*
⏱️ Aufwand: ca. 10 Minuten
🎯 Dringlichkeit: 🔴 Notwendig

Was hat sich geändert?
Die Datei http.middlewares.crowdsec.plugin.yml hatte bisher feste Werte direkt eingetragen (z.B. crowdsecLapiKey: DeinKey und crowdsecMode: live). Diese festen Werte werden jetzt durch Template-Platzhalter ersetzt, die Traefik beim Start automatisch aus der .env befüllt. Außerdem wurde das Bouncer-Plugin von v1.4.6 auf v1.5.1 aktualisiert und der separate Eintrag crowdsecLapiHost, crowdsecLapiScheme sowie crowdsecLapiTLSInsecureVerify entfällt.

Warum ist das wichtig?
Die alte Konfiguration mit fest eingetragenen Werten ist nicht kompatibel mit dem neuen Template-Ansatz — Traefik kann den Key nicht mehr korrekt einlesen und das Plugin verweigert den Start.

⚠️ Achtung: Führe Schritt 1 unbedingt zuerst durch, bevor du diese Datei ersetzt. Ohne die neuen Variablen in der .env bleiben die Platzhalter leer.

So gehst du vor:

  1. Öffne die Middleware-Konfigurationsdatei:
nano /opt/containers/traefik-crowdsec-stack/data/traefik/dynamic_conf/http.middlewares.crowdsec.plugin.yml
  1. Ersetze den gesamten Inhalt der Datei durch die folgende neue Konfiguration:
http:
  middlewares:
    crowdsec:
      plugin:
        bouncer:
          enabled: {{ env "SERVICES_TRAEFIK_ENV_CROWDSEC_ENABLED" }}
          crowdsecMode: {{ env "SERVICES_TRAEFIK_ENV_CROWDSEC_MODE" }}
          crowdsecAppsecEnabled: {{ env "SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_ENABLED" }}
          crowdsecAppsecFailureBlock: {{ env "SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_FAILURE_BLOCK" }}
          crowdsecAppsecUnreachableBlock: {{ env "SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_UNREACHABLE_BLOCK" }}
          crowdsecLapiKey: {{ env "SERVICES_TRAEFIK_ENV_CROWDSEC_LAPI_KEY" }}Code-Sprache: JavaScript (javascript)

💡 Tipp: Die Zeilen crowdsecLapiHost, crowdsecLapiScheme, crowdsecLapiTLSInsecureVerify, forwardedHeadersTrustedIPs und clientTrustedIPs aus der alten Konfiguration werden nicht mehr benötigt und können weggelassen werden. Der aktuelle Artikel (Kapitel 7.4.3) zeigt die vollständige neue Konfiguration falls du weitere optionale Einträge übernehmen möchtest.

✅ Prüfe ob es geklappt hat — starte den Stack neu und prüfe den Status:

cd /opt/containers/traefik-crowdsec-stack
docker compose up -d
docker compose ps

Du solltest sehen, dass der traefik-Container den Status Up ... (healthy) hat. Wenn er im Status Restarting bleibt, prüfe mit docker compose logs traefik auf Fehler in der Konfiguration.

Schritt 3: WAF-Konfiguration prüfen (nur bei aktiver WAF)

📖 Kapitel im Artikel: Kapitel 13.1: Web Application Firewall (WAF) mit CrowdSec AppSec
⏱️ Aufwand: ca. 10 Minuten
🎯 Dringlichkeit: 🟡 Empfohlen (nur relevant wenn du die WAF eingerichtet hast)

Was hat sich geändert?
Die WAF-Aktivierung (AppSec) erfolgt jetzt nicht mehr direkt in der Middleware-YAML-Datei, sondern über Variablen in der .env-Datei. Außerdem wurde die AppSec-Collection um crowdsecurity/appsec-crs erweitert und die Konfigurationsdatei für die AppSec-Regeln wurde umbenannt bzw. angepasst.

Warum ist das wichtig?
Wenn du die WAF bisher aktiv hattest (z.B. crowdsecAppsecEnabled: true stand in deiner YAML), ist diese Einstellung durch den neuen Template-Ansatz nun standardmäßig auf false gesetzt — die WAF wäre also deaktiviert, bis du die Variable in der .env explizit setzt.

So gehst du vor:

Öffne die globale .env-Datei des Stacks:

nano /opt/containers/traefik-crowdsec-stack/.env

Ergänze oder passe diese Zeilen an, um die WAF zu aktivieren:

SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_ENABLED=true
SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_FAILURE_BLOCK=true
SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_UNREACHABLE_BLOCK=trueCode-Sprache: JavaScript (javascript)

💡 Tipp: Schau dir Kapitel 13.1 im Artikel nochmals an — dort werden auch die aktualisierte AppSec-Collection (crowdsecurity/appsec-crs ist neu hinzugekommen) und die angepasste Konfigurationsdatei für AppSec-Regeln beschrieben. Diese solltest du ebenfalls auf den neuen Stand bringen.

Stack neu starten:

cd /opt/containers/traefik-crowdsec-stack
docker compose up -d

✅ Abschluss-Check

Nach allen Schritten bitte prüfen:

  • ☐ Neue Variablen in /opt/containers/traefik-crowdsec-stack/data/traefik/.env ergänzt
  • ☐ http.middlewares.crowdsec.plugin.yml enthält Template-Syntax ({{ env "..." }}) statt fester Werte
  • ☐ docker compose ps zeigt Traefik mit Status healthy
  • ☐ (Optional, nur WAF) SERVICES_TRAEFIK_ENV_CROWDSEC_APPSEC_ENABLED=true in .env gesetzt und Kapitel 13.1 erneut durchgesehen

🎉 Alles erledigt? Dein Setup läuft mit Version 0.1.1 auf dem neuesten Stand.

❓ Häufige Fragen

Muss ich meinen API-Key neu generieren?
Nein. Dein bestehender BOUNCER_KEY_TRAEFIK-Wert in der .env bleibt unverändert. Die neue Variable SERVICES_TRAEFIK_ENV_CROWDSEC_LAPI_KEY=${BOUNCER_KEY_TRAEFIK:-} liest ihn automatisch aus.

Was passiert, wenn ich die Änderungen nicht vornehme?
Die neue Middleware-Konfiguration aus Kapitel 7.4.3 enthält Template-Platzhalter ({{ env "..." }}), die ohne die passenden Variablen in der .env leer bleiben. Traefik kann den CrowdSec-Plugin-Bouncer dann nicht initialisieren — dein Setup läuft zwar weiter, aber ohne aktiven CrowdSec-Schutz.

Muss ich den sed-Befehl aus der alten Anleitung rückgängig machen?
Nein. Der sed-Befehl aus der alten Anleitung hat den Key direkt in die YAML-Datei geschrieben. Diesen Eintrag ersetzt du jetzt vollständig durch die neue Template-Konfiguration in Schritt 2 — der alte Wert wird dabei einfach überschrieben.

Autor

  • psycho0verload

    Von klein auf interessiere ich mich für verschiedene Themen im Bereich IT. Beruflich hat es mich in den medizinischen Sektor verschlagen, aber das Hobby ist geblieben. Auf der Suche nach der ein oder anderen Anleitung habe ich begonnen diese für mich selbst zu Dokumentieren und freue mich sehr darüber, dass ich auf GoNeuland mit veröffentlichen darf!

    Alle Beiträge ansehen
DSGVO Cookie Consent mit Real Cookie Banner