Documentation of MDNotifyCmd and MDMessageCmd: env vars, order of events, repeat call back-off

[whereisaaron]

Loving mod_md but found some documentation gaps that would be great to clarify.

(1) This commit suggests that:

MDNotifyCmd and MDMessageCmd now get the environment variable MD_STORE containing the path to the storage directory.

That's fantastic but the documentation doesn't mention it:

• https://github.com/icing/mod_md#mdnotifycmd
• https://github.com/icing/mod_md#mdmessagecmd

(2) The MDNotifyCmd and MDMessageCmd doesn't say when MDNotifyCmd is called? It says "for each MD that has been processed successfully". Is it before/after MDMessageCmd renewed or after restart as the certificate is installed?

(3) Both MDNotifyCmd and MDMessageCmd <reason> are called repeatedly until they return zero, but the documentation doesn't say what spacing or back-off. I think I read elsewhere that repeat call back off with doubling time up to 24 hours? Is that correct?

[whereisaaron]

Looks like (1) has been reverted, and env vars are no longer passed with MDNotifyCmd and MDMessageCmd.

MDNotifyCmd is now called for each domain that has been successfully renewed. Not for all Managed Domains after all have been processed. This gives notifications earlier.

What is a "Manage Domain"? Is it each MDDomain certificate with one or domains. Or it is each domain within each MDDomain certificate?

[icing]

MDNotifyCmd was the first, but it was not very flexible. It is only called when a new certificate has been obtained.

A managed domain is a group of DNS names for which a certificate - covering all DNS names in that MD - shall be obtained.

[whereisaaron]

@icing do repeat calls to MDMessageCmd <reason> that return a non-zero exit code have the same back-off timing as other things?

(3) Both MDNotifyCmd and MDMessageCmd are called repeatedly until they return zero, but the documentation doesn't say what spacing or back-off. I think I read elsewhere that repeat call back off with doubling time up to 24 hours? Is that correct?

[icing]

There is a limitation in the module how often MDMessageCmd or NotifyCmd is invoked for a pariticular reason. That is counted per Managed Domain. The table is like this:

    { "renewing", apr_time_from_sec(MD_SECS_PER_HOUR) }, /* once per hour */
    { "renewed", apr_time_from_sec(MD_SECS_PER_DAY) }, /* once per day */
    { "installed", apr_time_from_sec(MD_SECS_PER_DAY) }, /* once per day */
    { "expiring", apr_time_from_sec(MD_SECS_PER_DAY) },     /* once per day */
    { "errored", apr_time_from_sec(MD_SECS_PER_HOUR) },     /* once per hour */
    { "ocsp-renewed", apr_time_from_sec(MD_SECS_PER_DAY) }, /* once per day */
    { "ocsp-errored", apr_time_from_sec(MD_SECS_PER_HOUR) }, /* once per hour */

This is independent of the back-off timing for errors. These grow ever large with subsequent errors encountered, up to a max of once per day. Again, per Managed Domain.

[whereisaaron]

Thank you for explaining. So MDMessageCmd or NotifyCmd non-zero return codes trigger retry (per Managed Domain) once an hour or day as appropriate to the reason, other errors retry (per Managed Domain) starting with MDRetryDelay delay, then doubling the delay each time until it is capped at once per day.

I went to suggest a README documentation patch, only to find you did essentially cover this already. Not sure how I missed that, sorry. I apologise for asking a RTFM question 😭

https://github.com/icing/mod_md/blob/master/README.md#mdmessagecmd

The calls are rate limited. The successful renewal will only be called once, errors will triggers this only once per hour. The warning on an expiring certificate will run only once per day.