Caddy guide · Referrer-Policy

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.

  • 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
referrer-policy
strict-origin-when-cross-origin

Present on error pages too

In short3 points
  • 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
}
Shell
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 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:

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

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

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

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

Server hub

Every header on Caddy

Other web servers

Referrer-Policy on other servers

Questions

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.

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 Referrer-Policy, in a few seconds. Free, no account.

Scan your site