Distribute Certificates

Certbot supports using the --deploy-hook parameter to trigger scripts that can distribute certificates to their intended destinations. Such a script could for example use SCP (Secure Copy Protocol) to distribute the certificate to a different server or device.

Consider the following example script deploy.sh:

#!/bin/bash

# Copy certificate files to another host
scp "$RENEWED_LINEAGE"/*.pem otherserver.example.com:/location/

We can now use this script in the following way:

certbot certonly --server acme.networking4all.com/dv -d example.com --deploy-hook /path/to/deploy.sh

When Certbot finished receiving the new certificate it will set the $RENEWED_LINEAGE environment variable and execute deploy.sh. This variable merely contains the path to where the certificate is stored locally, usually /etc/letsencrypt/live/<common-name>. The script will in turn copy the relevant data (cert.pem, chain.pem, fullchain.pem, privkey.pem) to otherserver.example.com at /location/. The script will automatically be executed on any future renewal request unless it is manually removed from the configuration file which is usually found at /etc/letsencrypt/renewal/<common-name>.conf.

For a more dynamic approach the $RENEWED_DOMAINS environment variable is available to retrieve a list of space-delimited domains related to the order.

Acme.sh supports various ways for you to distribute your certificates post issuance.

Native deploy method

This method can be used to trigger scripts that distribute certificates to their intended destinations. The deploy functionality from acme.sh comes with several pre-made deploy scripts including ssh, docker, NGINX, gitlab, and many more. As the --deploy-hook can not be ran in combination with your initial --issue request you will need to run the --deploy command after the certificate has initially been issued. After using it with --deploy once it will be saved and executed on every future renewal.

For this example we will be using the SSH deploy hook, which uses SCP (Secure Copy Protocol) to distribute the certificate to a different server or device, but we suggest you explore the available hooks to see if others might be a better fit for your situation. It is also possible to use your own custom deploy hook by simply placing the script in the acme.sh/deploy folder.

For the SSH hook we first need to set up some environment variables:

export DEPLOY_SSH_USER=<ssh-username-here>
export DEPLOY_SSH_SERVER="otherserver.example.com"
export DEPLOY_SSH_KEYFILE="/etc/ssl/example.com.key"
export DEPLOY_SSH_CERTFILE="/etc/ssl/example.com.pem"
export DEPLOY_SSH_FULLCHAIN="/etc/ssl/example.com_full.pem"
export DEPLOY_SSH_REMOTE_CMD="systemctl restart nginx"

We can now use this hook in the following way:

# Issue the certificate first
./acme.sh --server acme.networking4all.com/dv --issue -d example.com -w /var/www/example.com/

# Deploy the certificate utilizing the SSH hook
./acme.sh --deploy -d example.com --deploy-hook ssh

This hook will copy the relevant data (in this case the private key, certificate, and full chain certificate) to otherserver.example.com at /etc/ssl/ and then restart NGINX.

Post-hook and reloadcmd methods

An alternative to the deploy method is using the --post-hook and/or --reloadcmd hooks to run commands post issuance. These hooks can be used with your initial --issue command and will be automatically executed on future renewals. Note that the --post-hook is executed whether the certificate was issued or not so you can not rely on this hook alone to be certain that the certificate was issued when it is executed. The --reloadcmd hook however is only executed when the certificate was successfully issued.

Consider the following example script post-hook.sh:

#!/bin/bash

# Check if CERT_FULLCHAIN_PATH is set
if [ -z "$CERT_FULLCHAIN_PATH" ]; then
  echo "Error: it seems like we failed to issue a certificate for '$Le_Domain'." >&2
else
  # Proceed with copying the certificate
  scp "$CERT_FULLCHAIN_PATH" otherserver.example.com:/location
fi

We can now use this script in the following way:

./acme.sh --server acme.networking4all.com/dv --issue -d example.com -w /var/www/example.com/ --post-hook "/path/to/post-hook.sh"

When acme.sh finished receiving the new certificate it will set the $CERT_FULLCHAIN_PATH environment variable and execute post-hook.sh. This variable contains the full path to where the full chain certificate is stored locally. The script will in turn copy the certificate to otherserver.example.com at /location/.

Other relevant variables you might want to use in your script are CERT_PATH, CERT_KEY_PATH, CA_CERT_PATH, DOMAIN_PATH, Le_Domain.

Simple-acme comes with various store plugins such as Azure Key Vault and the Windows Certificate Store which might already be compatible with your current distribution methods.

Simple-acme also supports using the --installation script --script <script> parameter to trigger scripts that can distribute certificates to their intended destinations. Simple-Acme comes with several pre-made (example) deploy scripts which can be found here or at your simple-acme installation directory under Scripts. This includes examples for Active Directory, Azure, Exchange, NTDS, WinRM, and Windows Admin Center (for IIS bindings documentation can be found here). You can however provide your own .bat, .exe, .sh, or .ps1 as a parameter to run custom scripts or executables.

For example, using the pfxfile store plugin like so: --store pfxfile --pfxfilepath 'C:\local\cert\path\' --pfxfilename pfxfile --installation script --script C:\path\to\pfxfile-example.ps1 --scriptparameters "{StorePath}"

Consider this script pfxfile-example.ps1:

param (
    [string]$StorePath # {StorePath} passed by simple-acme
)

$RemotePath = 'C:\remote\path\'
$Session = New-PSSession -ComputerName "ExampleServer" -Credential "Example\User"

Copy-Item $StorePath -Destination $RemotePath -ToSession $Session

$ScriptBlock = {
    $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
    $cert.Import(($RemotePath + 'pfxfile.pfx'))

    $store = New-Object System.Security.Cryptography.X509Certificates.X509Store "AcmeTest", "LocalMachine"
    $store.Open("ReadWrite")
    $store.Add($cert)
    $store.Close()
}

Invoke-Command -Session $Session -ScriptBlock $ScriptBlock

This script copies a local PFX certificate which was issued through Networking4all using simple-acme to a remote server and then imports it into the local certificate store on the remote server.