Certbot Hook Directories

In Certbot’s next minor release, we are planning on adding hook directories to Certbot to allow users and package maintainers to add scripts to be run during certificate renewal by simply placing an executable file in the appropriate directory. We wanted to post the proposed design of this system publicly to get feedback on it and to make sure it covers the majority of the desired use cases. If you are not already familiar with hooks in Certbot, see the documentation about the --pre-hook, --deploy-hook, and --post-hook flags found at https://certbot.eff.org/docs/using.html#renewing-certificates.

The proposed design is to create a directory named something like “renew-hooks” in Certbot’s configuration directory (which is located at /etc/letsencrypt by default). Inside of this directory are three additional directories called “pre”, “deploy”, and “post” where hooks of each type can be placed. Certbot will create this directories itself if not already done so by the packaging system that installed Certbot.

When Certbot is run with the “renew” subcommand and there are certificates due for renewal, all executable files found in these directories will be run like other hooks of the same type and will run in addition to any hooks defined through existing means such as the command line, INI configuration file, or renewal configuration file. Hooks defined in these directories will not be stored in renewal configuration files, but they will continue to be run when certificates are renewed with the “renew” subcommand as long as they remain in the appropriate directory.

Hooks defined in these directories will only be run with the “renew” subcommand and will be ignored when running with the “certonly” or “run” subcommands. If you want to use hooks with these other subcommands, you will have to define them on the command line or Certbot INI file.

If anyone has any feedback on this plan, we’d love to hear it!


It might be nicer to make the directory called “hooks” and inside put “pre-renew, deploy-renew, post-renew directories” so you can expand in the future if you want to do similar for certonly or other commands.

how do you plan to deal with different extension types

for example bash vs python vs perl scripts?


@ahaw021, on Unix a script can specify its own interpreter, and the OS kernel will then run that interpreter to interpret the script.

This means that people writing scripts for any of those interpreters don’t have to tell Certbot what the intended interpreter is, as long as the first line of the script specifies it appropriately. :slight_smile:

1 Like

thought that might be the case :smiley:

It’s good to have this explained somewhere explicitly (e.g. best practices)

I notice that the scripts you have posted do that but have noticed other people specifying for example python script.py


Hi @bmw,

What is the order of execution of scripts inside these new directories?

I mean, I don’t know if you will execute the scripts in alphabetical order or you will use another approach.

Using alphabetical order we can define the order simply naming our scripts like:


and I think it should be a good idea to documment this behaviour and provide some examples.

Good job team :wink:


1 Like

Whether or not these hooks also ran for other subcommands was one of the main points of discussion we had about this issue. In general, we felt what people really wanted was the ability to set hooks to run for renewal and some people specifically wanted the ability to set hooks to run for only the “renew” subcommand. With the “certonly” and “run” subcommands only ever issuing (at most) a single cert, the ability to set hooks becomes much less useful.

We have no plans to add hook directories for the other subcommands, but if we did I think we could create a /etc/letsencrypt/issuance-hooks directory to accomplish largely the same effect with the small downside of there being an additional directory in the top level of /etc/letsencrypt.

The order is undefined right now! Thanks for bringing this up. While I think this is a minor point as users should be able to create a wrapper script to run their scripts in a specific order if it matters, I can make the hooks run in alphabetical order in case anyone wants to take advantage of this functionality.

1 Like

That sounds potentially useful to me somehow.

I wrote a set of shell scripts to do something similar, with the difference that the “deploy” hook runs an executable only if its name matches a domain that has been renewed. Might not be useful for everybody, though.

I think even as described this would be a very helpful addition!

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.