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.
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.
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!