Certbot renewal hook priority

Help
1

The Certbot manual lists four ways to set renewal hooks:

  1. Command line arguments (certbot renew --pre-hook)
  2. Certificate renewal config files (certbot reconfigure --pre-hook)
  3. The global Certbot config file (e.g., /etc/letsencrypt/cli.ini)
  4. The renewal hook directories (/etc/letsencrypt/renewal-hooks/pre)

The renewal hook directory contents are always run for any renewal attemp by default, but how are the other three options prioritized?

Also, are there any addional ways to set renewal hooks apart from these four?

2

1/2 writes to 4: 3 changes where 4 should be

1 Like
3

1 and 2 write to the renewal hook directories? That doesn't sound quite right.

4

sorry I misread: prehook thing blown up 1/2 is that linage specific and written to each files renewalconfig file.

2 Likes
5

Maybe you meant to say that (2) certbot reconfigure --cert-name <cert name> --pre-hook and (1) certbot renew --cert-name <cert name> --pre-hook—if successful—write to /etc/letsencrypt/renewal/<cert name>.conf's pre_hook option?

2 Likes
6

Certbot's docs don't directly address your question. But, some details are in this section: User Guide — Certbot 3.1.0.dev0 documentation

Mostly though I think you will need to experiment. You could place a hook in each location and see the sequence. I use a hook command like 'echo Hook-For-ItemX' when testing similar cases. Fancier logging techniques inside hook scripts are possible of course.

Personally I am wary about relying on behavior that is not doc'd. My concern is the behavior may change without notice since there is nothing constraining it. In this case I don't think this is a big concern.

Sure, you could create your own "Certbot script" to run pre- and post- Certbot. Then setup a cronjob to run it for automated renew. If this is used for every certbot cert you should then disable the existing systemd timer or cronjob.

/var/myCertbotScript.sh

/var/myPreHook.sh
certbot renew 
/var/myPostHook.sh
3 Likes
7

I agree that it's best to not rely on undoumented behavior here.

In any case, I wrote a test to investigate it.

It turns out that hooks set in the global Cerbot config file (cli.ini) override hooks configured for each indivudal certificate renewal while command line argument hooks have the highest priority.

Another thing worth noting is that cli.ini uses hyphens in the option keys (pre-hook) while the <cert name>.conf uses underscores (pre_hook).

I ran the test on Certbot 3.0.1.

1 Like
8

Just curious ... was this test with hook scripts that used the same name?

Because Certbot docs mention something about ignoring repeated hooks.

I would have thought with unique names that hooks from all those places would have run. Although, a command line hook should override what was previously in the cert renewal profile.

There are also hook folders for "global" certs. Are those any benefit to you?

3 Likes
9

was this test with hook scripts that used the same name?

No, only the directory hooks are scripts. All other hooks are unique echo commands. The directory hooks are also echo commands, they're just contained in shell scripts.

I would have thought with unique names that hooks from all those places would have run.

The manual explains that directory hooks will always execute (1) before and (2) regardless of any other hooks. It's not stated explicitly, but I assume that implies the other three ways to set hooks will resolve to a single set of hooks if multiple sets are present, which is why I asked the question.

That would mean a maximum of two sets of hooks should run for any given renew command, which is also what the test shows.

Certbot docs mention something about ignoring repeated hooks.

According to the manual, Certbot won't re-execute a script it's already run as part of executing the directory hooks:

... if a hook specified elsewhere is simply the path to an executable file in the hook directory of the same type (e.g. your pre-hook is the path to an executable in /etc/letsencrypt/renewal-hooks/pre ), the file is not run a second time.

I didn't test this initially, but I've updated the test to confirm that's in fact how it works.

There are also hook folders for "global" certs. Are those any benefit to you?

Those are what I refer to as directory hooks. As you point out, they're all global.

1 Like
10

I've just submitted an issue on Github that asks for the precendence order to be documented: Document the precedence order for renewal hooks · Issue #10078 · certbot/certbot · GitHub

1 Like
11

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