Traefik letsencrypt Tutorial

Mit diesem Traefik letsencrypt Tutorial möchte ich dir helfen einfach und sauber Zertifikate via freier CA Let’s Encrypt zu beantragen und zu verwalten. In diesem Tutorial gehe ich auf die Punkte http-challenge, dns-challenge sowie weiteres Zertifikatsmanagement ein. Sollte Dir ein Punkt fehlen, schreibe mir dazu gerne in Kommentare.

Solltest Du auf dieses Tutorial gestoßen sein, weil du Docker nutzt, kann ich dir meine docker-compose Sammlung auf GitHub sehr ans Herz legen. Dort sind gerade für das Thema Homelab sehr viele Softwareprodukte hinterlegt die eine direkte Traefik Anbindung realisieren. Sicherlich ist auch meine Traefik Konfiguration ein guter Startpunkt für ein gutes Gelingen.

Traefik Grundkonfiguration

Traefik lässt sich über mehrere Wege konfigurieren. Hierbei spielt es keine Rolle ob man sämtliche Befehle und Konfigurationen direkt in die docker-compose Datei oder in separate Dateien packt. Ich für meinen Teil verwende dedizierte um eine einfachere und übersichtliche Konfiguration zu haben. Solltest du einen anderen Weg bevorzugen ist dies für dieses Traefik letsencrypt Tutorial nicht wichtig. Du musst natürlich nur die Einstellungen adaptieren.

Beginnen wir mit der traefik.toml Datei. Diese beinhaltet alle notwenigen Eigenschaften um Traefik sauber ans laufen zu bekommen.

[log]
  level = "ERROR"

[providers]
  [providers.docker]
    exposedByDefault = false
    endpoint = "unix:///var/run/docker.sock"
    network = "traefik_proxy"
  [providers.file]
    filename = "/etc/traefik/dynamic.yml"
    
[api]
  dashboard = false

# https://doc.traefik.io/traefik/routing/entrypoints/#redirection
[entryPoints.web]
  address = ":80"

  [entryPoints.web.http]
    [entryPoints.web.http.redirections]
      [entryPoints.web.http.redirections.entryPoint]
        to = "websecure"
        scheme = "https"

[entryPoints.websecure]
  address = ":443"

Gehen wir die Punkt einmal durch:

[log]

Das Loglevel sollte für den produktiven Betrieb so gewählt werden, dass nach Möglichkeit nicht die Festplatte voll läuft. Für den Beginn ist es evtl. ratsam hier auf DEBUG umzustellen um mehr zu sehen und um Fehler leichter erkennen zu können.

[providers]

Wir nutzen für diese Beispielkonfiguration Docker. Wir möchten allerdings nicht, dass grundsätzlich alle Docker Container via Traefik veröffentlicht werden (exposedByDefault = false) und setzen die jeweiligen Anpassungen für jeden Container dediziert. Traefik lassen wir auf den Docker Socket hören um zu wissen was Traefik so machen muss. Gegebenenfalls musst du den Parameter „network“ anpassen. Ich nutze hierfür immer „traefik_proxy“ als Netzwerk. Möchtest du das ebenfalls nutzen musst du

docker network create traefik_proxy

ausführen und das Netzwerk anzulegen.

[api]

Das Dashboard brauchen wir hierfür nicht, wird also deaktiviert

[entryPoints]

Die entryPoints sind die Ports und Protokolle auf die Traefik hört. Stand jetzt kann Traefik nur HTTP/HTTPS Traffic. Weitere Protokolle sollen in Zukunft kommen. Wir lauschen natürlich auch auf Port 80 (HTTP) und machen eine direkte Weiterleitung auf Port 443 (HTTPS). Unverschlüsselte Kommunikation sollte nur in Ausnahmefällen noch erlaubt sein.

Wie du siehst binden wir auch eine dynamic.yml Datei ein. Diese hat folgenden Aufbau

---
tls:
  options:
    default:
      minVersion: VersionTLS12
      sniStrict: true
      cipherSuites:
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
        - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      curvePreferences:
        - CurveP521
        - CurveP384
    mintls13:
      minVersion: VersionTLS13

http:
  middlewares:
    secHeaders:
      headers:
        browserXssFilter: true
        contentTypeNosniff: true
        frameDeny: true
        sslRedirect: true
        #  HSTS Configuration
        stsIncludeSubdomains: true
        stsPreload: true
        stsSeconds: 31536000
        customRequestHeaders:
          X-Frame-Options: "SAMEORIGIN"
        customFrameOptionsValue: "SAMEORIGIN"

Die dynamic.yml ist zur Konfiguration aller Sicherheitsmerkmale gedacht. Bitte passe diese nach den aktuellen Gegebenheiten an, da sich gerade die Cipher Suites häufig ändern können! Die restlichen Werte sind nach langjähriger Erfahrung von mir so zusammen getragen und müssen nicht dem aktuellen Sicherheitsstandards entsprechend. Für Tipps bin ich aber dankbar und passe die Datei dann gerne an.

Traefik letsencrypt tlsChallenge

Mit der tlsChallange ist es wahrscheinlich die einfachste Variante Zertifikate via Let’s encrypt zu beantragen. Hier kann Traefik direkt so konfiguriert, bzw. über die Docker Konfiguration so eingerichtet werden, dass nur Port 443, also HTTPS, veröffentlicht werden muss. Möchte man nur ein paar wenige Zertifikate beantragen ist das meiner Meinung die empfehlenswerte Version.

Die Konfiguration der tlsChallenge ist ziemlich einfach. Man fügt in der traefik.toml Datei folgende Zeilen am Ende ein:

[certificatesResolvers]
  [certificatesResolvers.default.acme]
    email = "mail@example.com" #Email Adresse hier anpassen
    storage = "/etc/traefik/ACME/acme.json"
    [certificatesResolvers.default.acme.tlsChallenge]

Email-Adresse ist für die Benachrichtigung von Let’s encrypt an dich gedacht. Entsprechend empfehle ich hier eine valide Email-Adresse anzugeben. Die Storage Angabe ist der Speicherort der Zertifikate. Entsprechend muss in der Docker Konfiguration auch das beachtet werden.

Traefik letsencrypt httpChallenge

Die httpChallenge ist quasi das gleich wie die tlsChallenge, allerdings via Port 80 anstatt 443. Hier muss als in der Docker Konfiguration auch Port 80 veröffentlicht werden. So ergibt sich daraus folgender Inhalt für die traefik.toml:

[certificatesResolvers]
  [certificatesResolvers.default.acme]
    email = "mail@example.com" #Email Adresse hier anpassen
    storage = "/etc/traefik/ACME/acme.json"
    [certificatesResolvers.default.acme.httpChallenge]
      entryPoint = "web"

Traefik letsencrypt dnsChallenge (am Beispiel Cloudflare)

Die dnsChallenge ist quasi die Königsdisziplin. Allerdings nur wirklich dann sinnvoll wenn man z. B. Wildcard Zertifikate benötig oder wenn man viele Subdomainzertifikate benötigt. Entsprechend muss man hier auch ein wenig mehr konfigurieren und vor allen Dingen benötigt man einen DNS Provider der von Let’s encrypt unterstützt wird. Ich empfehle hier Cloudflare.

[certificatesResolvers]
  [certificatesResolvers.default.acme]
    email = "mail@example.com" #Email Adresse hier anpassen
    storage = "/etc/traefik/ACME/acme.json"
    [certificatesResolvers.default.acme.dnsChallenge]
      provider = "cloudflare"
      CLOUDFLARE_EMAIL=foo@bar.com
      CLOUDFLARE_API_KEY=b9841238feb177a84330febba8a83208921177bffe733
      resolvers = ["1.1.1.1:53", "8.8.8.8:53"]

Den Cloudflare API Key bekommt man in den Profileinstellungen unter API Key.

Zertifikate löschen

Zertifikate werden in der acme.json Datei gespeichert und könnten dort heraus gelöscht werden. Zu jedem Zertifikat gibt es eine certificate und key Definition. Man kann also die Datei entsprechend editieren und die Zeichenketten entsprechend heraus löschen.

      {
        "domain": {
          "main": "teqqy.de",
          "sans": [
            "www.teqqy.de"
          ]
        },
        "certificate": "<Zeichenkette>",
        "key": "<Zeichenkette>",
        "Store": "default"
      },

Notwendig ist dies aber nur dann, wenn bei der Erstellung ein Fehler aufgetreten ist oder Let’s Encrypt Zertifikate wg. Fehlern zurückruft. Andernfalls laufen die Zertifikate automatisch nach 90 Tagen ab. Ein manuelles Aufräumen ist nicht notwendig.