- Caddy redirects HTTP to HTTPS on its own but sends no HSTS header. Add
header Strict-Transport-Security "max-age=31536000; includeSubDomains"to the site block. - The automatic HTTP redirect carries no HSTS header, as it should. Pages, 404s and
redirresponses from the HTTPS site carry it. - A site block that also serves
http://sends the header in clear text. Restrict it with aprotocol httpsmatcher. - Behind
reverse_proxy, an application that sends HSTS too produces two headers. Remove the application's withheader_down -Strict-Transport-Securityinside the proxy block.
The short answer
Add the header to the site block. Caddy already redirects HTTP to HTTPS for site addresses with a host name:
example.com {
root * /var/www/example
file_server
header Strict-Transport-Security "max-age=31536000; includeSubDomains"
}caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddyCaddy sends no HSTS header on its own: automatic HTTPS covers the redirect and
the certificate, not this header. Every snippet below was run on Caddy 2.9,
2.10 and 2.11 and checked with curl, on a page, a 404 and a redirect.
max-age=31536000 (one year) with includeSubDomains is what WebSec0 grades as
a pass, but it is a final value, not a starting point. Read
how to roll out HSTS without locking users out
before you ship it, and check that every subdomain works over HTTPS.
Before you start
Find every site block and any existing HSTS line:
grep -nE "^[^ \t#].*\{|Strict-Transport-Security|reverse_proxy|import" /etc/caddy/CaddyfileYou are looking for three things:
- Every HTTPS site. Each one needs the header, including sites that only redirect.
- Site addresses that start with
http://. They serve plain HTTP and need a matcher (step 3). - Proxied applications that may send HSTS themselves (step 4).
Step 1: start with a short max-age
A long max-age stays in visitors’ browsers even if you remove the line. Start
at five minutes:
header Strict-Transport-Security "max-age=300; includeSubDomains"Reload, browse your sites and subdomains, and watch your error rates. Then
raise the value in steps, waiting a full max-age each time: 604800 (one
week), 2592000 (30 days), then 31536000 (one year) or 63072000 (two
years).
If a subdomain cannot serve HTTPS yet, leave includeSubDomains out until it
can. WebSec0 grades a header without it as a warning, but a subdomain that
stops loading is worse.
Step 2: cover every host and redirect
Each HTTPS site needs the header, because includeSubDomains only reaches
browsers that have visited the parent domain. That includes a site that only
redirects to www:
(hsts) {
header Strict-Transport-Security "max-age=31536000; includeSubDomains"
}
example.com {
import hsts
redir https://www.example.com{uri} permanent
}
www.example.com {
import hsts
root * /var/www/example
file_server
}What our test returned for this configuration:
| Request | Response |
|---|---|
http://example.com/a |
308 to https://example.com/a, no HSTS |
https://example.com/some/path |
301 to https://www.example.com/some/path, with HSTS |
http://www.example.com/a |
308 to https://www.example.com/a, no HSTS |
https://www.example.com/ and a 404 |
With HSTS |
Caddy’s automatic redirect goes to HTTPS on the same host first, then the
redir moves visitors to www. This is the order the HSTS preload list
requires, and Caddy follows it without extra configuration. The snippet must
come before the site blocks that import it.
Step 3: keep it off plain HTTP
A site block whose address starts with http:// serves plain HTTP. If it also
lists the https:// address, a plain header line is sent on both. Our test
returned the header on the HTTP response too. Restrict it with a matcher:
http://example.com, https://example.com {
root * /var/www/example
file_server
@https protocol https
header @https Strict-Transport-Security "max-age=31536000; includeSubDomains"
}With the matcher, our test returned no header over HTTP, and the header on HTTPS pages and 404s. Browsers ignore HSTS over HTTP anyway, so this is about a clean response more than safety. Serving the site over HTTP at all is the real question: letting Caddy redirect is usually better.
When Caddy sits behind a load balancer or CDN that terminates TLS, it only sees plain HTTP. Send HSTS from the component that terminates TLS, or add the header in Caddy without the matcher. Make sure only one of the two sends it.
Step 4: one header behind reverse_proxy
Many frameworks send HSTS on their own. A plain header line runs before the
proxy, and Caddy keeps both. Our test, with an application sending
max-age=300:
HTTP/2 200
strict-transport-security: max-age=31536000; includeSubDomains
strict-transport-security: max-age=300Browsers and WebSec0 read the first header, so Caddy’s won here, but the response is confusing and fragile. Remove the application’s header as the response comes back from the proxy:
example.com {
header Strict-Transport-Security "max-age=31536000; includeSubDomains"
reverse_proxy 127.0.0.1:8080 {
header_down -Strict-Transport-Security
}
}Our test then returned a single header, Caddy’s, on the application’s pages and 404s, and on Caddy’s 502 when the application was down.
Prefixing the field with >, as in header >Strict-Transport-Security …,
also replaced the application’s value, but it defers the header until the
application writes the response. When the application was down, Caddy’s 502
had no HSTS header. Do not use the ? prefix either: it
only sets the header when none exists. In our test,
header ?Strict-Transport-Security in front of the proxy returned only the
application’s max-age=300.
Verify it
Check a page, an error page and the redirects. Use your own host names:
curl -sI https://example.com/ | grep -i strict-transport-security
curl -sI https://example.com/does-not-exist | grep -i strict-transport-security
curl -sI http://example.com/ | grep -iE "^location|strict-transport-security"The first two should print the header. The third should print a location:
pointing to https://example.com/ and no HSTS header.
Count the headers to catch duplicates. The result should be 1:
curl -sI https://example.com/ | grep -ci '^strict-transport-security:'Repeat for each site, then scan it with WebSec0. The headers report shows the value it received and whether it passes.
Roll back
If a subdomain breaks after you enabled includeSubDomains, set the value to
max-age=0, reload, and keep HTTPS running:
header Strict-Transport-Security "max-age=0"Our test returned max-age=0. Browsers forget the policy the next time they
receive this header. Deleting the line instead leaves the old policy in place
until it expires.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| No HSTS header at all | Caddy does not add one by default | Add the header line to the site block. |
Header missing on www or another site |
Only one site block has the line | Import a snippet in every HTTPS site block. |
Header on http:// responses |
The block also serves http:// |
Add @https protocol https and use it on the header line. |
Two Strict-Transport-Security headers |
The proxied application sends one too | Add header_down -Strict-Transport-Security inside reverse_proxy. |
The application’s short max-age is sent |
?Strict-Transport-Security in front of the proxy |
Drop the ? and add header_down. |
| WebSec0 shows a warning | max-age below 31536000 or no includeSubDomains |
Finish the rollout: one year with includeSubDomains. |
| Changes do not show up | Reload skipped, or a CDN cached old headers | caddy validate and reload, then purge the CDN. |
Server hub
Every header on Caddy
Other web servers
Strict-Transport-Security on other servers
Apache
Guide ↗Enable HSTS on Apache: send Strict-Transport-Security from the HTTPS virtual host only, with always, on every redirect and error page, without duplicates. Tested configs.
Nginx
Guide ↗Enable HSTS on Nginx: send Strict-Transport-Security from the HTTPS server only, with always, on every location and redirect, without duplicates. Tested configs.
Traefik
Guide ↗Enable HSTS on Traefik with the headers middleware: stsSeconds and stsIncludeSubdomains, the HTTPS redirect, middleware order, TLS offloading and a working rollback.
Questions
Frequently asked questions
Does Caddy send HSTS by default?
No. Caddy redirects HTTP to HTTPS automatically, but in our tests it sent no Strict-Transport-Security header until one was added with the header directive.
Where do I put HSTS in the Caddyfile?
Inside the site block, as header Strict-Transport-Security "max-age=31536000; includeSubDomains". For several sites, put it in a snippet and import it in each block.
Is HSTS sent on Caddy's HTTP to HTTPS redirect?
No. In our tests the automatic redirect, a 308 to the same host over HTTPS, carried no HSTS header. Browsers ignore HSTS over plain HTTP anyway.
My response has two Strict-Transport-Security headers. Which one counts?
Browsers apply the first one, and WebSec0 grades the first one too. Behind reverse_proxy, Caddy's came first in our test. Add header_down -Strict-Transport-Security inside reverse_proxy so Caddy drops the application's header and sends one.
How do I turn HSTS off on Caddy?
Change the value to max-age=0, reload, and keep serving HTTPS. Browsers drop the policy the next time they receive the header. Removing the line does not clear the policy they already stored.
References
Sources
- Automatic HTTPSCaddy
- Strict-Transport-Security headerMDN Web Docs
