Custom Deployment

From the Enterprise edition, you can deploy certificates to targets that TLSPilot does not support natively, using your own PowerShell scripts, which can also call other tools, for example to connect to a Linux server via SSH. Example scripts for deployments and Health checks are provided under %ProgramData%\iTrain\TLSPilot\Examples\Custom Deployment Script Examples, for FortiGate, Cisco ASA, Cisco FDM and Caddy, each with a deployment script and a Health check script, plus a Health check script that compares the thumbprint. The examples are provided without support. Any credential type can be used for a custom deployment, for appliances typically Custom / other. This example deploys a certificate to Caddy on a Linux server.

The script runs on the management host as the TLSPilot service account, not over WinRM, so any module or tool it uses, for example an SSH module, must be available to that account. The certificate files for the script are written to a temporary folder that exists only while the script runs.

1. Click the tile Credentials on the dashboard to open the Credentials Manager and create an SSH credential for the target as described in chapter Nginx, preferably with a private key.
2. Issue a certificate from any issuer as described in chapter My first certificates, for example “caddy.tlspilotlab.com”. In the step Deployments, switch on Automatic deployment and click Add…
3. Linked service: Select Custom Deployment at the end of the list.
4. Display name, Target host and Credential: Enter a name for the deployment and the name or IP address of the server, and select the credential from step 1. If your script needs the private key as Encrypted PEM, enter a password for it under Key password.
5. Shell: Select Windows PowerShell or PowerShell 7 (pwsh). If pwsh.exe is not found, TLSPilot uses Windows PowerShell.

6. Deployment Script: Enter the script that deploys the certificate. TLSPilot provides the variables $Cert, $Target and $Cred, see chapter Variables in custom scripts. The deployment fails when the script exits with a non-zero code, throws an error, or its last output is $false. Text written before that $false is shown in the result and the history and does not change the decision. The script may run for up to 300 seconds; after that, TLSPilot stops it and the deployment fails with Custom script timed out after 300s.
   • Previous certificate (optional): TLSPilot cannot read the target of a custom deployment itself. To report the certificate that your script replaced, write the line PREVIOUS|<thumbprint> with Write-Output, for example Write-Output "PREVIOUS|$oldThumbprint". TLSPilot shows it as Previous thumbprint in the result, the history and the alert mail. Without this line, the row Previous thumbprint is omitted. The first line that starts with PREVIOUS| counts; the line is evaluated only for the deployment script.

7. Health Check Script: Optionally, enter a script that checks whether the certificate is in use. It can use the same variables as the deployment script. TLSPilot evaluates the last output of the script: $true means Healthy, $false means Unknown. A line HEALTH|Status|Message written with Write-Output, for example HEALTH|Drift|Old certificate bound, sets that status and message; Drift makes the daily cycle deploy the certificate again. Status is Healthy, Drift, Unknown, Unreachable or Skipped. Optionally, add the thumbprint read on the target as fourth field, for example HEALTH|Healthy|Bound|<thumbprint>. The first HEALTH| line takes precedence over $true or $false. The script may run for up to 75 seconds. If it times out, exits with a non-zero code, throws an error, or ends without $true, $false or a HEALTH| line, the target is reported as unreachable. If the field is empty, TLSPilot cannot detect drift on this target: the daily cycle deploys it when it does not hold the current certificate, and skips it when it does. The tab of the deployment states this.

8. Click OK, complete the remaining steps as described in chapter My first certificates and issue the certificate with Issue now.

TLSPilot issues the certificate, runs your deployment script and checks the Health with your Health Check Script. If the deployment fails, the result shows the line of the script that caused the error. To correct the script, double-click the deployment in the tab Deployments of the certificate, make your changes, and click OK and Save. Then right-click the certificate, choose Deploy… and confirm with Deploy. This deployment runs immediately, regardless of whether the certificate has been renewed. As the deployment depends on your script and Test (dry run)… is not available for custom deployments, check on the target system that the certificate is in use.

Variables in custom scripts

The following variables are available in the deployment script and in the Health Check Script:

Aliases are also available: $Certificate, $TargetHost, $Credential, $PfxPath, $Thumbprint, $PemCertPath, $PemKeyPath, $PemBundlePath and $CredentialTarget.

Return values of the Health Check Script: TLSPilot sets the health of the target from the output of the script.