# 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.

Author: Joshua Martinelle, Security engineer at Tenable (https://www.websec0.com/guides/authors/joshua-martinelle/)
Canonical: https://www.websec0.com/guides/strict-transport-security/caddy/
Updated: 2026-10-20
Tested on: Caddy 2.9, 2.10 and 2.11

## In short

- 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"
}
```

```sh
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](/guides/strict-transport-security/)
before you ship it, and check that every subdomain works over HTTPS.

## Before you start

Find every site block and any existing HSTS line:

```sh
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:

```sh
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`:

```sh
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. |

## 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.

## Sources

- [Caddyfile directive: header](https://caddyserver.com/docs/caddyfile/directives/header), Caddy
- [Automatic HTTPS](https://caddyserver.com/docs/automatic-https), Caddy
- [Caddyfile directive: redir](https://caddyserver.com/docs/caddyfile/directives/redir), Caddy
- [Request matchers: protocol](https://caddyserver.com/docs/caddyfile/matchers), Caddy
- [RFC 6797: HTTP Strict Transport Security (HSTS)](https://www.rfc-editor.org/rfc/rfc6797.html), IETF
- [Strict-Transport-Security header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security), MDN Web Docs
