Named-Reference Hooks, Multiple Hooks

[johnnybubonic]

Welcome

• Yes, I'm using a binary release or the library within the two latest releases.
• Yes, I've searched for similar issues on GitHub and didn't find any.

Detailed Description

Currently when using the config file, only a single hook of each type may be defined and it is applied to all certificate definitions/references.

Certbot at least has the option of hook directories, in which multiple hooks could be placed.

The hooks should support named references (just like challenges, accounts, etc.) and they should be a list, not a string scalar.

The following suggestion is backwards compatible by creating a new section, hooksets:

# (...)

hooksets:
  # A named reference, 'one'.
  one:
    deploy:
      - command: '/usr/bin/some_deploy_hook'
        timeout: 2m
      - command: '/usr/bin/some_other_deploy_hook'
        timeout: 1m
  # A hookset named 'two'.
  two:
    pre:
      - command: '/usr/bin/a_pre_hook'
    post:
      - command: '/usr/bin/a_post_hook'

# (...)

certificates:
  cert_foo:
    # ( ... )
    hooksets:
      - one
  cert_bar:
    # ( ... )
    hooksets:
      - one
      - two

Any/all hooks defined in hooks would still be applied globally, but hooksets would only be run if referenced by a certificate object.

This adds missing functionality, allows for far more modular deploys, and retains backwards compatibility.

Effective version of lego

v5.2.2

How do you use lego?

Binary

In which context are you using lego?

Personal and professional use

🌱 Supporting the Maintainers

• Yes, I find this project useful, and I appreciate the work done by the maintainers.
• Yes, I have starred this repository to help others find it.
• Yes, I have sponsored this project to keep the project stable and maintained.

Confirmation

• Yes, I've included all the information above (version, usage, etc.).

[ldez]

The current design is a deliberated choice: #2947

I recommend using the env vars to "route" your hooks.

I don't close the issue because this is a proposal (I don't evaluate it as an enhancement because this is only a raw idea) even if I would prefer to have a detailed use-case instead of a configuration proposal.

Don't hesitate to describe, in detail, why to you need to use multiple different hooks.

[johnnybubonic]

Don't hesitate to describe, in detail, why to you need to use multiple different hooks.

Sure. Some hosts use the same certificate for multiple services, and require a reload for the new certificate.

For example:

NGINX and OpenLDAP, where NGINX runs a self-service portal for users to reset a password (or some web UI for LDAP, etc.), and OpenLDAP serves LDAP via StartTLS or LDAPS.

But NGINX is likely serving other sites too, not just the self-service portal/web UI. These sites are likely using different certificates. You don't want to reload LDAP unnecessarily for a web-use-only certificate.

Some services don't even support a reload, and instead require a restart. That is now service outage for unrelated cert renewals.

And sure, while one COULD use the env vars to conditionally execute operations inside the hooks, this is IMHO kludgy and ungraceful. It either requires hardcoding specific values into the hooks themselves, making them non-globally-usable, or requiring additional external configuration for each hook, and one is now writing whole scripts instead of just being able to define a hook command as, e.g., nginx -s reload or systemctl reload slapd.

It also breaks with the structure of the rest of the sections (aside from the global directives and logging, obviously) in that all the others have/can make use of named references whereas hooks are/can not.

Given that per #2947 , "hooks [are] executed per-certificate", most of the underlying support is already in place for this -- it just needs an additional switch that can be specified multiple times (optional) and YAML-tagged slice on the certificate config.

Merging likewise is simple: if "global" hooks are found and a certificate has a specified "hookset" as well, just append the global hooks to the hookset(s).

(EDIT: I actually just realized OpenLDAP's slapd is one of those services that doesn't have a reload signal, it's one of the ones that actually does require a service restart.)