Automatisez vos commandes et renouvellements de certificats à l'aide de TBSCertBot
Pré-requis
TBSCertBot fonctionne avec php 5.4 et supérieur.
Note : TBSCertbot autodétecte et installe des dépendances. Cependant si vous rencontrez des difficultés, nous vous invitons à mettre à jour vos librairies :
#composer update
Présentation
TBSCertBot offre de nombreux moyens d'automatisation :
- La fonctionnalité des Hooks (crochets, points d'accroche) vous permet d'assigner l'exécution d'un script à la fin d'une commande.
- La commande cron vous permet, d'une manière combinée, de lancer les commandes download et renew pour vérifier la livraison de nouveaux certificats puis de renouveler les certificats arrivant à expiration.
Mise en place
Nous allons décrire la procédure pour mettre en place un lancement périodique de ce mode afin d'automatiser votre renouvellement et votre installation de certificat.
Configuration des Hooks dans TBSCertBot
TBSCertbot vous permet d'associer des scripts à la fin de certaines opérations dont la commande, le renouvellement, ou le télechargement d'un certificat.
Des scripts d'exemples sont fournis avec TBSCertbot dans le sous répertoire userdoc/examples/hooks. Nous allons détailler leur utilisation.
Pour lier un script à un hook, vous pouvez éditer votre fichier de configation data/conf.ini pour ajouter le chemin vers un script. Par exemple :
… [HOOKS] ; These parameters must be a valid path to a script or binary executable, or a valid command if used ; Use at your own risk. TBS Internet is not responsible for any damage caused by third party software. dcv = /chemin/vers/tbscertbot/userdoc/examples/dcv_order_hook.sh download = /chemin/vers/tbscertbot/userdoc/examples/install_download_hook.sh …
Des variables d'environnement sont mises à dispostion des scripts si les valeurs existent :
- PHP_TBS_REFERENCE : La référence TBS de votre commande
- PHP_TBS_CN : Le CN (Common Name) de votre certificat
- PHP_TBS_SAN : Une liste des SAN inscrits dans votre certificat, séparés par des virgules.
- PHP_TBS_KEY : Le chemin absolu vers la clé privée
- PHP_TBS_CERT : Le chemin absolu vers le certificat
- PHP_TBS_CHAIN : Le chemin absolu vers le fichier de chaine de certification
- PHP_TBS_DCV : Le chemin absolu vers le fichier de DCV HTTP
- PHP_TBS_DCV_METHOD : Méthode de DCV (par exemple, dns-txt-token ou dns-cname-token)
- PHP_TBS_DCV_DOMAIN_ROOT : Domaine racine pour le DCV
- PHP_TBS_DCV_DOMAIN_SUB : Sous-domaine pour le DCV
- PHP_TBS_DCV_VALUE : Valeur pour le DCV
- PHP_TBS_DNS_ACTION : Action pour le DNS (CREATE ou UPDATE)
- PHP_TBS_REGISTRAR : Registrar du domaine (par exemple GANDI SAS ou OVH SAS)
Comment tester vos hooks ?
Vous pouvez créer autant de hooks que vous le souhaitez. Une fonctionnalité de test intitulée « test-hook » existe au sein de TBSCertBot spécifiquement pour tester vos hooks.
Pour tester un hook, il faut utiliser la commande :
php tbscertbot.php test-hook NOM_DU_HOOK [Référence TBS].
La référence TBS est optionnelle. Indiquez-là si vous souhaitez tester votre hook sur une commande sépcifique. Exemple :
php tbscertbot.php test-hook download 1234567890.
Cette commande relancera le script lié au hook de téléchargement sur la commande 1234567890. Vous trouverez quelques exemples de hooks dans le répertoire data/testhooks de votre installation TBSCertBot.
Validation DCV
Les produits Sectigo (Sectigo, TBS X509, PositiveSSL) et DigiCert (DigiCert, Thawte, Geotrust, RapidSSL) nécessitent une validation du nom de domaine appelée Challenge DCV.
Le script dcv_order_hook.sh, situé dans le répertoire userdoc/examples/hooks de votre installation TBSCertBot vous permettra de placer automatiquement le fichier nécessaire à la méthode de validation HTTP(S) à la racine de votre serveur web si vous avez choisi la méthode par fichier HTTP ou HTTPS.
Éditez simplement le chemin vers votre serveur web.
Ce script montre également comment utiliser le nom du CN dans les chemins et noms de fichiers.
Pour la méthode DNS, le script dcv_order_hook.sh exécutera script spécifique à votre registrar qui mettra en place l'entrée choisie dans votre configuration DNS.
Voir nos exemples de scripts pour l'automatisation des validations DCV :
- Mise en place de hook pour le DCV DNS dans TBSCertBot
- Mise en place de hook pour le DCV HTTP/HTTPS dans TBSCertBot
Liaison des fichiers de certificat à la livraison
Le script d'exemple install_download_hook.sh présent dans le répertoire userdoc/examples/hooks de votre installation TBSCertBot vous permettra de lier automatiquement les fichiers de certificat (clé, certificat et chaine) dans un dossier du serveur web pour qu'ils soient automatiquement utilisés.
Il vous faudra éditer votre répertoire ssl dans le script si vous désirez l'utiliser.
Lancement périodique de TBSCertBot
La dernière étape de votre processus d'automatisation consiste à configurer votre système pour lancer périodiquement TBSCertBot. Deux exemples sont fournis : avec timers systemd et avec un cron.
Avec Systemd
Si vous utilisez le système d'init Systemd, vous pouvez utiliser sa fonctionnalité intégrée de timers.
Deux fichiers d'exemples sont disponibles dans le répertoire doc/examples/systemd/ de votre installation TBSCertBot. Le fichier d'extension .timer est défini pour exécuter le fichier de service d'extension .service chaque matin à 04:00, heure locale du serveur.
Le fichier de service exécute TBSCerbot, il vous faudra éditer le chemin avant utilisation.
Avec Cron
Si vous disposez d'un service de cron activé, vous pouvez utiliser ce dernier pour lancer périodiquement TBSCertBot.
La commande crontab -e vous permettra d'éditer le crontab de l'utilisateur courant qui contient les différentes tâches à lancer. Cette commande utilise la variable d'environnement EDITOR ou si elle n'est pas affectée, l'éditeur vi.
Vous pourrez alors ajouter sur une nouvelle ligne :
0 4 * * * cd /chemin/vers/tbscertbot/ && /usr/bin/php /chemin/vers/tbscertbot/tbscertbot.php cron
Cette ligne lancera le cron chaque matin à 04:00. À la sauvegarde du fichier, crontab vérifiera la validité de sa syntaxe.