Enable HSTS in nginx

The fix/etc/nginx/snippets/security-headers.conf

add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;

Start with a short max-age — 300 — and raise it once you’re sure. The reasons are in the safety section, and they are the whole point of this page.

Directives on this page

Strict-Transport-Security

The HSTS response header, set through add_header. Not an nginx directive of its own — nginx has no HSTS setting, which is why it is written as a header.

• acceptsmax-age=<seconds> | includeSubDomains | preload

nginx.org ngx_http_headers_module docs

If you see this

nginx: [emerg] unknown directive "includeSubDomains" in /etc/nginx/nginx.conf:12

The semicolon inside the header value ended the add_header line early, so nginx read what followed as a new directive. The whole value has to be quoted — `add_header Strict-Transport-Security "max-age=63072000; includeSubDomains";`. — nginx/src/core/ngx_conf_file.c

nginx: [emerg] invalid parameter "preload" in /etc/nginx/nginx.conf:12

add_header takes a name, a value and one optional third word, and that word can only be `always`. preload belongs inside the quoted value, not after it. — nginx/src/http/modules/ngx_http_headers_filter_module.c

Why it matters

A redirect from HTTP to HTTPS still leaves one plaintext request on the wire, and that request is the attack. Someone on the path intercepts it, never lets the redirect through, and proxies the session over plaintext. The user sees a working site and no warning.

HSTS closes it by telling the browser: for the next max-age seconds, never use plaintext for this host — rewrite it to HTTPS before sending anything. After the first successful visit, there is no plaintext request left to intercept.

That first visit is still exposed, which is what preload addresses, at a cost.

The three parts

Part	Meaning
max-age=63072000	Remember for two years. The browser refreshes it on each visit.
includeSubDomains	Apply to every subdomain, including ones you forgot.
preload	Ship the rule in browsers, so even the first visit is protected.

includeSubDomains is the sharp edge. It applies to hosts you’re not thinking about — legacy.example.com, the intranet box, the vendor’s CNAME. Any of them that cannot do HTTPS becomes unreachable in every browser that has seen your main domain, and there is no way to fix it from that subdomain’s side.

Only add preload if you mean it permanently

preload is not just a token. It requests inclusion in a list compiled into browsers, which requires includeSubDomains, a max-age of at least one year, and submission at hstspreload.org.

Removal is the problem. Getting off the list requires a request, and then waiting for browsers to ship a release with the updated list — realistically months, during which every user with an older browser build still enforces it. There is no fast rollback and no way to hurry it.

For a site you control end to end and intend to keep on HTTPS forever, that’s fine. For anything with subdomains you don’t fully control, it is a decision you cannot walk back at the speed you’ll want to.

Verify it worked

Confirm the header is sent:

curl -sI https://your.site/ | grep -i strict-transport-security

Check a subdomain if you used includeSubDomains — this is the check that matters, because it tells you what you just committed to:

for h in your.site www.your.site legacy.your.site; do
  printf '%-28s %s\n' "$h" "$(curl -sI --max-time 5 "https://$h/" 2>/dev/null | grep -ci 'strict-transport' >/dev/null && echo 'HTTPS ok' || echo 'NO HTTPS — will break')"
done

Confirm the browser is enforcing it, not just receiving it — in Chrome, visit chrome://net-internals/#hsts and query your domain. That shows the actual stored policy, which is the thing that will strand you if it’s wrong.

Note HSTS is ignored on plaintext responses, so setting it in an HTTP server block does nothing. It only counts on HTTPS.

Before you apply this

This is the one control on this cluster you cannot simply undo.

Setting max-age=63072000 means a browser that saw it once will refuse plaintext for that host for two years. Setting it back to max-age=0 only helps users who visit again and receive the new header. Anyone who doesn’t return keeps enforcing the old policy for the full duration. You cannot recall it.

Roll it out in stages:

1. max-age=300, no includeSubDomains. Five minutes of commitment. Confirm nothing breaks.
2. Raise to max-age=86400. Watch for a day.
3. Before adding includeSubDomains, enumerate every subdomain and confirm each serves HTTPS with a valid certificate. Include the ones you don’t manage.
4. Raise to max-age=63072000.
5. preload only if you accept a months-long rollback.

The failure mode of skipping step 3: a subdomain that only speaks HTTP becomes unreachable for anyone who has visited your main site, with a browser error and no override. Your users cannot click through it, and you cannot fix it by changing that subdomain — only by waiting out the max-age you chose.

Certificate expiry gets worse under HSTS too. Normally a user can click past a warning; under HSTS they cannot. An expired cert is a hard outage.

Related

• Set security headers correctly — including why this is in a snippet.
• Configure TLS — HSTS makes TLS mandatory, so it has to work.