From 286e7b7f2622459bd4fed81be6452f3b84cde351 Mon Sep 17 00:00:00 2001 From: Islam Elsayed Date: Tue, 15 Sep 2026 14:08:00 +0300 Subject: [PATCH 1/3] Document the tls_automate_names global option Added in caddyserver/caddy#8015: names certificates should be managed for without adding a route for them, replacing the empty-site-block workaround. --- src/docs/markdown/caddyfile/options.md | 28 ++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index e8f9e9d7..ec5e199e 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,33 @@ 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. The names get the same certificate management [Automatic HTTPS](/docs/automatic-https) gives the names in your site blocks, but no route is added, so Caddy does not respond for them. + +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.12 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. From 30a0dc077d714cc72d322197a47ba68d68379a2d Mon Sep 17 00:00:00 2001 From: Islam Elsayed Date: Sun, 20 Sep 2026 00:02:52 +0300 Subject: [PATCH 2/3] Target 2.11.5 for tls_automate_names The version note was a guess from v2.11.4 being the latest release. @francislavoie and @steadytao settled on 2.11.5 rather than 2.12 on caddyserver/caddy#8015, since the option is a low-impact addition and not an API change. --- src/docs/markdown/caddyfile/options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index ec5e199e..6365c589 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -482,7 +482,7 @@ Use this for a name you need a certificate for but do not serve with Caddy's HTT A name that also has its own site block keeps that site's certificate settings. May be repeated; the names accumulate. -(Requires Caddy 2.12 or newer.) +(Requires Caddy 2.11.5 or newer.) ```caddy { From 712f690eee5a0fe914d73151fa7f40093d66c661 Mon Sep 17 00:00:00 2001 From: Islam Elsayed Date: Sun, 20 Sep 2026 13:02:06 +0300 Subject: [PATCH 3/3] Say that tls_automate_names overrides auto_https @steadytao's review: describing the option only as the management Automatic HTTPS provides hid the precedence. Listing a name is an explicit request, so it is still managed when auto_https is off or disable_certs, the same way the tls directive's force_automate forces automation for a site. Verified by adapting both: `auto_https off` and `auto_https disable_certs` each leave the name in the automate loader. caddyserver/caddy#8015 pins the first in tls_automate_names_auto_https_off.caddyfiletest. --- src/docs/markdown/caddyfile/options.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 6365c589..9440009b 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -476,7 +476,9 @@ 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. The names get the same certificate management [Automatic HTTPS](/docs/automatic-https) gives the names in your site blocks, but no route is added, so Caddy does not respond for them. +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.