basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN
    МануалHomelabTraefik

    Traefik и Let's Encrypt: wildcard, ACME, сертификат для соседей

    Wildcard-сертификаты (*.example.org) запрашиваем на точке входа, а не на роутере: так они не зависят ни от одного сервиса. Для wildcard нужен DNS-challenge, адрес для ACME пишем явно. Если сертификат нужен кому-то ещё, его выгружает cert-dumper, а потребитель регулярно перечитывает файл.

    Настройка

    1. Wildcard — на точке входа

      Статический конфиг Traefik:

      traefik.yml
      entryPoints:
        http:
          address: ":80"
          http:
            redirections:
              entryPoint: { to: https, scheme: https }
        https:
          address: ":443"
          http:
            tls:
              certResolver: cloudflare

      Резолвер по умолчанию: роутеры с tls=true без своего резолвера берут сертификат отсюда.

              domains:
                - main: "example.org"
                  sans: ["*.example.org"]
                - main: "example.net"
                  sans: ["*.example.net"]
      Главное

      Wildcard — здесь, а не на роутере. Сертификаты ни к одному роутеру не привязаны: любой сервис можно убрать или переименовать.

      certificatesResolvers:
        cloudflare:
          acme:
            email: [email protected]

      Адрес — явно: статический конфиг читает сам Traefik, и ${EMAIL} уйдёт буквально («traefik.yml не подставляет переменные»).

            storage: acme.json

      Хранилище аккаунта и сертификатов. Права 600, в git — никогда, в бэкап — желательно: после потери придётся перевыпускать всё, и можно упереться в лимиты Let's Encrypt.

            dnsChallenge:
              provider: cloudflare
              resolvers: ["1.1.1.1:53", "1.0.0.1:53"]

      Токен Cloudflare — Docker secret: CF_DNS_API_TOKEN_FILE: /run/secrets/cf_api_token («Секреты в Docker-стеках»). Права токена — только редактирование DNS нужных зон.

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

      Тестовый сервер Let's Encrypt — для экспериментов: без лимитов, но сертификаты недоверенные.

    2. Роутер сервиса — только tls=true

      - "traefik.http.routers.app-https.rule=Host(`app.example.org`)"
      - "traefik.http.routers.app-https.entrypoints=https"
      - "traefik.http.routers.app-https.tls=true"        # сертификат — wildcard из хранилища
    3. Сертификат для соседей — cert-dumper

      Если тот же сертификат нужен не Traefik’у (nginx как сайт-заглушка, почтовый сервер), выгружаем его из acme.json в файлы — например, traefik-certs-dumper:

      traefik-cert-dumper:
        image: ldez/traefik-certs-dumper
        entrypoint: sh -c 'apk add jq;
          while ! [ -e /data/acme.json ] || ! [ `jq ".[] | .Certificates | length" /data/acme.json` != 0 ]; do sleep 5; done &&
          traefik-certs-dumper file --version v2 --domain-subdir --clean=false --watch --source ./acme.json --dest /cert-dumps'
        volumes:
          - ./data:/data
          - ./cert-dumps:/cert-dumps
        working_dir: /data

      --domain-subdir кладёт файлы в cert-dumps/<домен>/certificate.crt и privatekey.key, --watch обновляет их при продлении.

    4. nginx перечитывает сертификат по расписанию

      nginx читает сертификат при старте и при reload, а без этого отдаёт старый — до истечения срока. Раз в неделю хватает с запасом: продление идёт за 30 дней до конца.

      /etc/cron.d/nginx-reload
      23 4 * * 1 root (docker exec nginx nginx -t && docker exec nginx nginx -s reload && echo reloaded) 2>&1 | logger -t nginx-reload

      Сертификаты монтируем в nginx каталогом (./cert-dumps/example.org:/etc/nginx/ssl:ro), не файлами: отдельно смонтированный файл после обновления остаётся старым («Монтирование отдельного файла»).

    Traefik продлевает сертификат Let’s Encrypt (90 дней) за 30 дней до конца срока. Делать для этого ничего не нужно, но первое продление после любых правок ACME проверяем.

    Wildcard или сертификат на каждое имя

    Решение Когда Цена
    wildcard, DNS-challenge много поддоменов; не хочется светить их имена нужен API-токен DNS-провайдера на сервере
    сертификат на каждый поддомен, HTTP-challenge (порт 80) пара сайтов, DNS без API каждое имя навсегда попадает в публичные журналы сертификатов
    TLS-ALPN-challenge (порт 443) порт 80 закрыт то же, имена публичны
    wildcard на точке входа всегда, когда wildcard —
    wildcard через tls.domains на роутере — сертификаты держатся на одном роутере: убрали его — продление прекратилось

    Каждый выпущенный сертификат попадает в публичные журналы Certificate Transparency (crt.sh). Отдельный сертификат на admin.example.org — публичное объявление, что такая админка есть. Wildcard имён поддоменов не раскрывает, если на них раньше не выпускались отдельные сертификаты. Basic Auth прячет содержимое, но не сам поддомен; админку, которой вообще не должно быть видно, наружу не публикуем — открываем только из внутренней сети.

    С sniStrict: true в настройках TLS (tls.options.default.sniStrict) Traefik не отвечает на запросы без имени сервера: сканеры по IP получают отказ, а не сертификат с именами доменов.

    Если не работает

    Сайты внезапно показывают самоподписанный сертификат Traefik

    Причина
    Wildcard держался на tls.domains роутера, который удалили или переименовали: продление прекратилось, срок истёк.
    Делаем
    Переносим wildcard на точку входа (шаг 1).

    В конфиге email: ${EMAIL_FOR_SSL}

    Причина
    Traefik не подставляет переменные в traefik.yml, адрес уходит буквально.
    Делаем
    Вписываем адрес. После смены адреса Traefik может зарегистрировать новый аккаунт ACME; выданные сертификаты остаются в силе.

    nginx отдаёт просроченный сертификат, а у Traefik — свежий

    Причина
    nginx читает сертификат при старте и при reload, а файл с тех пор обновился.
    Делаем
    Ставим reload по расписанию (шаг 4).

    acme.json с правами шире 600

    Причина
    Traefik откажется его использовать: permissions 644 for /acme.json are too open, please use 600.
    Делаем
    chmod 600 acme.json.

    Эксперименты упёрлись в лимиты Let's Encrypt

    Причина
    Каждая попытка шла на основной сервер Let's Encrypt, а у него лимиты на выпуск.
    Делаем
    Пока всё не заработает, работаем с тестовым caServer (staging).

    Сертификат не продлевается

    Причина
    Чаще всего у токена DNS нет нужных прав или токен не смонтирован: /run/secrets/… пуст.
    Делаем
    Смотрим docker logs traefik 2>&1 | grep -i acme | tail -20, проверяем права токена и файл секрета.

    Как проверить

    # срок сертификатов из cert-dumper
    for d in example.org example.net; do printf '%s: ' "$d"; openssl x509 -enddate -noout -in /opt/traefik/cert-dumps/$d/certificate.crt; done
    # что на самом деле отдаёт сайт
    echo | openssl s_client -connect app.example.org:443 -servername app.example.org 2>/dev/null | openssl x509 -noout -subject -enddate
    # ошибки ACME
    docker logs traefik 2>&1 | grep -iE 'acme|certificate' | grep -iE 'error|unable|fail' | tail -5

    После первого продления срок должен сдвинуться примерно на 60 дней вперёд.