Custom hook confusion

[Codelica]

Hello... thanks for this project, it's been working great for me across many domains. :)

I'm just a little confused about the custom hook capabilities as described here.

It details creating a executable file named deploy-hook.sh, but doesn't mention where this file should be located?

Also the example shows setting the DEPLOY_HOOK env var to create-nginx-certs which doesn't seem to be a reference to the script name or anything in particular ?

And I guess finally, I see a directory named renewal-hooks with subdirectories of deploy, post, and pre, which I couldn't find documentation on. Are those used or involved in any way?

Any insight would be appreciated, and sorry if I've overlooked something. Thanks!

[adferrand]

Hello!

Indeed there is several things to explain about hooks, that are related to Certbot, the ACME client used in my Docker.

Certbot recognizes three types of hooks : pre, post and deploy. Pre is executed before a certificate creation or tentative of renewal, post after it, and deploy when a certificate is actually deployed.

These scripts can be passed to Certbot in two ways: by command line or in a specific location.

First, the command line. You pass the name of the script as a flag to the Certbot command, like --deploy-hook. The trick is that the script must be findable in the PATH, so it is something that you could run in a shell using directly the name of the script, without its full path.

That is why in my example the create-nginx-certs in /usr/bin, because this folder is in the PATH by default.

Second, the specific locations. As you certainly understood now, these locations correspond to the renewal-hooks folder, and every script located in pre, post or deploy will be executed accordingly as a pre, post or deploy hook.

So far so good, but verbatim capabilities of Certbot have several limitations, in particular when run in a Docker.

About the flag approach, the problem is that --deploy-hook flag is already used in my Docker for a lot of logic around the certificates deployments. And anyway, it would require to rebuild a Docker on top of mine to modify the parameters to Certbot. Also, in theory you need the hook to be in the PATH. You could have unexpected results if you try to use a built-in shell command (like echo), or a full path. About the specific locations, well, the big thing is that the folder is called renewal-hooks: these hooks are called for a renewal, NOT for a new certificate creation. And you need anyway find someway to copy the files, either as a volume, or by building a Docker on top of mine, in a folder (/etc/letsencrypt) that is already persisted...

So, I recommend the DEPLOY_HOOK env variable approach, that is specific to my Docker. In fact, the internal deploy script will call DEPLOY_HOOK if set as a shell command. So anything that is a valid shell command can be used, including scripts in PATH of course, but also anything that is a built-in shell command, and with args passed to it if you want. This file can be inserted as a volume, or included during a build, in any location that suits you.

I hope I was clear, because this problematic is really not obvious, and the hooks scripts is an API we want to improve on Certbot since a long time...

[Codelica]

Thanks for all the info!

So I'll definitely go the DEPLOY_HOOK route. I just found what I was overlooking :) I didn't realize the script name was "changed" via the volume mount.

--volume /etc/letsencrypt/deploy-hook.sh:/usr/local/bin/create-nginx-certs \

Which explains why DEPLOY_HOOK is set to that.

Thanks again!