Automate your certificate orders and renewals using TBSCertBot
Prerequisite: TBSCertBot is compatible with php 5.4 to 7.x
Overview
TBSCertbot allow many automation ways:
- The Hook feature allows you to assign scripts to the end of commands.
- The cron command allows you run a combine download and renew, to check for both new deliveries and renewable certificates.
Deployement
We will describe the procedure to run a periodic download and certificate install.
Configuring hooks in TBSCertBot
TBSCertBot allows you to associate scripts to the end of some operations, like orders, renewals and downloads.
Example scripts are provided with TBSCertBot in the userdoc/examples/hooks subdirectory. We will detail their use.
To link a script to a hook, you need to edit the configuration file data/conf.ini to add the path to the script, e.g.:
… [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 …
Environment variables are set so that you can use them in your scripts:
- PHP_TBS_REFERENCE: The TBS Reference of your order
- PHP_TBS_CN: Your certificate's common name (CN)
- PHP_TBS_SAN: A comma-separated list of your certificate's SAN
- PHP_TBS_KEY: The absolute path to the private key
- PHP_TBS_CERT: The absolute path to the certificate
- PHP_TBS_CHAIN: The absolute path to the certificate chain
- PHP_TBS_DCV: The absolute path to the HTTP DCV file
DCV
Sectigo, TBS X509 and PositiveSSL products require a domain validation called DCV Challenge.DCV Challenge.
The dcv_order_hook.sh script, placed in the directory doc/examples/hooks of your TSCertBot install, can easily place your HTTP DCV file to your webserver's root.
Simply edit the path to your webserver's root.
The script also shows how to use the CN mane in paths and filenames.
Linking the certificate files on delivery
The install_download_hook.sh example script, located in the doc/examples/hooks subdirectory of your TBSCertBot install can automatically link certificate files (key, certificate, and chain) in a folder of the web server so that they are automatically used.
You will need to edit your ssl directory if you wish to use it.
Periodically running TBSCertBot
The last step of your automation process is configuring your system to periodically run TBSCertBot. Two examples are provided: one using systemd timers, and the other one using a cron job.
Using systemd
If you use the systemd init, you can use its integrated timer feature.
Two example files are available in the doc/examples/systemd/ subdirectory of your TBSCertBot install. The .timer file is defined to run the .service file every morning at 04:00, localtime.
The service file runs TBSCertBot. You will need to edit the path before use.
Using Cron
If you have an enabled cron system, you can use it to periodically run TBSCertBot.
The command crontab -e allows you to edit the current user crontab that will contain various tasks to run. The command use the environment variable EDITOR or if not set, the editor vi.
You can then add on a new line:
* 4 * * * cd /path/to/tbscertbot/ && /usr/bin/php /path/to/tbscertbot/tbscertbot.php cron
This line will run the cron job every morning at 04:00. After saving the file, crontab will check the syntax validity.