# How to set Referrer-Policy on Caddy

> Set Referrer-Policy on Caddy with the header directive, use no-referrer on sensitive paths with route, and stop a proxied app's weaker value from winning. Tested configs.

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

## In short

- Add `header Referrer-Policy "strict-origin-when-cross-origin"` to the site block. Caddy sends it on its own 404 pages and redirects without any extra flag.
- Browsers apply the last Referrer-Policy they recognise. Behind `reverse_proxy`, the application's header comes after Caddy's and wins. Add `header_down -Referrer-Policy` inside the proxy block.
- For `no-referrer` on sensitive paths, put `header /reset/* Referrer-Policy "no-referrer"` in a `route` block. Outside `route`, the site-wide line runs last and overwrites it.

## The short answer

Add the header to the site block in your Caddyfile:

```caddyfile
example.com {
	header Referrer-Policy "strict-origin-when-cross-origin"
	root * /var/www/example
	file_server
}
```

```sh
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy
```

Every snippet below was run on Caddy 2.9, 2.10 and 2.11 and checked with
`curl`, on a page, a 404, a redirect, a proxied application and an
application that was down.

`strict-origin-when-cross-origin` keeps full URLs on your own origin and sends
only the origin to other sites. The
[Referrer-Policy overview](/guides/referrer-policy/) compares the eight values
and explains when to choose a stricter one.

## Before you start

Find every site block, `header` directive and proxy in your Caddyfile:

```sh
grep -nE "^[^ \t#].*\{|header|Referrer-Policy|reverse_proxy|php_fastcgi|import|route" /etc/caddy/Caddyfile
```

Then check your HTML templates for a `<meta name="referrer">` tag. It
overrides the header in the browser:

```sh
curl -s https://example.com/ | grep -i 'name="referrer"'
```

You are looking for:

- **Every site that serves pages.** Caddy adds no Referrer-Policy on its own.
- **Proxied applications** that may send a Referrer-Policy themselves. Two
  headers cause trouble (step 3).
- **Paths whose URLs carry secrets,** such as password reset or invitation
  links. They deserve a stricter policy (step 4).

## Step 1: choose the value

| Your site | Caddyfile line |
| --- | --- |
| Most sites | `header Referrer-Policy "strict-origin-when-cross-origin"` |
| Never reveal where users come from | `header Referrer-Policy "no-referrer"` |
| Keep full URLs on your origin, nothing elsewhere | `header Referrer-Policy "same-origin"` |

Do not use `unsafe-url` or `no-referrer-when-downgrade`: both send full URLs
to other sites, and WebSec0 grades them as a warning. Keep the value in plain
double quotes: extra quotes inside it reach the browser, which treats the
value as invalid and falls back to its default.

## Step 2: which responses get the header

A plain `header` line acts on every response of the site. In our test:

| Response | Referrer-Policy |
| --- | --- |
| A page from `file_server` | Present |
| A 404 from `file_server` | Present |
| A `301` from a `redir` in the site | Present |
| A file under `/assets/` with its own `header /assets/* Cache-Control …` line | Present |
| A 502 when the proxied application was down | Present |
| Caddy's automatic HTTP to HTTPS redirect | Absent |

Unlike Nginx and Apache, there is no `always` flag to remember. The automatic
redirect has no page to protect. To send the same headers from several sites,
put them in a snippet that each site imports; the
[security headers hub for Caddy](/guides/security-headers/caddy/) shows one
snippet with all six security headers.

## Step 3: one header behind reverse_proxy

Many frameworks send a Referrer-Policy of their own. A `header` line runs
before the proxy, and Caddy keeps the application's header after its own. Our
test, with an application sending `unsafe-url`:

```http
HTTP/2 200
referrer-policy: strict-origin-when-cross-origin
referrer-policy: unsafe-url
```

Browsers apply the last value they recognise, so users get the application's
`unsafe-url`, and WebSec0 grades the same value as a warning. Drop the
application's header as the response comes back from the proxy:

```caddyfile
example.com {
	header Referrer-Policy "strict-origin-when-cross-origin"
	reverse_proxy 127.0.0.1:8080 {
		header_down -Referrer-Policy
	}
}
```

Our test then returned a single `strict-origin-when-cross-origin`, on the
application's pages and 404s, and on Caddy's 502 when the application was
down. Do not use the `>` prefix instead: it replaces the application's value,
but Caddy's own error pages then go without the header, as the
[security headers hub for Caddy](/guides/security-headers/caddy/) shows.

If the application must vary the policy per page, let it own the header and
remove the Caddy line instead.

## Step 4: a stricter policy on sensitive paths

Pages whose URLs carry a token, such as `/reset/?token=…`, should send no
referrer at all. A `header /reset/* …` line next to the site-wide one does
not work. Caddy sorts `header` directives by path matcher, the most specific
first and the one without a matcher last, so the site-wide line runs after
the per-path one and overwrites it. In our test, `/reset/` got
`strict-origin-when-cross-origin`.

Put the per-path line in a `route` block. Inside `route`, directives run in
the order written, and the block as a whole runs after the site-wide
`header`:

```caddyfile
example.com {
	header Referrer-Policy "strict-origin-when-cross-origin"
	route {
		header /reset/* Referrer-Policy "no-referrer"
	}
	root * /var/www/example
	file_server
}
```

What our test returned:

| URL | Referrer-Policy |
| --- | --- |
| `/` | `strict-origin-when-cross-origin` |
| `/reset/` | `no-referrer` |
| `/reset/does-not-exist` (404) | `no-referrer` |

Keep the site-wide line outside `route`: `route` runs after `redir` in
Caddy's directive order, so a redirect would go without the header.

## Verify it

Check a page, an error page and a sensitive path. Use your own host name:

```sh
curl -sI https://example.com/ | grep -i "^referrer-policy"
curl -sI https://example.com/does-not-exist | grep -i "^referrer-policy"
curl -sI https://example.com/reset/ | grep -i "^referrer-policy"
```

Each should print the policy you chose for that path. Count the headers to
catch duplicates. The result should be `1`:

```sh
curl -sI https://example.com/ | grep -ci '^referrer-policy:'
```

Then scan the site with WebSec0. The headers report shows the value it
received and whether it passes.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| No Referrer-Policy at all | Caddy adds none by default | Add the `header` line to every site, or import a snippet. |
| Two `Referrer-Policy` headers, the application's last | The proxied application sends one too | Add `header_down -Referrer-Policy` inside `reverse_proxy`. |
| A stricter path policy has no effect | The per-path line is outside `route`, so the site-wide line overwrites it | Put it in a `route` block. |
| Header missing on 502 pages | `>` in front of the field | Drop the `>` and use `header_down`. |
| WebSec0 shows a warning | The last value is `unsafe-url` or `no-referrer-when-downgrade` | Use `strict-origin-when-cross-origin` and keep one header. |
| WebSec0 fails a header that is present | No recognised value: a typo or extra quotes | Fix the value; browsers ignore it too. |
| Browser sends more than the header says | A `<meta name="referrer">` in the page overrides it | Remove the tag or make it match. |
| Changes do not show up | Reload skipped, or a CDN cached old headers | `caddy validate` and reload, then purge the CDN. |

## Frequently asked questions

### Where do I put Referrer-Policy in a Caddyfile?

In each site block, or in a snippet that every site imports. Caddy applies it to every response of the site, including its own 404 pages and redirects.

### What is the Caddyfile line for Referrer-Policy?

`header Referrer-Policy "strict-origin-when-cross-origin"`. Check the configuration with `caddy validate` and reload with `systemctl reload caddy`.

### My response has two Referrer-Policy headers behind reverse_proxy. Which one applies?

The last one browsers recognise, which was the application's in our test: Caddy sets its header before the proxy and keeps the application's after it. Add `header_down -Referrer-Policy` inside `reverse_proxy` to send one.

### Why is my per-path Referrer-Policy ignored in Caddy?

Caddy sorts `header` directives by path, most specific first and the one without a path last, so the site-wide line overwrites the per-path one. Put the per-path line in a `route` block, where directives run in the order written.

### Does Caddy send Referrer-Policy by default?

No. Caddy sends no security headers of its own. Browsers then apply their default, `strict-origin-when-cross-origin` in current versions, but WebSec0 fails a missing header.

## Sources

- [Caddyfile directive: header](https://caddyserver.com/docs/caddyfile/directives/header), Caddy
- [Caddyfile directive: reverse_proxy (header_down)](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#headers), Caddy
- [Caddyfile directive: route](https://caddyserver.com/docs/caddyfile/directives/route), Caddy
- [Referrer Policy](https://w3c.github.io/webappsec-referrer-policy/), W3C
- [Referrer-Policy header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy), MDN Web Docs
