ACME klient Lego

Podrobný návod krok za krokem k instalaci, konfiguraci a automatické obnově SSL certifikátu na Linux serveru pomocí ACME klienta Lego.

ACME klient Lego je nezávislý, bezplatný open-source projekt psaný v jazyce Go. Je ideální pro vlastní integraci a skriptování a získává širokou podporu registrátorů domén a poskytovatelů DNS. Lego je flexibilní ACME klient, který lze snadno integrovat do vlastních systémů a skriptů. Kromě validace HTTP-01 nabízí DNS validaci přes mnoho DNS providerů (seznam podporovaných DNS providerů) pro získání WildCard SSL certifikátů.
Návod používá syntaxi ověřenou na verzi Lego 5.*.* a je určen pro Debian/Ubuntu s Apache 2 a ACME klientem Lego.

Základní pojmy

• ACME – protokol pro automatizované vydávání a obnovu SSL/TLS certifikátů.
• HTTP-01 – ACME validační metoda, která ověřuje vlastnictví domény pomocí dočasného souboru dostupného přes HTTP.
• DNS-01 – validační metoda přes DNS TXT záznam _acme-challenge.
• EAB kid + hmac – External Account Binding (EAB) údaje od certifikační autority. Propojují Certbot s účtem nebo produktem.
• Systemd služba - soubor s nastavením, který systému Linux říká, jak má aplikaci spouštět a udržovat ji běžící i po restartu serveru.

Pokud je v příkladech uvedena doména example.com, vždy ji nahraďte 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

Po úspěšné instalaci doporučujeme dočasné soubory odstranit.

rm -f /tmp/lego /tmp/lego.tar.gz /tmp/LICENSE /tmp/CHANGELOG.md

Apache, webroot

Tento postup vytvoří základní konfiguraci VirtualHostu pro doménu na portu 80. Nastaví DocumentRoot, oprávnění pro webový adresář, vytvoří logy Apache, povolí konfiguraci pomocí a2ensite, ověří její správnost (apache2ctl configtest) a načte změny. Na závěr ověří dostupnost webu pomocí HTTP požadavku curl.

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

# or just updates
apt update
apt install --only-upgrade apache2
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 www.$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"
curl -I "http://www.$DOMAIN"

Konfigurační soubory 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 a hooky.

Konfigurační soubor lego.yml

Soubor .yml je textový konfigurační soubor ve formátu YAML, používaný pro přehledný zápis nastavení, parametrů a strukturovaných dat. Před uložením YAML konfigurace nahraďte example.com vlastní doménou, vas@email.cz vaším kontaktním e-mailem a hodnoty KID / HMAC údaji z objednávky ACME certifikátu.

mkdir /etc/lego/$DOMAIN
nano /etc/lego/$DOMAIN/lego.yml

storage: /etc/lego/example.com

accounts:
  certum-account:
    server: certum
    email: your@email.com   # your email address for CA Certum
    acceptsTermsOfService: true
    eab:
      kid: KID
      hmacKey: HMAC

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

challenges:
  http-chal:
    http:
      # Path to your website's document root.
      # Lego will temporarily write a file to this directory .well-known/acme-challenge/
      webroot: /var/www/example.com/public

certificates:
  example-com:
    account: certum-account
    challenge: http-chal
    domains:
      - example.com
      - www.example.com
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2

Tip! Téměř hotový obsah YML si můžete vygenerovat přímo na serveru a poté jen doplnit správný e-mail, kid a hmacKey. Stačí spustit příkaz níže a zkopírovat obsah ze stránky index.html do souboru lego.yml.
›› Zobrazit/Skrýt předpřipravený YML.

cat > "/var/www/$DOMAIN/public/index.html" <<EOF
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>${DOMAIN}</title>
<style>
body { font-family: sans-serif; max-width: 900px; margin: 40px auto; }
pre { background:#f4f4f4; padding:1em; overflow:auto; }
</style>
</head>
<body>

<h1>OK – ${DOMAIN}</h1>
<p>Apache is working correctly.</p>
<h2>lego.yml</h2>
<pre><code>storage: /etc/lego/${DOMAIN}

accounts:
  certum-account:
    server: certum
    email: YOUR_EMAIL
    acceptsTermsOfService: true
    eab:
      kid: YOUR_KID
      hmacKey: YOUR_HMAC_KEY

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

challenges:
  http-chal:
    http:
      webroot: /var/www/${DOMAIN}/public

certificates:
  ${DOMAIN//./-}:
    account: certum-account
    challenge: http-chal
    domains:
      - ${DOMAIN}
      - www.${DOMAIN}
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2
</code></pre>

</body>
</html>
EOF

Kontrola oprávnění a vlastníka souboru:

stat -c "%a %U:%G %n" /etc/lego/$DOMAIN/lego.yml

Vydání SSL/TLS certifikátu

Před spuštěním zkontrolujte echo ${DOMAIN} nebo nastavte proměnnou DOMAIN na název své domény DOMAIN="example.com". Nástroj Lego provede HTTP-01 validaci pomocí souboru dočasně uloženého do webrootu, ověří vlastnictví domény a následně vytvoří SSL/TLS certifikát. Certifikát, privátní klíč i certifikát vydavatele (intermediate) budou uloženy do adresáře /etc/lego/${DOMAIN}/certificates/.

Během generování bude ACME klient Lego vypisovat informace o žádosti:

root@vmiXXXXXXXX:~# echo ${DOMAIN}
example.com

root@:~# lego --config /etc/lego/$DOMAIN/lego.yml

INFO  Archive account scope=accountID filepath=/etc/lego/example.com/accounts/acme.certum.pl/certum-acme/ 
      archives=/etc/lego/example.com/archives/accounts/acme.certum.pl_certum-acme_1785270773.zip
INFO  Private key saved. filepath=/etc/lego/example.com/accounts/acme.certum.pl/certum-account/certum-account.key
INFO  Registering the account (EAB). email=your@email.com
WARN  !!!! HEADS UP !!!!

Your account credentials have been saved in your
configuration directory at "/etc/lego/example.com/accounts".

You should make a secure backup of this folder now. This
configuration directory will also contain private keys
generated by lego and certificates obtained from the ACME
server. Making regular backups of this folder is ideal.

INFO  Obtaining bundled SAN certificate. domains="example.com, www.example.com"
INFO  Use solver. domain=www.example.com type=http-01
INFO  Use solver. domain=example.com type=http-01
INFO  http01: Trying to solve HTTP-01. domain=www.example.com
INFO  The server validated our request. domain=www.example.com
INFO  http01: Trying to solve HTTP-01. domain=example.com
INFO  The server validated our request. domain=example.com
INFO  Validations succeeded; requesting certificates. domains="example.com, www.example.com"
INFO  Waiting for certificates. timeout=30s interval=500ms domains="example.com, www.example.com"
INFO  Server responded with a certificate. domains="example.com, www.example.com"
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.crt
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.issuer.crt
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.key
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.pem
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.json

Ověřte vygenerované soubory SSL certifikátu

Zobrazí obsah adresáře certifikátů vytvořeného službou Lego, včetně certifikátu, soukromého klíče a certifikátu vydavatele pro vybranou doménu.

Adresář certificates/ obsahuje vydaný .crt, .key, intermediate certifikáty certifikační autority a metadata.

Nasazení certifikátu do Apache

Tento příklad používá proměnnou ${DOMAIN}, kterou byste měli mít již nastavenu z úvodu průvodce. Před spuštěním příkazů se můžete ujistit, že je proměnná správně nastavena, například: echo ${DOMAIN}
Proměnná ${DOMAIN} se použije v názvu konfiguračního souboru, hodnotách ServerName a ServerAlias a cestě k webrootu.
Upozornění! - v cestách k SSL certifikátu a privátnímu klíči se použije doména ve tvaru example-com. Cesty musí odpovídat doméně použité v Lego konfiguraci.

cat > /etc/apache2/sites-available/${DOMAIN}-le-ssl.conf <<EOF
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName ${DOMAIN}
    ServerAlias www.${DOMAIN}

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

    SSLEngine on
    SSLCertificateFile /etc/lego/${DOMAIN}/certificates/${DOMAIN//./-}.crt
    SSLCertificateKeyFile /etc/lego/${DOMAIN}/certificates/${DOMAIN//./-}.key

    ErrorLog ${APACHE_LOG_DIR}/${DOMAIN}_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/${DOMAIN}_ssl_access.log combined
</VirtualHost>
</IfModule>
EOF

a2ensite ${DOMAIN}-le-ssl.conf
apache2ctl configtest
systemctl reload apache2

curl -I https://${DOMAIN}
curl -I https://www.${DOMAIN}

Výsledek: Funkční HTTPS.

Automatická obnova

Lego umí certifikát automaticky obnovit, ale samo po instalaci nevytvoří systemd jednotky pro pravidelné spouštění. K automatické obnově je proto potřeba vytvořit dvě jednotky:

• lego-example-com-renew.service – spustí kontrolu a případnou obnovu certifikátu.
• lego-example-com-renew.timer – zajistí každodenní spuštění služby ve stanovený čas.

Před vložením případně nahraďte example-com ve jménu service/timeru vlastním názvem, a nahraďte example.com v cestě ke konfiguraci vlastní doménou.

cat > /etc/systemd/system/lego-${DOMAIN//./-}-renew.service <<EOF
[Unit]
Description=Renew ACME Certum SSL for example.com using Lego HTTP-01
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/lego --config /etc/lego/${DOMAIN}/lego.yml
EOF

cat > /etc/systemd/system/lego-${DOMAIN//./-}-renew.timer <<EOF
[Unit]
Description=Daily Lego renewal check for ${DOMAIN}

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

[Install]
WantedBy=timers.target
EOF

Po vytvoření jednotek ověřte jejich obsah:

cat /etc/systemd/system/lego-example-com-renew.service
echo "----------------"
cat /etc/systemd/system/lego-example-com-renew.timer

Načtěte nové jednotky, povolte timer a ověřte jeho spuštění:

systemctl daemon-reload
systemctl enable --now lego-${DOMAIN//./-}-renew.timer
systemctl list-timers | grep lego

Výsledek: Timer je aktivní a systemd naplánoval jeho další spuštění.

Bezpečný test služby:

systemctl start lego-${DOMAIN//./-}-renew.service
systemctl status lego-${DOMAIN//./-}-renew.service --no-pager
journalctl -u lego-${DOMAIN//./-}-renew.service -n 100 --no-pager

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

Seznam dostupných Lego jednotek:

ls -l /etc/systemd/system/lego*

systemctl list-timers | grep lego

Výsledek: Obě varianty zobrazí všechny služby a timery, které se týkají Lego ACME klienta.

Kam dál?

• ACME protokol
• ACME klient Lego (WildCard + API DNS)
• ACME klient Certbot
• SSL certifikát - vše co potřebujete vědět