basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    traefik.yml block by block: what each setting means

    Traefik’s static config block by block: what each setting does, its default, and when to change it. Settings that aren’t in the file but are often needed get their own section.

    What’s in this file and what isn’t

    traefik.yml is the static config: entry points, where routes come from, how to get certificates, logs, plugins. Traefik reads it once, at startup, so any change means docker compose restart traefik and a few seconds when no site opens.

    Routers, middleware and services aren’t here — they’re dynamic config: container labels (Traefik labels) and files in dynamic/ (at the end of this page). ${…} variables aren’t substituted in traefik.yml: Traefik reads the file itself, not compose (traefik.yml doesn’t substitute variables).

    The file, block by block

    Domains are replaced with example.org and example.net; the Cloudflare network lists are shortened.

    /opt/traefik/data/traefik.yml
    experimental:
      plugins:
        crowdsec-bouncer-traefik-plugin:
          moduleName: "github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin"
          version: "v1.8.1"

    The CrowdSec bouncer plugin: the name on the left is what dynamic/crowdsec.yml uses to attach it (CrowdSec with Traefik behind Cloudflare). Traefik downloads the plugin from GitHub on every start, so pin the version with a tag.

    default no plugins

    global:
      checkNewVersion: false
      sendAnonymousUsage: false

    No new-version check: the image tag sets the version, and otherwise Traefik goes looking for updates and logs about them. Anonymous stats are off anyway — the line is for whoever reads the file.

    default:checkNewVersion truesendAnonymousUsage false

    api:
      dashboard: false
      debug: false

    The dashboard is a page with every router and its errors. It isn’t exposed by itself: it needs a router on api@internal with a password and the ban. Turn it on while debugging; api.insecure: true would open it on port 8080 with no protection.

    default:dashboard trueinsecure false

    log:
      level: INFO
      filePath: "/logs/traefik.log"

    INFO adds events: which certificates were obtained, which providers connected. DEBUG is for troubleshooting; the log grows fast. With filePath the log goes only to the file, and docker logs traefik is empty.

    default:level ERRORfilePath stdout

      maxSize: 10
      maxBackups: 5
      maxAge: 7
      compress: true

    Built-in rotation: a new file after 10 MB, 5 old ones kept, at most 7 days, old ones gzipped. Don’t add traefik.log to logrotate: two mechanisms on one file get in each other’s way (Traefik logs).

    default:maxSize 100maxBackups 0 — allmaxAge 0 — no limitcompress false

    accesslog:
      addInternals: true
      format: json
      filePath: "/logs/access.log"

    The request log in JSON, one line per request: address, router, status code, duration. Log parsers such as CrowdSec or vector take their events from it (Traefik logs). A file rather than stdout because there can be several readers; logrotate rotates it with a USR1 signal.

    default:format commonaddInternals false

    entryPoints:
      http:
        address: ":80"
        http:
          aliasHeadersStrategy: delete
          redirections:
            entryPoint:
              to: https
              scheme: https
    Key part

    Every request on 80 goes to HTTPS. The redirect’s priority beats any router, so http routers and redirectscheme in service labels are no longer needed. The names http and https are arbitrary; labels refer to them. aliasHeadersStrategy — in the next block.

    default:permanent truepriority MaxInt−1

      https:
        address: ":443"
        http:
          aliasHeadersStrategy: delete
          tls:
            certResolver: cloudflare
            domains:
              - main: "example.org"
                sans:
                  - "*.example.org"
              - main: "example.net"
                sans:
                  - "*.example.net"

    Every router on this entry point gets TLS and a certificate from the cloudflare resolver. The wildcard is requested here, not on a router: the certificate doesn’t depend on any single service (Traefik and Let’s Encrypt). aliasHeadersStrategy: delete drops headers with _ or . in the name: PHP and nginx read X_Auth_User as X-Auth-User, so a visitor could forge a header that Traefik sets. reject instead of delete answers such a request with 400. Without the line, Traefik 3.7 logs a warning for each entry point.

    default:aliasHeadersStrategy keep

        forwardedHeaders:
          trustedIPs:
            # Cloudflare IPv4
            - 173.245.48.0/20
            - 103.21.244.0/22
            # … 13 more IPv4 networks
            # Cloudflare IPv6
            - 2400:cb00::/32
            # … 6 more IPv6 networks

    Traefik accepts X-Forwarded-* only from these addresses and overwrites it from anyone else — otherwise any visitor could pose as another address. Without this block, the log and CrowdSec show Cloudflare instead of visitors. The list: cloudflare.com/ips.

    providers:
      docker:
        endpoint: "unix:///var/run/docker.sock"
        exposedByDefault: false
        watch: true

    Only containers with traefik.enable=true are exposed. With the default, every container with a port would go public under its own name. Routes are rebuilt on Docker events at most once every 2 s.

    default:exposedByDefault truewatch true

      file:
        directory: /dynamic/
        watch: true

    A directory, not a single file: a single-file mount doesn’t see changes after git pull (Single-file mounts). Edits in dynamic/ apply without a restart.

    certificatesResolvers:
      cloudflare:
        acme:
          email: [email protected]
          storage: acme.json

    The Let’s Encrypt account email, written literally (traefik.yml doesn’t substitute variables). acme.json holds the account key and every certificate: mode 600, never in git, always in backups.

    default:storage acme.json

          caServer: https://acme-v02.api.letsencrypt.org/directory
          # caServer: https://acme-staging-v02.api.letsencrypt.org/directory

    The production Let’s Encrypt server issues certificates browsers trust. The staging server is for experiments: higher limits, untrusted certificates; after switching back, clear acme.json.

    default production server

          dnsChallenge:
            provider: cloudflare
            resolvers:
              - "1.1.1.1:53"
              - "1.0.0.1:53"

    DNS-01: Traefik creates the TXT record itself through the Cloudflare API — the only way to get a wildcard. The token is CF_DNS_API_TOKEN_FILE from a Docker secret (Secrets in Docker stacks). Check the record at Cloudflare’s DNS: it sees the record before anyone else.

    Not in the file, but often needed

    traefik.ymlnot enabled on the server
    entryPoints:
      https:
        transport:
          respondingTimeouts:
            readTimeout: 600s

    Within readTimeout Traefik must read the whole request, body included. A large upload over a slow link breaks off at one minute — raise it on the entry point that takes uploads.

    default:readTimeout 60swriteTimeout 0idleTimeout 180s

        http3: {}

    HTTP/3 over QUIC. It also needs a UDP port: - 443:443/udp in compose. Works only for routers with TLS.

        proxyProtocol:
          trustedIPs: ["10.0.0.5"]

    PROXY protocol — when a TCP load balancer in front of Traefik passes the visitor’s address at the start of the connection. Only from the balancer’s addresses.

    serversTransport:
      insecureSkipVerify: true

    Don’t verify certificates of services behind Traefik — for a service that serves HTTPS itself with a self-signed certificate. Here it applies to every service at once; for one service, use a serversTransport in dynamic config and have the service refer to it by name with the provider: serversTransport: insecure@file.

    default false

    ping: {}
    metrics:
      prometheus: {}

    /ping is for a compose healthcheck: traefik healthcheck --ping. Metrics — requests, status codes and timings per router, for Grafana. Both live on the traefik entry point (8080); don’t publish it.

    providers:
      docker:
        network: proxy

    The network Traefik uses to reach containers. On the server it’s set in every service with the traefik.docker.network label; one line here replaces them all.

    default:network empty — Traefik picks

    certificatesResolvers:
      letsencrypt:
        acme:
          email: [email protected]
          storage: acme.json
          httpChallenge:
            entryPoint: http

    Without a wildcard you don’t need DNS-01: HTTP-01 validates through port 80, tlsChallenge: {} through 443.

    default:keyType RSA4096certificatesDuration 2160 h

          dnsChallenge:
            propagation:
              delayBeforeChecks: 60s

    A pause before, or skipping, the TXT propagation check when Cloudflare answers slowly. Older configs use delayBeforeCheck and disablePropagationCheck: Traefik 3.7 still understands them but logs a deprecation warning.

    default:delayBeforeChecks 0sdisableChecks false

    Next door: what lives in dynamic/

    Dynamic config is picked up without a restart. On the server data/dynamic/ holds three files: TLS options, rate limits, and the ban middleware (crowdsec.yml, covered in CrowdSec with Traefik behind Cloudflare).

    dynamic/dynamic.yml
    tls:
      options:
        default:
          sniStrict: true

    Traefik drops a connection with no site name or a foreign name instead of serving TRAEFIK DEFAULT CERT: a scanner hitting the server’s address won’t learn which sites live there.

    default false

    dynamic/rate-limit.yml
    http:
      middlewares:
        global-ratelimit:
          rateLimit:
            average: 100
            burst: 50
            period: 1s

    On average 100 requests per period from one address, plus a burst of up to 50. The limit is counted per address, not for the whole router.

    default:average 0 — offburst 1period 1s

            sourceCriterion:
              ipStrategy:
                depth: 1
    Key part

    The visitor’s address is the first from the right in X-Forwarded-For: Cloudflare appended it. Without depth the limit would be counted by Cloudflare addresses and shared by everyone coming through one node.

    If it doesn’t work

    After editing traefik.yml the container restarts in a loop

    Cause
    An error in the static config — Traefik won’t start.
    Fix
    docker logs traefik --tail 20 shows the line; if you can’t find it fast, git checkout -- data/traefik.yml && docker compose restart traefik.

    docker logs traefik is empty

    Cause
    log.filePath is set — the log goes to a file.
    Fix
    tail -f /opt/traefik/data/logs/traefik.log.

    The request log and CrowdSec show only Cloudflare addresses

    Cause
    No forwardedHeaders.trustedIPs on the entry point, or the list of Cloudflare networks is out of date.
    Fix
    Compare the list with cloudflare.com/ips.

    The rate limit hits everyone at once

    Cause
    rateLimit has no ipStrategy.depth: 1, so the limit is shared per Cloudflare node.
    Fix
    Add sourceCriterion.ipStrategy.depth: 1.

    A new service is exposed though it has no traefik.enable

    Cause
    exposedByDefault isn’t set and stayed true.
    Fix
    Set exposedByDefault: false and restart Traefik.

    The wildcard isn’t issued; the log mentions TXT record propagation

    Cause
    Cloudflare hadn’t spread the record before the check.
    Fix
    Add propagation.delayBeforeChecks: 60s; details — Traefik and Let’s Encrypt.

    How to check

    # the Traefik container's ports are 80 and 443
    docker port traefik
    # 80/tcp -> 0.0.0.0:80
    # 443/tcp -> 0.0.0.0:443
    # the certificate is a wildcard from Let's Encrypt
    echo | openssl s_client -connect whoami.example.org:443 -servername whoami.example.org 2>/dev/null \
      | openssl x509 -noout -subject -ext subjectAltName
    # DNS:*.example.org, DNS:example.org
    # without a site name the connection is dropped (sniStrict)
    echo | openssl s_client -connect 203.0.113.10:443 2>&1 | grep -iE 'alert|error' | head -2
    # behind Cloudflare, Traefik sees the visitor's address, not Cloudflare's
    curl -s https://whoami.example.org | grep -i '^X-Real-Ip'