Ce que fait ce module #
Un certificat TLS est ce qui transforme http:// en https:// : il chiffre la connexion entre vos visiteurs et le serveur, et fait afficher au navigateur le cadenas au lieu d'un avertissement « non sécurisé ».
Le module tls gère tout le cycle de vie de ce certificat à l'aide de certbot : il le demande à Let's Encrypt (une autorité gratuite et bien reconnue), prouve que le domaine est le vôtre grâce au défi ACME, installe le certificat là où votre serveur web l'attend, et le renouvelle automatiquement avant qu'il n'expire — sans que vous ayez à y penser.
Votre domaine (p. ex. app.ejemplo.com) doit pointer via DNS vers l'IP de ce serveur, et le port 80 doit être joignable pour le défi HTTP-01. Sinon, l'émission échouera à l'étape de validation.
Tâches courantes #
Choisissez ce que vous voulez faire. Chaque recette fournit la commande déjà écrite — il suffit d'y mettre votre propre domaine et e-mail, et de cliquer sur Copier.
1
Émettre mon premier certificat
Obtenez le cadenas HTTPS pour votre domaine en une minute.
Connectez-vous en SSH à votre serveur en tant qu'utilisateur ubuntu.
Lancez la commande, en y mettant votre propre domaine et e-mail (l'e-mail sert uniquement à vous avertir si quelque chose est sur le point d'expirer) :
$ sudo imaxe tls issue app.ejemplo.com --email [email protected]Attendez quelques secondes. Vous verrez la progression du défi et, à la fin, la date d'expiration.
https:// avec le cadenas. Le renouvellement automatique est activé — vous n'avez rien d'autre à faire.2
Voir lesquels existent et quand ils expirent
Vérifiez l'état de vos certificats d'un coup d'œil.
Un résumé rapide de l'état général et du timer de renouvellement :
$ sudo imaxe tls statusVous voulez le détail domaine par domaine, avec les jours restants et le chemin de la fullchain ? Utilisez list :
$ sudo imaxe tls list3
Forcer un renouvellement
C'est généralement automatique, mais vous pouvez l'anticiper si besoin.
Renouvelez tous les certificats proches de l'expiration (c'est exactement ce que fait le timer) :
$ sudo imaxe tls renewVous voulez d'abord le répéter à blanc sans toucher au disque, ou renouveler même s'il reste des jours ? Ajoutez --dry-run ou --force :
$ sudo imaxe tls renew --dry-run
$ sudo imaxe tls renew --force4
Révoquer un certificat
Invalidez un certificat auprès de l'autorité (p. ex. si la clé a fuité).
Révoquez le certificat d'un domaine auprès de Let's Encrypt, en indiquant la raison si vous la connaissez :
$ sudo imaxe tls revoke app.ejemplo.com --reason keycompromiseissue.5
Supprimer un certificat du disque
Cessez de gérer un domaine que vous n'utilisez plus.
Retirez le certificat et ses clés du disque. Note : cela ne le révoque pas auprès de l'autorité — pour cela, utilisez d'abord revoke.
$ sudo imaxe tls delete tienda.ejemplo.comimaxe tls list et son renouvellement automatique s'arrête.Le problème le plus courant est que le DNS ne s'est pas encore propagé ou que le port 80 est fermé. Attendez quelques minutes et réessayez. Si cela persiste, essayez d'abord le mode test avec --staging (voir la référence) pour ne pas épuiser votre quota de tentatives.
Synopsis #
imaxe tls <subcomando> [<dominio>...] [--email CORREO] [flags]Les sous-commandes qui touchent aux certificats nécessitent les privilèges root (utilisez sudo) car elles écrivent dans /etc/imaxe/ et rechargent des services système. Ajoutez --json à list ou status pour une sortie lisible par machine, adaptée au scripting.
Sous-commandes #
| Sous-commande | Rôle | Flags pertinents |
|---|---|---|
| issue | Émet un certificat pour un ou plusieurs domaines, en résolvant le défi ACME. | --email, --webroot, --standalone, --staging |
| renew | Renouvelle les certificats proches de l'expiration et recharge le serveur web. Adapté à un timer. | --dry-run, --force |
| list | Liste les certificats gérés avec les jours avant expiration et le chemin de la fullchain. | --json |
| status | Résumé : nombre de certificats, ceux proches de l'expiration et l'état du timer de renouvellement. | --json |
| revoke | Révoque un certificat par domaine auprès de l'autorité (ACME). | --reason |
| delete | Supprime le certificat et ses clés du disque. Ne révoque pas auprès d'ACME. | — |
Arguments et flags #
| Flag | Type | Par défaut | Description |
|---|---|---|---|
| <dominio> req. | string… | — | Un ou plusieurs domaines pour le certificat. Dans issue, le premier est le principal (CN) ; les autres sont des SAN. Dans revoke/delete, le domaine sur lequel opérer. |
| string | tls.yml | E-mail de contact du compte ACME. Requis au premier issue ; ensuite, celui de tls.yml est réutilisé. | |
| --webroot | path | /var/www/html | Répertoire racine pour le défi HTTP-01. La méthode par défaut. |
| --standalone | bool | false | Utilise le serveur intégré de certbot au lieu d'un webroot. Nécessite que le port 80 soit libre. |
| --staging | bool | false | Utilise l'environnement de test de Let's Encrypt (ne compte pas dans la limite de débit). Le certificat ne sera pas approuvé. |
| --dry-run | bool | false | Dans renew, simule le renouvellement sans toucher au disque. |
| --force | bool | false | Dans renew, renouvelle même s'il n'est pas proche de l'expiration. |
| --reason | enum | unspecified | Dans revoke : unspecified, keycompromise, superseded, cessationofoperation. |
| --json | bool | false | Dans list/status, émet le résultat en JSON sur stdout. |
Fichiers et chemins #
| Chemin | Contenu |
|---|---|
| /etc/imaxe/tls.yml | Configuration du module : e-mail par défaut, méthode (webroot/standalone), webroot, staging, renouvellement automatique et hook de rechargement. |
| /etc/letsencrypt/live/<dominio>/ | Certificat (fullchain.pem) et clé privée (privkey.pem) gérés par certbot. |
| /var/log/imaxe/tls.log | Journal structuré de chaque émission, renouvellement et révocation. |
| imaxe-tls.timer | Timer systemd qui déclenche renew périodiquement. |
Exemple de tls.yml :
email: [email protected]
default_method: webroot
webroot: /var/www/html
staging: false
auto_renew: true
reload_hook: systemctl reload nginxCodes de sortie et logs #
Chaque exécution renvoie un code que vous pouvez vérifier avec echo $? — pratique pour enchaîner dans des scripts :
Suivez le log en direct pendant le débogage :
$ sudo journalctl -u imaxe-tls -f
$ sudo tail -f /var/log/imaxe/tls.logExemples avancés #
Plusieurs domaines dans un seul certificat
Le premier domaine est le principal ; les suivants sont ajoutés comme SAN, tous dans un seul certificat :
$ sudo imaxe tls issue ejemplo.com www.ejemplo.com \
--email [email protected]Un test sûr avant la production
Validez toute la chaîne contre l'environnement de test pour ne pas épuiser votre quota réel. Avec --standalone, vous n'avez pas besoin d'un serveur web configuré :
$ sudo imaxe tls issue app.ejemplo.com \
--email [email protected] --standalone --staging \
|| echo "falló con código $?"Résolution des problèmes #
| Symptôme | Cause probable | Solution |
|---|---|---|
| Renvoie CHALLENGE (code 3) | Le domaine ne résout pas vers cet hôte ou le port 80 est fermé. | Vérifiez l'enregistrement A/AAAA et ouvrez le port 80 dans le security group ; réessayez. |
| Renvoie RATELIMIT (code 4) | Trop d'émissions du même domaine en une semaine. | Utilisez --staging pour tester ; attendez que la fenêtre se libère. |
| HTTPS se charge mais avec un avertissement | Émis avec --staging : le certificat n'est pas approuvé. | Réémettez sans --staging pour en obtenir un valide. |
| Renvoie RELOAD (code 5) | Le reload_hook pointe vers un service inexistant. | Ajustez reload_hook dans tls.yml et relancez renew. |
Bloqué sur le module TLS ?
Écrivez-nous avec la sortie de « imaxe <module> status --json » et nous vous répondons rapidement.