Opscraft
Nginx & reverse proxies · Lesson 2 of 6 · 3 min read

Serving and routing requests

Server blocks and server_name

Nginx picks a server block in two steps. First by the address and port the connection arrived on (listen). Then, among the servers listening there, by the Host header (or the SNI name for TLS) against server_name:

  1. An exact name: server_name shop.example.com;
  2. The longest wildcard starting with *: *.example.com
  3. The longest wildcard ending with *: shop.*
  4. The first matching regular expression, in file order: ~^(?<tenant>.+)\.example\.com$

If nothing matches, the default server for that port handles the request: the one marked listen 80 default_server;, or else the first one defined. Always define an explicit default that returns 444 (close the connection) or a plain 404, so requests for unknown names or raw IP addresses don't land on a real site by accident.

server {
    listen 80 default_server;
    server_name _;
    return 444;
}

Location matching

Inside the chosen server, Nginx matches the request path (without the query string) against location blocks. The order of the file matters less than people expect:

Modifier Meaning Priority
= /path Exact match Used immediately if it matches
^~ /prefix Prefix; if it is the longest prefix, skip regex checks Next
~ regex / ~* regex Regular expression, case-sensitive / insensitive First match in file order wins
/prefix Plain prefix Longest one is remembered; used only if no regex matches

So the algorithm is: check exact matches; find the longest prefix; if that prefix has ^~, stop; otherwise try regexes in order and use the first match; if none match, use the remembered longest prefix.

Enlarge diagramExact = match?use it nowLongest prefixremember itHas ^~ ?use it, skip regexRegexes in file orderfirst match winsNo regex matcheduse remembered prefix12345
Figure 1. How Nginx picks a location. File order matters only among regular expressions.
Swipe sideways to see all of it, or tap to open it full screen.
location = /healthz      { access_log off; return 200 "ok\n"; }
location ^~ /static/     { root /srv/app; expires 30d; }
location ~* \.(png|jpg)$ { root /srv/img; }
location /api/           { proxy_pass http://api; }
location /               { try_files $uri /index.html; }

A request for /static/logo.png is served by ^~ /static/, not by the image regex, because ^~ stops the regex search. Without ^~ the regex would win.

Static files and try_files

  • root /srv/app; appends the full URI: /static/a.css becomes /srv/app/static/a.css.
  • alias /srv/assets/; replaces the matched part: location /static/ { alias /srv/assets/; } serves /srv/assets/a.css. Mismatched trailing slashes on alias are a well-known path traversal risk (/static../), so keep both with a slash.
  • try_files $uri $uri/ /index.html; tries each path in turn and falls back to the last one. This is how single-page apps (React, Vue) get client-side routes to work.
  • sendfile on; tcp_nopush on; let the kernel copy files straight to the socket.