Client ACME Lego

Le client ACME Lego est un projet indépendant, gratuit et open-source écrit dans le langage Go. Il est idéal pour l'intégration personnalisée et les scripts et bénéficie d'un large support de la part des registraires de domaines et des fournisseurs DNS. Lego est un client ACME flexible qui peut être facilement intégré à des systèmes et des scripts personnalisés. Outre la validation HTTP-01, il propose la validation DNS via de nombreux fournisseurs DNS (liste des fournisseurs DNS pris en charge) pour obtenir des certificats SSL WildCard.
Le guide utilise une syntaxe vérifiée sur la version Lego 5.*.* et est destiné à Debian/Ubuntu avec Apache 2 et le client ACME Lego.

Concepts de base

• ACME – protocole pour l'émission et le renouvellement automatisés des certificats SSL/TLS.
• HTTP-01 – méthode de validation ACME qui vérifie la propriété du domaine à l'aide d'un fichier temporaire accessible via HTTP.
• DNS-01 – méthode de validation via l'enregistrement DNS TXT _acme-challenge.
• EAB kid + hmac – détails External Account Binding (EAB) fournis par l'autorité de certification. Ils relient ACME client à un compte ou à un produit.
• Service systemd - un fichier de configuration qui indique au système Linux comment démarrer une application et la maintenir en fonctionnement même après un redémarrage du serveur.

Si le domaine example.com apparaît dans les exemples, remplacez-le toujours par votre propre domaine.

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

Après une installation réussie, nous recommandons de supprimer les fichiers temporaires.

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

Apache, webroot

Cette procédure crée une configuration VirtualHost de base pour le domaine sur le port 80. Elle définit DocumentRoot, les permissions du répertoire web, crée les logs Apache, active la configuration à l'aide de a2ensite, en vérifie l'exactitude (apache2ctl configtest) et recharge les modifications. Enfin, elle vérifie la disponibilité du site web à l'aide d'une requête HTTP 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"

Fichiers de configuration de Lego

L'approche recommandée pour Lego v5 est de stocker les paramètres dans un fichier de configuration. Le service systemd n'a alors pas besoin de contenir une longue commande avec les domaines et les hooks.

Fichier de configuration lego.yml

Le fichier .yml est un fichier de configuration texte au format YAML, utilisé pour une notation claire des paramètres, des options et des données structurées. Avant d'enregistrer la configuration YAML, remplacez example.com par votre propre domaine, vas@email.cz par votre e-mail de contact et les valeurs KID / HMAC par les détails de votre commande de certificat ACME.

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

Astuce ! Vous pouvez générer un contenu YML presque complet directement sur le serveur, puis il suffit de compléter le bon e-mail, kid et hmacKey. Exécutez simplement la commande ci-dessous et copiez le contenu de la page index.html dans le fichier lego.yml.
›› Afficher/Masquer le YML préparé.

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

Vérification des permissions et du propriétaire du fichier :

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

Émission du certificat SSL/TLS

Avant l'exécution, vérifiez echo ${DOMAIN} ou définissez la variable DOMAIN sur le nom de votre domaine DOMAIN="example.com". L'outil Lego effectue la validation HTTP-01 à l'aide d'un fichier temporairement stocké dans le webroot, vérifie la propriété du domaine puis crée un certificat SSL/TLS. Le certificat, la clé privée et le certificat de l'émetteur (intermédiaire) seront stockés dans le répertoire /etc/lego/${DOMAIN}/certificates/.

Pendant la génération, le client ACME Lego affichera des informations sur la requête :

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

Vérifier les fichiers du certificat SSL généré

Affiche le contenu du répertoire certificates créé par le service Lego, y compris le certificat, la clé privée et le certificat de l'émetteur pour le domaine sélectionné.

Le répertoire certificates/ contient les .crt, .key émis, les certificats intermédiaires de l'autorité de certification et les métadonnées.

Déploiement du certificat vers Apache

Cet exemple utilise la variable ${DOMAIN}, que vous devriez déjà avoir définie depuis le début du guide. Avant d'exécuter les commandes, vous pouvez vous assurer que la variable est correctement définie, par exemple : echo ${DOMAIN}
La variable ${DOMAIN} est utilisée dans le nom du fichier de configuration, les valeurs ServerName et ServerAlias ainsi que le chemin vers le webroot.
Attention ! - les chemins vers le certificat SSL et la clé privée utilisent le domaine sous la forme example-com. Les chemins doivent correspondre au domaine utilisé dans la configuration de Lego.

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}

Résultat : HTTPS fonctionnel.

Renouvellement automatique

Lego peut renouveler le certificat automatiquement, mais après l'installation il ne crée pas de lui-même les unités systemd pour une exécution régulière. Deux unités doivent donc être créées pour le renouvellement automatique :

• lego-example-com-renew.service – exécute la vérification et, si nécessaire, le renouvellement du certificat.
• lego-example-com-renew.timer – garantit que le service s'exécute quotidiennement à une heure définie.

Avant l'insertion, remplacez example-com dans le nom du service/timer par votre propre nom si nécessaire, et remplacez example.com dans le chemin de configuration par votre propre domaine.

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

Après avoir créé les unités, vérifiez leur contenu :

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

Rechargez les nouvelles unités, activez le timer et vérifiez qu'il fonctionne :

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

Résultat : le timer est actif et systemd a planifié sa prochaine exécution.

Test sûr du service :

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

Résultat : si le certificat n'est pas proche de l'expiration, Lego peut signaler que le renouvellement n'est pas nécessaire. C'est un comportement correct.

Liste des unités Lego disponibles :

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

systemctl list-timers | grep lego

Résultat : les deux variantes affichent tous les services et timers liés au client ACME Lego.

Où aller ensuite ?

• Protocole ACME
• Client ACME Lego (WildCard + API DNS)
• Client ACME Certbot
• Certificat SSL - Tout ce qu'il faut savoir