add a comment explaining that nginx OCSP stapling is broken without configuring the async resolver

[thestinger]

nginx caches the IP of the OCSP stapling server forever after loading the configuration if it's using the default synchronous DNS resolver provided by libc. The synchronous DNS resolver is only ever used at configuration load time. People need to be setting resolver to the DNS resolver IP address, such as resolver [::1] for localhost or it ends up breaking if they migrate their IP address. This is included in the generated configuration but has no comment explaining it, so people may remove it to use the default and not realize it's broken.

If you configure the async resolver, it respects TTL instead of caching it forever to avoid blocking the event loop on DNS. The configuration generator needs a comment telling people that this is required, instead of it just being there with no explanation of why it's required. Many people are going to think that removing it and using the default DNS resolution is fine, since it appears to work.

See https://trac.nginx.org/nginx/ticket/1305 or one of the other issues there with an explanation from the developers.

Related:

It would also make a lot of sense to add a comment explaining that people should not use Must-Staple unless they use an approach like https://github.com/tomwassenberg/certbot-ocsp-fetcher because nginx doesn't persistently cache the OCSP response and is also willing to replace a valid response with an invalid one resulting in it no longer serving one. Must-Staple is a great way to do a denial of service on yourself unless you use certbot-ocsp-fetcher. At the moment, nothing discourages people from trying to use Must-Staple with that configuration since it appears to support OCSP stapling but the built-in nginx implementation is ONLY intended as a performance optimization that's treated as optional / non-critical so it doesn't use it at start-up until it gets it in the background, has no persistent cache and doesn't try to avoid losing the valid response it already has.

[thestinger]

I reworded this a fair bit to clarify that I think there should be a clear explanation that resolver should be considered mandatory for using the built-in OCSP stapling. If people use an external implementation, they don't need resolver configured unless they need that for some other reason like using dynamic proxy_pass with a variable (or the resolve feature for upstream blocks that's not in open source nginx) which is far more obvious and isn't just silently broken like this.

[HLFH]

And I also recommend https://github.com/tomwassenberg/certbot-ocsp-fetcher which makes OCSP Must-Staple work with nginx.