Automate your certificate orders and renewals using TBSCertBot
Prerequisites
TBSCertBot works with php 5.4 and above.
TBSCertBot also requires these modules:
- php-curl
- php-cli
- openSSL
- rarely: php-xml
Note: TBSCertbot autodetects and installs dependencies. However, if you encounter difficulties, we invite you to update your libraries:
#composer update
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
- PHP_TBS_DCV_METHOD: DCV method (e.g. dns-txt-token or dns-cname-token)
- PHP_TBS_DCV_DOMAIN_ROOT: Root domain for DCV
- PHP_TBS_DCV_DOMAIN_SUB: Subdomain for DCV
- PHP_TBS_DCV_VALUE: DCV value
- PHP_TBS_DNS_ACTION: Action for DNS (CREATE or UPDATE)
- PHP_TBS_REGISTRAR: Domain registrar (e.g. GANDI SAS or OVH SAS)
How to test your hooks?
You can create as many hooks as you like. A testing feature called "test-hook" exists within TBSCertBot specifically for testing your hooks.
To test a hook, you must use the command:
php tbscertbot.php test-hook NAME_OF_THE_HOOK [TBS reference].
The TBS reference is optional. Indicate it if you want to test your hook on a specific command. Example:
php tbscertbot.php test-hook download 1234567890.
This command will restart the script related to the download hook on command 1234567890. You can find some example hooks in the data/testhooks directory of your TBSCertBot installation.
DCV
Sectigo (Sectigo, TBS X509 and PositiveSSL) and DigiCert (DigiCert, Thawte, Geotrust, RapidSSL) products require a domain validation called DCV Challenge.
The dcv_order_hook.sh script, placed in the directory userdoc/examples/hooks of your TSCertBot install, can easily place your HTTP DCV file to your webserver's root if you chose the file method.
Simply edit the path to your webserver's root.
The script also shows how to use the CN mane in paths and filenames.
For the DNS method, the script dcv_order_hook.sh will execute another script, specific to your registrar, that'll create or update the entry in your DNS configuration.
See our sample scripts for automating DCV validations:
Linking the certificate files on delivery
The install_download_hook.sh example script, located in the userdoc/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 manually create the file "/etc/cron.d/tbscertbot" with the following content:
1 */12 * * * root perl -e 'sleep int(rand(43200))' && cd /usr/local/tbscertbot && /usr/bin/php tbscertbot.php cron
This line will run the cron every 12 hours. When the file is saved, crontab will check its syntax for validity.