Caddy guide · Strict-Transport-Security

How to enable HSTS (Strict-Transport-Security) on Caddy

Enable HSTS on Caddy: add Strict-Transport-Security to the site block, keep it off plain HTTP, cover redirects and avoid a second header behind reverse_proxy. Tested.

  • By
  • Updated
  • 4 min read
  • Tested on Caddy 2.9, 2.10 and 2.11
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
Caddy
strict-transport-security
max-age=31536000; includeSubDomains

Present on error pages too

In short4 points
  • 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 redir responses from the HTTPS site carry it.
  • A site block that also serves http:// sends the header in clear text. Restrict it with a protocol https matcher.
  • Behind reverse_proxy, an application that sends HSTS too produces two headers. Remove the application's with header_down -Strict-Transport-Security inside 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:

Caddyfile
example.com {
	root * /var/www/example
	file_server
	header Strict-Transport-Security "max-age=31536000; includeSubDomains"
}
Shell
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy

Caddy 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:

Shell
grep -nE "^[^ \t#].*\{|Strict-Transport-Security|reverse_proxy|import" /etc/caddy/Caddyfile

You 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:

Caddyfile
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:

Caddyfile
(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:

Caddyfile
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
HTTP/2 200
strict-transport-security: max-age=31536000; includeSubDomains
strict-transport-security: max-age=300

Browsers 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:

Caddyfile
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:

Shell
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:

Shell
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:

Caddyfile
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

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

About the author

Portrait of Joshua Martinelle

Security engineer at Tenable

Security engineer at Tenable and web security researcher. He has disclosed more than 60 CVEs since 2020 and builds WebSec0.

Verify the change

Deployed it? Check it.

WebSec0 grades your TLS setup and security headers, including Strict-Transport-Security, in a few seconds. Free, no account.

Scan your site