Documentation : --install-cert vs. deploy scripts

[jlecour]

Hi,

I'm currently trying to move from certbot to acme.sh and I have some difficulties to understand the differences betwen the --install-cert step and the deploy hooks that are available.

I understand that when a certificates has just been issued it simply exists inside acme.sh own directory and that we must not use them directly.

I understand that there is a single "install" profile (that we can see in the acme.sh/my-domain/my-domain.conf). This profile describes where the certificate/chain/key are stored and an optional reload command. It seems that the install action is "just" a couple of cat commands to copy the files into the desired destination and after them, the reload command is run. It seems that when the certificate is renewed, the same actions (cat and reload) happen automatically.

The deploy hooks seem to allow much more complex actions : copy the files over SSH, deploy combined files to HAProxy… If the reload logic is present in the deploy script then it's there, but for example the "apache" and "nginx" deploy scripts are empty.

I don't understand if and how the deploy scripts can be automatically run when a certificate is renewed. Should I create a custom script which runs all the deploy scripts I want (with the correct environment variables) and set it to run as "reloadcmd" ?

Here are a few complete examples that I have in mind :

1. From a server that responds to the example.com domain, I want to issue a certificate that I can use locally (with Apache for example), but also on a remote mail server (deployed over SSH).
2. In a setup with 2 load-balancers, I want to have one of them issue/renew certificates, that are locally deployed to HAProxy, but also deployed to HAProxy on the other load-balancer (over SSH).
3. A wildcard certificate issued/renewed on a server, but deployed over SSH on many remote servers (mail, FTP, web…).

Thanks for your help

[Neilpang]

I don't understand if and how the deploy scripts can be automatically run when a certificate is renewed.

It will run when the cert is renewed successfully. Just same as the reload-cmd .

Should I create a custom script which runs all the deploy scripts I want (with the correct environment variables) and set it to run as "reloadcmd" ?

No, but the ssh deploy hook supports to deploy to multiple ssh servers.

[jlecour]

Hi @Neilpang

Thanks for your answer. Initially I was disappointed because you've answered just a small part of my interrogations, but, I've tried to investigate based on your information and I've found the path to all my answers.

I had already tried to "install" a test cert in a target directory and noticed that the fine names and the reload command had been stored ib the certificate configuration file. This morning, I've tried to use the ssh deploy to copy the cert to a remote server over SSH. Obviously it worked, but the epiphany happend when I noticed that the deploy hook configuration had also been stored in the cert configuration :

Le_DeployHook='ssh,'
Le_Deploy_ssh_user='jlecour'
Le_Deploy_ssh_server='::1'
Le_Deploy_ssh_backup='yes'
Le_Deploy_ssh_backup_path='.acme_ssh_deploy'
Le_Deploy_ssh_keyfile='/tmp/prikey.pem'
Le_Deploy_ssh_fullchain='/tmp/fullchain.pem'

It show that the acme.sh --deploy --deploy-hook ssh […] has to be run once, and that many hooks can be configured to be run at renew-time.

So, I'll try to answer my own question and use cases.

From a server that responds to the example.com domain, I want to issue a certificate that I can use locally (with Apache for example), but also on a remote mail server (deployed over SSH).

# acme.sh --issue --domain www.example.com […]
# acme.sh --install-cert --domain www.example.com  --key-file /etc/apache2/ssl/www.example.com.privkey.pem --fullchain-file /etc/apache2/ssl/www.example.com.fullchain.pem --reloadcmd "systemctl reload apache2
# DEPLOY_SSH_USER=jlecour […] acme.sh --deploy --domain www.example.com --deploy-hook ssh

Then at each renew, the install step and all the hooks will be executed.

In a setup with 2 load-balancers, I want to have one of them issue/renew certificates, that are locally deployed to HAProxy, but also deployed to HAProxy on the other load-balancer (over SSH).

After issuing the certificate, no need to install the cert, but an haproxy hook will set HAProxy locally, and an ssh hook will copy it on the second load-balancer.

I still have to figure how to execute the haproxy hook remotely.

A wildcard certificate issued/renewed on a server, but deployed over SSH on many remote servers (mail, FTP, web…).

Same as before : no instal step, but several ssh deploy hooks to copy the files on the remote servers.

I still have to figure out how to execute different scripts on remote servers.