TBSCertBot - The Quick Start Guide
Once your API user is created, launching TBSCertBot is only a matter of minutes? You'll find the essential steps to the tool installation and use below.
Prerequisites
TBSCertBot works with php 5.4 and above.
Note: TBSCertbot autodetects and installs dependencies. However, if you encounter difficulties, we invite you to update your libraries:
#composer update
1 - Create an API user
Before using TBSCertBot an API user needs to be created.
Warning: TBSCertBot is available in a test and a production environment. You'll have to create an API user for each of the environment you want to work on.
To do so, log on to your Certificate Center (on the desired environment) and go to the "Administration" > "Users" section.
From this page you'll be able to create one (or several) API user.
Test environment:
open an account /
access the account
Production environment
open an account /
access the account
2 - Install TBSCertBot
First, download TBSCertBot.
Unzip the archive. A TBSCertBot repertory is create and the libraries required for the tool to work correctly are automatically updated.
# tar jxvf tbscertbot.tar.bz2
3 - TBSCertBot configuration
TBSCertBot requires a configuration file to function. This file contains all the elements needed to manage a certificate: API username and password, certificate type, validity, organization, DCV method, etc.
Retrieve a configuration file from a certificate order
It is possible to generate a configuration file from a folder. This file will then be populated with the data of the chosen certificate.
Note: The download button is present on any certificate status page supported by the API.
You will be able to choose the server you want to use TBSCertBot on as well as an API user.
Once the file is downloaded and saved in the data/ directory of TBSCertBot, you simply need to add the password of the selected API user.
Create a configuration file
If you don't have a configuration file, then run TBSCertBot. It first checks for the presence of a configuration file. If there isn't one, it will prompt you to create one:
php tbscertbot.php The config file doesn't exist. Do you want create a new config file ? [Y/n]
You'll be asked for your API login and password and the server on which you want TBSCertBot to work on.
Before ordering a certificate you need to edit the configuration file to provide the default information regarding your orders to come: certificate kind, validity, organization, DCV method...
It is possible to order a cert without editing the configuration file but you then have to provide all the information in prompt mode.
4 - Order a certificate
TBSCertBot is now ready to be used. Ordering a certificate is quite simple:
# php tbscertbot.php order
Once the certificate is ordered, the TBS reference is displayed.
When the certificate is ready, launch the "download" command to download your product. By default the certificate and the certification chain are installed in the /data/certs/ repertory while the private key is stored in the /data/keys/ one.
5 - Hooks
Hooks allow you to associate scripts to the end of some operations, like orders, renewals and downloads.
In the following example, a hook is created to indicate a specific repertory for the certificate installation after its deliverance. The hook is executed after the "download" command.
First provide the path to the hook in the configuration file. Then create / modify the hook file to indicate the new installation directory for your certificate, certification chain and private key.
Note: You can create as many hooks as you like. A testing feature called "test-hook" exists within TBSCertBot specifically for testing your hooks.
How to test 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.