- 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. Addheader_down -Referrer-Policyinside the proxy block. - For
no-referreron sensitive paths, putheader /reset/* Referrer-Policy "no-referrer"in arouteblock. Outsideroute, the site-wide line runs last and overwrites it.
The short answer
Add the header to the site block in your Caddyfile:
example.com {
header Referrer-Policy "strict-origin-when-cross-origin"
root * /var/www/example
file_server
}caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddyEvery 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:
grep -nE "^[^ \t#].*\{|header|Referrer-Policy|reverse_proxy|php_fastcgi|import|route" /etc/caddy/CaddyfileThen check your HTML templates for a <meta name="referrer"> tag. It
overrides the header in the browser:
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/2 200
referrer-policy: strict-origin-when-cross-origin
referrer-policy: unsafe-urlBrowsers 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:
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:
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:
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:
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
Apache
Guide ↗Set Referrer-Policy on Apache with Header always set, keep it on errors and redirects, use no-referrer on sensitive paths and stop a proxied app's value winning. Tested.
Nginx
Guide ↗Set Referrer-Policy on Nginx with add_header and always, keep it on every location, use a stricter policy on sensitive paths and avoid duplicate headers. Tested configs.
Traefik
Guide ↗Set Referrer-Policy on Traefik with the referrerPolicy option of the headers middleware, in labels or a file, and use no-referrer on sensitive paths. Tested configs.
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
- Referrer-Policy headerMDN Web Docs
