ACME klient Lego

Detailní návod pro nasazení hvězdičkového WildCard SSL certifikátu přes ACME klienta Lego a API DNS validaci u webhostingu VEDOS. Postup je určený pro certifikáty typu example.com a *.example.com, kde má být obnova automatická bez ručního zadávání TXT záznamů. V návodu je použit ACME certifikát od certifikační autority Certum. Použitý certifikát slouží pouze jako příklad – princip fungování i postup nasazení ACME jsou stejné u všech certifikačních autorit.

Návod používá syntaxi ověřenou na Lego 5.2.2. Lego v5 změnilo některé parametry oproti starším verzím, proto při chybě typu flag provided but not defined ověřte správnou syntaxi pomocí lego accounts register --help, lego run --help nebo lego --help.

Základní pojmy

• ACME – protokol pro automatizované vydávání a obnovu SSL/TLS certifikátů.
• Lego – ACME klient napsaný v Go. Umí DNS validaci přes mnoho DNS providerů (seznam podporovaných DNS providerů).
• DNS-01 – validace přes DNS TXT záznam _acme-challenge. Je nutná pro WildCard certifikáty.
• EAB kid + hmac – External Account Binding (EAB) údaje od certifikační autority. Propojují Certbot s účtem nebo produktem.
• VEDOS WAPI – API rozhraní VEDOS, přes které Lego vytváří a maže DNS TXT záznamy.

Ve všech uvedených příkladech nahraďte doménu example.com vlastní doménou.

Instalace Lego

apt update
apt install -y curl tar

cd /tmp
LEGO_URL=$(curl -s https://api.github.com/repos/go-acme/lego/releases/latest | sed -n 's/.*"browser_download_url": "\(.*linux_amd64.tar.gz\)".*/\1/p' | head -n1)
echo "$LEGO_URL"
curl -L -o lego.tar.gz "$LEGO_URL"
tar -xzf lego.tar.gz
install -m 0755 lego /usr/local/bin/lego
lego --version

Webhosting DNS API

V tomto návodě je použito DNS API od webhostingu Vedos. Pro webhosting Vedos je nutné aktivovat WAPI a také vyplnit povolené IP adresy a WAPI heslo.
Klient LEGO podporuje stovky dalších DNS poskytovatelů. Jejich seznam neleznete na webových stránkách LEGO - seznam podporovaných DNS providerů

IP adresy VPS serveru

curl -4 ifconfig.me
curl -6 ifconfig.me

Do pole Povolené IP adresy vložte všechny odchozí IP adresy vašeho serveru, typicky IPv4 i IPv6. Hodnoty se oddělují mezerou. VEDOS povolí API požadavky pouze z uvedených IP adres.

Doporučené hodnoty ve VEDOS

Apache, webroot

Základní nastavení Apache je podpůrná část. DNS validace běží přes DNS API, ne přes HTTP, ale Apache vhost je potřeba pro obsluhu webu po vydání certifikátu.

cd /var/www
apt update
apt install -y apache2
systemctl enable --now apache2
a2enmod rewrite headers ssl
systemctl reload apache2

DOMAIN="example.com"
mkdir -p /var/www/$DOMAIN/public
chown -R www-data:www-data /var/www/$DOMAIN
chmod -R 755 /var/www/$DOMAIN
echo "OK $DOMAIN" > /var/www/$DOMAIN/public/index.html

cat > /etc/apache2/sites-available/$DOMAIN.conf <<EOF
<VirtualHost *:80>
    ServerName $DOMAIN
    ServerAlias *.$DOMAIN

    DocumentRoot /var/www/$DOMAIN/public
    <Directory /var/www/$DOMAIN/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog \${APACHE_LOG_DIR}/${DOMAIN}_error.log
    CustomLog \${APACHE_LOG_DIR}/${DOMAIN}_access.log combined
</VirtualHost>
EOF

a2ensite $DOMAIN.conf
apache2ctl configtest
systemctl reload apache2
curl -I http://$DOMAIN

Konfigurační soubor Lego

Doporučený postup pro Lego v5 je uložit nastavení do konfiguračního souboru. Systemd služba pak nemusí obsahovat dlouhý příkaz s doménami, DNS providerem a hooky.

VEDOS env soubor

Před spuštěním nahraďte example.com vlastní doménou. Soubor vedos-example.com.env bude obsahovat přihlašovací údaje k VEDOS WAPI, proto ho ukládáme do /etc/lego a nastavíme mu omezená práva.

DOMAIN="example.com"

mkdir -p /etc/lego/$DOMAIN
nano /etc/lego/vedos-$DOMAIN.env

V konfiguraci níže nahraďte WEDOS_LOGIN vaším VEDOS loginem a WEDOS_WAPI_PASSWORD heslem vygenerovaným ve VEDOS WAPI. Hodnoty timeoutu a intervalu můžete ponechat.

WEDOS_USERNAME='WEDOS_LOGIN'
WEDOS_WAPI_PASSWORD='WEDOS_WAPI_PASSWORD'
WEDOS_PROPAGATION_TIMEOUT=3600
WEDOS_POLLING_INTERVAL=30
WEDOS_TTL=300

Soubor lego.yml

Před uložením YAML konfigurace nahraďte example.com vlastní doménou, *.example.com wildcard názvem, vas@email.cz vaším kontaktním e-mailem a hodnoty KID / HMAC údaji z objednávky ACME certifikátu. Názvy jako certum-example nebo example-com-wildcard jsou interní popisky; můžete je ponechat, ale u více domén je vhodné je přejmenovat podle domény.

storage: /etc/lego/example.com

accounts:
  certum-example:
    server: certum
    email: vas@email.cz
    acceptsTermsOfService: true
    eab:
      kid: KID
      hmacKey: HMAC

servers:
  certum:
    url: https://acme.certum.pl/directory

challenges:
  vedos-dns:
    dns:
      provider: edos
      envFile: /etc/lego/vedos-example.com.env
      resolvers:
        - 1.1.1.1:53

certificates:
  example-com-wildcard:
    account: certum-example
    challenge: vedos-dns
    domains:
      - example.com
      - "*.example.com"
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2

Vydání certifikátu

Před spuštěním nahraďte example.com v cestě doménou, kterou jste použili při vytváření adresáře. První spuštění vytvoří ACME účet, nastaví DNS TXT záznamy přes DNS API, provede DNS-01 validaci a uloží certifikát.

Během čekání může Lego vypisovat:

To znamená, že Lego kontroluje DNS každých 30 sekund a čeká maximálně 1 hodinu. Po úspěchu ověřte soubory:

Adresář certificates/ obsahuje vydaný .crt, .key, issuer certifikát a metadata.

Alternativní CLI postup pro Lego v5

lego accounts register \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --accept-tos \
  --eab \
  --eab.kid 'KID' \
  --eab.hmac 'HMAC'

set -a
. /etc/lego/vedos-example.com.env
set +a

lego run \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --dns vedos \
  --dns.resolvers 1.1.1.1:53 \
  --domains example.com \
  --domains '*.example.com'

Nasazení certifikátu do Apache

Před vytvořením HTTPS vhostu nahraďte example.com vlastní doménou ve jménu souboru, hodnotách ServerName, ServerAlias, cestách k webrootu i cestách k certifikátu. Tyto cesty musí odpovídat doméně použité v Lego konfiguraci.

cat > /etc/apache2/sites-available/example.com-le-ssl.conf <<'EOF'
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName example.com
    ServerAlias *.example.com

    DocumentRoot /var/www/example.com/public
    <Directory /var/www/example.com/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile /etc/lego/example.com/certificates/example.com.crt
    SSLCertificateKeyFile /etc/lego/example.com/certificates/example.com.key

    ErrorLog ${APACHE_LOG_DIR}/example.com_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/example.com_ssl_access.log combined
</VirtualHost>
</IfModule>
EOF

a2ensite example.com-le-ssl.conf
apache2ctl configtest
systemctl reload apache2

curl -I https://example.com
curl -I https://test.example.com

Automatická obnova

Lego umí certifikát obnovit, ale samo po instalaci nevytvoří systemd timer. Pravidelné spouštění se nastavuje přes vlastní service a timer. Před vložením nahraďte example-com ve jménu service/timeru vlastním bezpečným názvem bez teček, například mojedomena-cz, a nahraďte example.com v cestě ke konfiguraci vlastní doménou.

cat > /etc/systemd/system/lego-example-com-renew.service <<'EOF'
[Unit]
Description=Renew Certum WildCard SSL for example.com using Lego and VEDOS DNS
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/lego --config /etc/lego/example.com/lego.yml
EOF

cat > /etc/systemd/system/lego-example-com-renew.timer <<'EOF'
[Unit]
Description=Daily Lego renewal check for example.com

[Timer]
OnCalendar=*-*-* 03:20:00
RandomizedDelaySec=1800
Persistent=true

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now lego-example-com-renew.timer
systemctl list-timers | grep lego

Bezpečný test služby:

systemctl start lego-example-com-renew.service
journalctl -u lego-example-com-renew.service -n 100 --no-pager

Pokud certifikát není blízko expirace, Lego může oznámit, že obnova není potřeba. To je správné chování.

Časté chyby

Neznámý parametr u Lego

U Lego v5 jsou EAB parametry --eab.kid a --eab.hmac. Parametry patří vždy ke konkrétnímu subcommandu.

lego accounts register --help
lego accounts list --help
lego run --help

Cleanup TXT záznamů selže na nepovolené IP

Do VEDOS WAPI povolených IP adres přidejte také IPv6 adresu serveru. Certifikát může být vydaný správně, ale TXT záznamy po validaci zůstanou v DNS.

Ověřovací checklist

dig TXT _acme-challenge.example.com +short
lego --config /etc/lego/example.com/lego.yml
systemctl status lego-example-com-renew.timer
apache2ctl configtest
curl -I https://example.com

Kam dál?

• ACME protokol
• ACME klient Certbot
• WildCard SSL přes Certbot a DNS-01
• SSL certifikát - vše co potřebujete vědět