diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index e8f9e9d7..9440009b 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -101,6 +101,7 @@ Possible options are (click on each option to jump to its documentation): # TLS Options auto_https off|disable_redirects|ignore_loaded_certs|disable_certs + tls_automate_names email default_sni fallback_sni @@ -474,6 +475,35 @@ This means that if you wish to serve your site over HTTP, you should change your ``` +##### `tls_automate_names` +Manages certificates for the given names without serving them. No route is added, so Caddy does not respond for the names; only their certificates are managed. + +Listing a name here is an explicit request, so it takes precedence over the general switch: certificates are still managed for it when [`auto_https`](#auto_https) is set to `off` or `disable_certs`. In that it behaves like the [`tls` directive's `force_automate`](/docs/caddyfile/directives/tls), which forces automation for a site even when other managed certificates apply. + +Use this for a name you need a certificate for but do not serve with Caddy's HTTP server: a wildcard that only covers other sites, a mail server, or a name handled by a [layer 4](https://github.com/mholt/caddy-l4) app. A Caddyfile containing only global options is valid when this option is set. + +A name that also has its own site block keeps that site's certificate settings. May be repeated; the names accumulate. + +(Requires Caddy 2.11.5 or newer.) + +```caddy +{ + tls_automate_names *.example.com +} + +foo.example.com { + respond "Hello, world!" +} +``` + +Without this option, the same thing requires an empty site block, which also makes Caddy respond for every name that block matches, including names you never configured: + +```caddy +*.example.com { +} +``` + + ##### `email` Your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates.