ACME-klienten Lego

ACME-klienten Lego är ett oberoende, gratis projekt med öppen källkod skrivet i programmeringsspråket Go. Den är idealisk för anpassad integration och skriptning och har brett stöd från domänregistratorer och DNS-leverantörer. Lego är en flexibel ACME-klient som enkelt kan integreras i anpassade system och skript. Förutom HTTP-01-validering erbjuder den DNS-validering via många DNS-leverantörer (lista över DNS-leverantörer som stöds) för att erhålla WildCard SSL-certifikat.
Guiden använder syntax som verifierats på version Lego 5.*.* och är avsedd för Debian/Ubuntu med Apache 2 och ACME-klienten Lego.

Grundläggande begrepp

• ACME – protokoll för automatiserat utfärdande och förnyelse av SSL/TLS-certifikat.
• HTTP-01 – ACME-valideringsmetod som verifierar domänägarskap med hjälp av en tillfällig fil som är tillgänglig via HTTP.
• DNS-01 – valideringsmetod via DNS TXT-posten _acme-challenge.
• EAB kid + hmac – External Account Binding (EAB)-uppgifter från certifikatutfärdaren. De kopplar Certbot till ett konto eller en produkt.
• Systemd service - en konfigurationsfil som talar om för Linux-systemet hur en applikation ska startas och hållas igång även efter en serveromstart.

Om domänen example.com förekommer i exemplen, ersätt den alltid med din egen domän.

Installation av 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

Efter en lyckad installation rekommenderar vi att du tar bort de tillfälliga filerna.

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

Apache, webroot

Detta förfarande skapar en grundläggande VirtualHost-konfiguration för domänen på port 80. Det ställer in DocumentRoot, behörigheter för webbkatalogen, skapar Apache-loggar, aktiverar konfigurationen med a2ensite, verifierar att den är korrekt (apache2ctl configtest) och laddar om ändringarna. Slutligen verifierar det webbplatsens tillgänglighet med en HTTP-begäran 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"

Lego-konfigurationsfiler

Det rekommenderade tillvägagångssättet för Lego v5 är att lagra inställningarna i en konfigurationsfil. Systemd-tjänsten behöver då inte innehålla ett långt kommando med domäner och hooks.

Konfigurationsfilen lego.yml

.yml-filen är en textkonfigurationsfil i YAML-format, som används för en tydlig notation av inställningar, parametrar och strukturerade data. Innan du sparar YAML-konfigurationen, ersätt example.com med din egen domän, vas@email.cz med din kontakt-e-post och värdena KID / HMAC med uppgifterna från din ACME-certifikatorder.

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

Tips! Du kan generera ett nästan komplett YML-innehåll direkt på servern och sedan bara fylla i rätt e-post, kid och hmacKey. Kör bara kommandot nedan och kopiera innehållet från index.html-sidan till lego.yml-filen.
›› Visa/Dölj det förberedda 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

Kontrollera filens behörigheter och ägare:

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

Utfärdande av SSL/TLS-certifikatet

Innan du kör, kontrollera echo ${DOMAIN} eller ställ in DOMAIN-variabeln till namnet på din domän DOMAIN="example.com". Verktyget Lego utför HTTP-01-validering med hjälp av en fil som tillfälligt lagras i webroot, verifierar domänägarskap och skapar sedan ett SSL/TLS-certifikat. Certifikatet, den privata nyckeln och utfärdarens (mellanliggande) certifikat lagras i katalogen /etc/lego/${DOMAIN}/certificates/.

Under genereringen skriver ACME-klienten Lego ut information om begäran:

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

Verifiera de genererade SSL-certifikatfilerna

Visar innehållet i certifikatkatalogen som skapats av Lego-tjänsten, inklusive certifikatet, den privata nyckeln och utfärdarens certifikat för den valda domänen.

Katalogen certificates/ innehåller det utfärdade .crt, .key, certifikatutfärdarens mellanliggande certifikat och metadata.

Driftsätta certifikatet till Apache

Detta exempel använder variabeln ${DOMAIN}, som du redan bör ha ställt in från början av guiden. Innan du kör kommandona kan du säkerställa att variabeln är korrekt inställd, till exempel: echo ${DOMAIN}
Variabeln ${DOMAIN} används i konfigurationsfilens namn, värdena ServerName och ServerAlias samt sökvägen till webroot.
Varning! - sökvägarna till SSL-certifikatet och den privata nyckeln använder domänen i formen example-com. Sökvägarna måste matcha domänen som används i Lego-konfigurationen.

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}

Resultat: Fungerande HTTPS.

Automatisk förnyelse

Lego kan förnya certifikatet automatiskt, men efter installationen skapar den inte systemd-enheterna för regelbunden körning på egen hand. Två enheter behöver därför skapas för automatisk förnyelse:

• lego-example-com-renew.service – kör kontrollen och, om det behövs, förnyelsen av certifikatet.
• lego-example-com-renew.timer – ser till att tjänsten körs dagligen vid en angiven tidpunkt.

Innan du infogar, ersätt example-com i service/timer-namnet med ditt eget namn om det behövs, och ersätt example.com i konfigurationssökvägen med din egen domän.

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

Efter att du skapat enheterna, verifiera deras innehåll:

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

Ladda om de nya enheterna, aktivera timern och verifiera att den är igång:

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

Resultat: Timern är aktiv och systemd har schemalagt dess nästa körning.

Säkert test av tjänsten:

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

Resultat: Om certifikatet inte är nära utgången kan Lego rapportera att förnyelse inte behövs. Detta är korrekt beteende.

Lista över tillgängliga Lego-enheter:

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

systemctl list-timers | grep lego

Resultat: Båda varianterna visar alla tjänster och timrar relaterade till ACME-klienten Lego.

Vart går du härnäst?

• ACME-protokollet
• ACME-klienten Lego (WildCard + API DNS)
• ACME-klienten Certbot
• SSL-certifikat - Allt du behöver veta