skip to content

In a Rails 8.1 app, what does config.hosts protect against, and how do you configure it in production without blocking health checks?

level: seniorimportance: should knowfreq 35%

answer

  1. DNS rebinding and forged Host headers
  2. empty list means no middleware
  3. leading dot allows one subdomain level
  4. Host and X-Forwarded-Host both checked
  5. host_authorization exclude: for /up

basics

~10 s

config.hosts makes ActionDispatch::HostAuthorization answer 403 to any request whose Host or X-Forwarded-Host is not listed, defeating DNS rebinding and forged Host headers; in production list your domains and exclude the health-check path with config.host_authorization.

solid answer

~40 s

`config.hosts` feeds `ActionDispatch::HostAuthorization`, which compares the `Host` header and the last `X-Forwarded-Host` value with the allowed list and answers **403 Forbidden** on a mismatch. That stops DNS-rebinding attacks and keeps forged hosts out of anything built from `request.host`. In development the list defaults to `.localhost`, `.test`, every IP address and `RAILS_DEVELOPMENT_HOSTS`; in production and test it is empty, and an empty list means the middleware is not even installed. Entries can be exact strings, strings with a leading dot (the domain plus one subdomain label), anchored regexes or `IPAddr` ranges. A load balancer that probes `/up` by IP would be blocked, so add `config.host_authorization = { exclude: ->(request) { request.path == "/up" } }`, as the generated `production.rb` suggests in a comment.

code

ruby · 9 lines
ruby
# config/environments/production.rb
Rails.application.configure do
  config.hosts = [
    ".budget.example"   # the apex plus one label, e.g. app.budget.example
  ]
  config.host_authorization = {
    exclude: ->(request) { request.path == "/up" }
  }
end

go deeper

for a junior

Recall that config.hosts lists the domains the app answers to, and that a blocked host gets 403 with a hint page in development.

for a middle

Explain the per-environment defaults, why an empty list installs no middleware, and how strings, leading dots, regexes and IPAddr entries match.

for a senior

Roll it out in production behind a proxy: list the real public names, check what Host and X-Forwarded-Host the proxy sends, and exclude the health-check path instead of allowing every IP.

for a principal

Treat the allowed-host list as part of the environment contract, owned with DNS and proxy configuration, so new hostnames are added deliberately rather than by widening patterns.

## What the protection is for Every HTTP request names the host it wants in the `Host` header, and proxies may add `X-Forwarded-Host`. Rails uses the result, `request.host`, when it builds absolute URLs, redirects and anything else keyed by host. Two attacks exploit an app that accepts any host: - **DNS rebinding**: a malicious page makes a victim's browser resolve the attacker's name to the app's address, so the browser talks to the app under a foreign `Host`. - **Forged Host headers**: a request with `Host: evil.example` makes the app generate links pointing at the attacker. `ActionDispatch::HostAuthorization` refuses both by allowing only the hosts you list. ## Defaults per environment | Environment | `config.hosts` default | Middleware installed? | |---|---|---| | development | `.localhost`, `.test`, all IPv4 and IPv6 addresses, plus `RAILS_DEVELOPMENT_HOSTS` | yes | | test | `[]` | no | | production | `[]` | no | The last row is the trap: a production app is **unprotected until you set the list**. The generated `production.rb` contains the setting commented out with the hint "Enable DNS rebinding protection and other `Host` header attacks." Clearing the list (`config.hosts.clear`) is how people switch the check off in development. ## How entries match The middleware turns each entry into a matcher: 1. A plain string like `"budget.example"` matches that host exactly, case-insensitively, with any port. 2. A string with a **leading dot**, `".budget.example"`, matches the apex and **one** extra label: `budget.example` and `app.budget.example`, but not `a.b.budget.example`. 3. A **regex** is anchored for you, with an optional port: `/.*\.budget\.example/` matches any depth of subdomain but **not** the bare apex. 4. An **`IPAddr`** range matches IP hosts, such as `IPAddr.new("10.0.0.0/8")`. For every request it checks the `Host` header and, if present, the **last** `X-Forwarded-Host` value. Either one failing blocks the request. ## What a blocked request sees The default response app logs `Blocked hosts: …` at error level and returns **403** with an empty body. With detailed exceptions on, as in development, the body is a page telling you to add `config.hosts << "that-host"`. You can pass your own Rack app as `config.host_authorization = { response_app: ... }`. ## Health checks and other exceptions Load balancers and orchestrators often probe the container by IP, so `Host` is an address your list does not contain, and the probe gets 403. The fix is an exclusion, not a wider list: ```ruby config.host_authorization = { exclude: ->(request) { request.path == "/up" } } ``` Excluded requests skip the check entirely. Adding `IPAddr.new("0.0.0.0/0")` to production would also let the probe through, but it would admit every IP-addressed request, which is exactly what DNS rebinding needs. ## Tests and other environments Integration tests send `Host: www.example.com` by default. That is harmless while `config.hosts` is set only in `production.rb`, but if you move the list into `config/application.rb` every integration test starts receiving 403. Keep the list in the environment files, or add the test host to the test environment's list. In development, a team member opening the app through a tunnel or a custom local domain sees the blocked-host page; the fix is `RAILS_DEVELOPMENT_HOSTS` or a `config.hosts <<` line in `development.rb`, not clearing the list for everyone. ## Behind a proxy - Make sure the proxy passes the public host through in `Host` or `X-Forwarded-Host`, or list the name it actually sends. - In the default stack host authorization sits ahead of `ActionDispatch::AssumeSSL` and `ActionDispatch::SSL`, so a blocked host never reaches the HTTPS redirect. - Keep staging and preview hostnames in their own environment files rather than in a shared regex that grows over time.

  • Why does a fresh Rails production app accept any Host header?
    `config.hosts` defaults to an empty array outside development, and Rails installs `ActionDispatch::HostAuthorization` only when the list is non-empty. The generated `production.rb` has the setting commented out, so until you list your domains no host check runs at all.
  • A health check from the load balancer gets 403 after you set config.hosts. What do you change?
    The probe hits the container by IP, so its `Host` is not in the list. Add `config.host_authorization = { exclude: ->(request) { request.path == "/up" } }`, which skips the check for that path only. Widening `config.hosts` to all IPs would also work but re-opens the DNS-rebinding hole for every path.

  • config.hosts is enforced in production by default
  • A leading-dot entry matches subdomains at any depth
  • Only the Host header is checked; X-Forwarded-Host is ignored
  • Add 0.0.0.0/0 in production so health checks pass
  • Blocked hosts get redirected to the first allowed host