- Add
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"to the<VirtualHost *:443>, and redirect port 80 to HTTPS withRedirect permanent. - Keep
always: withHeader set, Apache sends no HSTS header on 404 pages and redirects. - Every HTTPS virtual host needs the header, including one that only redirects
example.comtowww.example.com. - For a server-wide line, add the condition
"expr=%{HTTPS} == 'on'"so plain HTTP responses do not carry it. - Behind
mod_proxy_http, an application that sends HSTS too produces two headers. PutHeader unset Strict-Transport-Securitybefore thealwaysline.
The short answer
Redirect port 80 to HTTPS, and add the header to the virtual host that listens on 443:
<VirtualHost *:80>
ServerName example.com
Redirect permanent / https://example.com/
</VirtualHost>
<VirtualHost *:443>
ServerName example.com
DocumentRoot "/var/www/example"
SSLEngine on
SSLCertificateFile /etc/ssl/example.com/fullchain.pem
SSLCertificateKeyFile /etc/ssl/example.com/privkey.pem
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>sudo apachectl configtest && sudo apachectl gracefulalways keeps the header on error pages and redirects. The port 80 host has
no header on purpose: browsers ignore HSTS over plain HTTP. Every snippet below
was run on Apache httpd 2.4.58, 2.4.62 and 2.4.69 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
The Header directive comes from mod_headers. Check that it is loaded, then
list your virtual hosts and any existing Header lines:
apachectl -M | grep headers
apachectl -S
grep -rn "Strict-Transport-Security" /etc/apache2/ /etc/httpd/ 2>/dev/nullIf headers_module is missing, enable it with sudo a2enmod headers on
Debian and Ubuntu, or uncomment its LoadModule line in httpd.conf.
You are looking for three things:
- Every virtual host on 443. Each one needs the header, including hosts that only redirect.
- An existing HSTS line, in another file, in
.htaccess, or set by the application. Two headers cause trouble (step 5). - The port 80 hosts. They should only redirect.
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:
Header always set 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: keep it on error pages and redirects
Apache keeps two tables of response headers. Header set writes to the one
used for successful responses; Header always set writes to the one that is
also sent on errors and redirects. Our test with Header set:
HTTP/1.1 200 OK
Strict-Transport-Security: max-age=31536000; includeSubDomains
HTTP/1.1 404 Not Found
(no Strict-Transport-Security header)
HTTP/1.1 301 Moved Permanently
(no Strict-Transport-Security header)With Header always set, all three responses carried the header. A visitor’s
first HTTPS response can be a 404 from an old link, or a redirect.
Step 3: cover every host and redirect
includeSubDomains only protects visitors whose browser has already seen the
parent domain. A visitor who goes straight to www.example.com learns the
policy from that host, so each HTTPS virtual host needs the header, including
one that only redirects:
<VirtualHost *:80>
ServerName example.com
Redirect permanent / https://example.com/
</VirtualHost>
<VirtualHost *:80>
ServerName www.example.com
Redirect permanent / https://www.example.com/
</VirtualHost>
<VirtualHost *:443>
ServerName example.com
# SSLEngine and certificate lines...
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
Redirect permanent / https://www.example.com/
</VirtualHost>
<VirtualHost *:443>
ServerName www.example.com
# SSLEngine and certificate lines...
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>What our test returned:
| Request | Response |
|---|---|
http://example.com/a |
301 to https://example.com/a, no HSTS |
http://www.example.com/a |
301 to https://www.example.com/a, no HSTS |
https://example.com/a |
301 to https://www.example.com/a, with HSTS |
https://www.example.com/ and a 404 |
With HSTS |
Each port 80 host redirects to HTTPS on the same host first, then the
HTTPS host moves visitors to www. Skipping that step, with http://example.com
going straight to https://www.example.com, means browsers never receive HSTS
for example.com. The HSTS preload list requires this order.
Step 4: one line for all virtual hosts
To set the header once, put it in the server configuration, outside any
VirtualHost, with a condition so that plain HTTP responses do not carry it:
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains" "expr=%{HTTPS} == 'on'"Our test returned the header on the HTTPS host, its 404 included, and no header on the HTTP host.
Do not keep a Header set Strict-Transport-Security line in a virtual host as
well. In our test, a server-wide Header always set combined with a
Header set in the virtual host returned two identical HSTS headers on
successful responses, because each line writes to a different table.
Step 5: one header behind a reverse proxy
Many frameworks send HSTS on their own. With mod_proxy_http and
Header always set, our test returned both:
HTTP/1.1 200 OK
Strict-Transport-Security: max-age=31536000; includeSubDomains
Strict-Transport-Security: max-age=300Apache’s header came first, so browsers and WebSec0 applied it here, but the
response is fragile and confusing. Remove the application’s header from the
default table, then set yours in the always table:
<VirtualHost *:443>
# ...
ProxyPass "/" "http://127.0.0.1:8080/"
Header unset Strict-Transport-Security
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>Our test then returned a single header, on pages and on 404s. The same pair of
lines also handles CGI and mod_proxy_fcgi applications, whose headers Apache
stores in the always table.
When Apache sits behind a load balancer or CDN that terminates TLS, it only
sees plain HTTP. Send HSTS from the component that terminates TLS, or set the
line in Apache without the %{HTTPS} condition. Make sure only one of the two
sends it.
Verify it
Check a page, an error page and the redirects. Use your own host names:
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:
curl -sI https://example.com/ | grep -ci '^strict-transport-security:'Repeat for each host, then scan the site 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:
Header always set Strict-Transport-Security "max-age=0"Our test returned max-age=0 on pages and 404s. 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 |
|---|---|---|
Invalid command 'Header' |
mod_headers is not loaded |
a2enmod headers, or uncomment its LoadModule line. |
| Header missing on 404 pages or redirects | Header set without always |
Write Header always set. |
Header missing on www or another subdomain |
Only the main virtual host sends it | Add it to every HTTPS virtual host, including redirects. |
Two Strict-Transport-Security headers |
A proxied application sends one too, or a Header set and a Header always set coexist |
Header unset before Header always set, and keep one line per scope. |
Header on http:// responses |
The line is server-wide or in the port 80 host | Add "expr=%{HTTPS} == 'on'", or move it to the 443 host. Harmless, but browsers ignore it. |
| 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 | apachectl configtest && apachectl graceful, then purge the CDN. |
Server hub
Every header on Apache
Other web servers
Strict-Transport-Security on other servers
Caddy
Guide ↗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.
Nginx
Guide ↗Enable HSTS on Nginx: send Strict-Transport-Security from the HTTPS server only, with always, on every location and redirect, without duplicates. Tested configs.
Traefik
Guide ↗Enable HSTS on Traefik with the headers middleware: stsSeconds and stsIncludeSubdomains, the HTTPS redirect, middleware order, TLS offloading and a working rollback.
Questions
Frequently asked questions
Where do I put the HSTS header in Apache?
In the <VirtualHost *:443> block of each site, with Header always set. Do not put it in the port 80 virtual host: browsers ignore HSTS over plain HTTP, and that host should only redirect.
Why is HSTS missing on my 404 pages or redirects?
Header set writes to the table Apache uses for successful responses only. Error pages and redirects that Apache generates use the always table. Write Header always set.
Can I set HSTS once for all virtual hosts?
Yes, in the server configuration outside any VirtualHost, with the condition "expr=%{HTTPS} == 'on'". Do not combine it with a Header set line for the same header in a virtual host: our test returned two headers on successful responses.
My response has two Strict-Transport-Security headers. Which one counts?
Browsers apply the first one, and WebSec0 grades the first one too. Behind mod_proxy_http, Apache's always header came first in our test, and the application's after it. Add Header unset Strict-Transport-Security before the Header always set line to send one.
How do I turn HSTS off on Apache?
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 browsers already stored.
Is mod_headers needed for HSTS?
Yes. The Header directive comes from mod_headers. Check it with apachectl -M | grep headers, and enable it with a2enmod headers on Debian and Ubuntu.
References
Sources
- Apache Module mod_headersApache HTTP Server Project
- Apache Module mod_alias: RedirectApache HTTP Server Project
- Expressions in Apache HTTP ServerApache HTTP Server Project
- Strict-Transport-Security headerMDN Web Docs
