Nginx، Reverse Proxy و لایهٔ وبNginx, Reverse Proxy & the Web Tier

Your Spring Boot service comes up on port 8080 and works. But no real user ever connects to that port directly. Between the user's browser and your JVM process sits an entire engineering layer: something that unwraps TLS, fixes up headers, serves static files without waking the application, spreads traffic across instances, slows attackers down, and — when the app hiccups — returns something sane instead of an ugly stack trace.

We call this the web tier, and its most common tool is nginx. This topic shows up in almost every backend interview, because it is exactly where "programmer" ends and "engineer" begins. Someone who only writes code treats nginx as a config file copied from a forum. Someone who keeps systems alive knows why they got a 502, why the client IP in the logs is wrong, and why a 10 MB upload comes back as 413.

This chapter takes you from zero to the point where you can read a production config line by line, debug it, and defend its architectural choices.

1. What sits in front of the service, and why

The seven roles the web tier plays

1. Reverse proxy. "Reverse" is the opposite of an ordinary proxy: a forward proxy represents the client (your browser hands it a request to fetch on your behalf), while a reverse proxy represents the server — the client believes it is talking to the real service, but it is talking to an intermediary that hands the work to internal services. The payoff is that the addresses, count and topology of those internal services stay invisible from outside.

2. Load balancer. With three instances running, something must decide where each request goes and remove a dead instance from rotation. Because this happens at layer 7 (HTTP), the decision can depend on path, header or cookie — not just IP and port.

3. TLS terminator. Encryption is unwrapped here: the certificate and private key live on nginx and the app receives plain traffic. Certificate renewal, cipher selection and turning on HTTP/3 happen once, in one place, instead of in ten services.

4. Static file server. JS, CSS, images and fonts carry no logic; nginx ships them at a tiny fraction of the CPU cost of a Java thread.

5. Cache. Repeated, cacheable responses are returned without touching the app. Even a one-second cache (micro-caching) can cut load on a hot endpoint several fold.

6. Rate limiter and first shield. Floods, giant bodies and slow connections are cut here, before they consume a thread or a database connection.

7. WAF entry point. A Web Application Firewall blocks known attack shapes (SQL injection, path traversal, scanners); since all traffic passes through this layer, it is the natural place to install it.

These seven roles do not have to live on one binary: in a real deployment a CDN and anti-DDoS sit at the internet edge, nginx at the datacentre edge, and perhaps a sidecar next to each service. The names change; the concepts do not.

The path of one request from browser to JVM. | مسیر یک درخواست از مرورگر تا JVM.

flowchart LR
  U[Browser] -->|HTTPS| CDN[CDN / Edge]
  CDN -->|HTTPS| NG[nginx: TLS, cache, limits]
  NG -->|static files| FS[(Disk assets)]
  NG -->|HTTP keepalive| A1[Spring Boot #1]
  NG --> A2[Spring Boot #2]
  NG --> A3[Spring Boot #3]
  A1 --> DB[(Database)]
  A2 --> DB
  A3 --> DB

2. Anatomy: processes and contexts

The process model: why nginx holds tens of thousands of connections on little memory

Nginx starts one master process and several worker processes. The master only does privileged work (reading config, binding ports below 1024, opening log files, managing workers); the real work happens in workers running as an unprivileged user.

The key point: each worker is single-threaded and runs an event loop. Instead of "one thread per connection", one worker uses non-blocking system calls (epoll on Linux) to hold thousands of connections and only touches a socket when it is ready; an idle connection costs almost no memory. The same idea on the Java side is covered in the reactive-reactor and virtual-threads chapters.

A direct consequence of that design: because each worker is single-threaded, any operation that blocks that thread stalls every connection on that worker — a slow disk read, a heavy third-party module, or a Lua script doing synchronous I/O. Use sendfile on; (and aio threads; where needed) for large files, and never push heavy logic into nginx.

Contexts: an nginx config is a tree, not a list

nginx.conf is built from nested blocks called contexts. Keep the hierarchy in your head, because inheritance follows it:

• main (outermost, no block): whole-process settings — user, worker_processes, pid, error_log, load_module.
• events: the event loop — worker_connections, use, multi_accept.
• http: everything HTTP — include mime.types, log_format, gzip, upstream, and server blocks.
• server: one virtual host — listen, server_name, TLS certificates, and location blocks.
• location: rules for a URI path.

There are also stream (TCP/UDP proxying at layer 4), mail, and upstream.

Inheritance rule: a directive flows from an outer context into inner ones unless redefined. That sounds simple, and it is — except for one infamous exception you will meet in the security-headers section.

The skeleton of a real nginx.conf:

user  nginx;
worker_processes  auto;                 # one per CPU core
worker_rlimit_nofile 65535;             # file-descriptor ceiling per worker
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  8192;           # the default is only 512
    use epoll;                          # on Linux
    multi_accept on;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  75s;             # default is 75s
    server_tokens   off;                # do not advertise the nginx version

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" "$http_user_agent"';
    access_log  /var/log/nginx/access.log  main;

    include /etc/nginx/conf.d/*.conf;   # one file per site
}

Commands you need every day

nginx -v            # version
nginx -V            # version + compile flags and built modules
nginx -t            # test config only (mandatory before any reload)
nginx -T            # test + print the fully assembled config with all includes
nginx -s reload     # reload without dropping connections
nginx -s quit       # graceful shutdown (open connections finish)
nginx -s reopen     # close and reopen log files (for logrotate)

3. Virtual hosts: listen, server_name and server selection

One nginx can serve hundreds of domains on the same IP and port 443. Each server block is a virtual host, and nginx picks exactly one per request.

Selection has two stages:

1. Match address and port against the listen parameters.
2. Among servers listening on that address/port, compare the request's Host header with server_name in this priority order: exact name ← longest wildcard starting with * (*.example.com) ← longest wildcard ending with * (mail.*) ← the first matching regular expression in file order.
3. If nothing matches, the server marked default_server answers (or, if none is marked, the first server for that address/port).

server {
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    server_name _;                 # a name that never matches a real Host
    ssl_reject_handshake on;       # since 1.19.4 — refuse the TLS handshake
    return 444;                    # nginx-internal code: close without a response
}

server {
    listen 443 ssl;
    http2 on;                      # since 1.25.1 this is a standalone directive
    server_name shop.example.com www.shop.example.com;

    ssl_certificate     /etc/ssl/shop/fullchain.pem;
    ssl_certificate_key /etc/ssl/shop/privkey.pem;

    root /var/www/shop;
}

One version note: before nginx 1.25.1 you wrote listen 443 ssl http2;, but that listen parameter is now deprecated in favour of the standalone http2 on; directive at server or http level — which is also more practical, since you can enable HTTP/2 for one virtual host and disable it for another without fighting over a shared socket.

4. location: the rule everyone gets wrong

Once the server is chosen, nginx decides which location block governs the URI. This is where most "why is my config ignored?" bugs are born, because the order in the file is not the order of evaluation.

The exact algorithm: nginx checks all prefix locations and remembers the longest match; if that match used =, it stops there; if it used ^~, regexes are skipped; otherwise regexes are tried in the order they appear in the file and the first match wins; if no regex matches, the remembered longest prefix is used.

The location selection decision. | تصمیم انتخاب location.

flowchart TD
  S[Request URI] --> E{Exact '=' match?}
  E -- yes --> USE[Use it, stop]
  E -- no --> P[Find longest prefix match]
  P --> C{Prefix has '^~'?}
  C -- yes --> USE
  C -- no --> R[Scan regex locations in file order]
  R --> M{Any regex matched?}
  M -- yes --> UR[Use first matching regex]
  M -- no --> UP[Use longest prefix]

A worked example — read the config, then the table:

server {
    location = /health        { return 200 "ok\n"; }     # A
    location /                { proxy_pass http://app; }  # B
    location /static/         { root /var/www; }          # C
    location ^~ /downloads/   { root /srv; }              # D
    location ~* \.(png|jpg)$  { expires 30d; root /var/www; }  # E
}

Rows three and four are exactly what interviewers ask about: if you want a whole branch to stay out of the reach of generic regexes, you must write ^~. There are hundreds of configs in the wild that define /static/ while their images are served from a different block, and nobody notices until the cache headers disagree.

Performance-wise regexes are not free either: every request walks the regex list until the first match. For hot paths — health checks above all — use location = /path so the search ends on the first step.

5. Files, paths and rewriting: root, alias, try_files, return, rewrite

root vs alias

Both build a filesystem path, but differently — and that single difference is an endless source of bugs:

• root: final path = the root value + the whole URI.
• alias: final path = the alias value + whatever follows the location prefix (the prefix is replaced).

location /images/ {
    root /data/w3;          # /images/cat.png  ->  /data/w3/images/cat.png
}

location /i/ {
    alias /data/w3/images/; # /i/cat.png       ->  /data/w3/images/cat.png
}

try_files: the backbone of serving an SPA

try_files tries a list of candidates in order and serves the first one that exists; the last argument is either a URI for an internal redirect or a status code.

location / {
    root /var/www/spa;
    try_files $uri $uri/ /index.html;   # the standard React/Angular/Vue pattern
}

location /files/ {
    root /srv;
    try_files $uri =404;                # if the file is missing, say 404 explicitly
}

index and error_page

index names the file served when a URI points at a directory (index index.html index.htm;). error_page routes errors to another URI or code:

error_page 500 502 503 504 /50x.html;
location = /50x.html { root /usr/share/nginx/html; internal; }

# turn a backend failure into clean JSON
error_page 502 504 = @maintenance;
location @maintenance {
    default_type application/json;
    return 503 '{"error":"service_unavailable","retry_after":30}';
}

internal; means that location is reachable only through an internal redirect, never directly from outside.

return vs rewrite — a difference you must know

Both live in the rewrite module, but they do different jobs:

• return ends processing immediately and returns a code (optionally with a URL or a body). Cheap, explicit, predictable.
• rewrite rewrites the URI with a regex. With the last or break flag it is internal and the user sees nothing; with redirect (302) or permanent (301) it sends a redirect to the client.

# right: http to https with return — one line, no regex
server {
    listen 80;
    server_name shop.example.com;
    return 301 https://$host$request_uri;
}

# expensive and fragile: the same thing with rewrite
# rewrite ^(.*)$ https://$host$1 permanent;

# rewrite where it is genuinely needed: reshaping legacy URLs
rewrite ^/blog/([0-9]+)/(.*)$ /articles/$2?id=$1 last;

The flags differ: last means "restart the location search with the new URI", break means "change the URI but stay in this location". Misusing last inside a location that has a proxy_pass can create a rewrite loop and the rewrite or internal redirection cycle error in the log.

6. Variables, map, and logs that actually debug

Nginx exposes dozens of built-in variables: $uri (the current normalized URI), $request_uri (the raw URI including the query string), $args, $host, $http_<name> for any request header, $upstream_addr, $status and many more.

map builds a translation table: it derives a new variable from the value of another. It is declared at http level and is lazy — evaluated only when a request actually needs it.

http {
    # detect WebSocket clients
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }

    # bypass the cache for logged-in users
    map $http_cookie $skip_cache {
        default            0;
        "~*SESSION="       1;
    }
}

The log format you want in production

The default combined format is useless for debugging a reverse proxy because it says nothing about the upstream. Use this instead:

log_format upstream_json escape=json
  '{"time":"$time_iso8601","remote_addr":"$remote_addr",'
  '"request":"$request","status":$status,'
  '"request_time":$request_time,"upstream_addr":"$upstream_addr",'
  '"upstream_status":"$upstream_status",'
  '"upstream_connect_time":"$upstream_connect_time",'
  '"upstream_header_time":"$upstream_header_time",'
  '"upstream_response_time":"$upstream_response_time",'
  '"cache":"$upstream_cache_status","request_id":"$request_id"}';

access_log /var/log/nginx/access.log upstream_json buffer=64k flush=5s;

Four timing variables change everything: $request_time is the full lifetime of the request as nginx sees it (including the user's network), $upstream_connect_time is the time to establish TCP/TLS with the app, $upstream_header_time is the time until the first response-header byte ("how long the app thought"), and $upstream_response_time is the time until the last body byte.

If $upstream_response_time is small while $request_time is large, the application is innocent and the user is on a slow mobile network. That distinction ends endless backend-versus-infra arguments in one minute.

$request_id is a random identifier nginx generates per request; forward it with proxy_set_header X-Request-Id $request_id; so it lands in your Java logging MDC and you can jump from one nginx log line straight to the same request in the application log (details in the logging and observability chapters).

7. Proxying to the application: the heart of it

proxy_pass and the trailing-slash trap

proxy_pass forwards the request to an upstream address, which may be a host directly or the name of an upstream block:

upstream app {
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
}

server {
    location / {
        proxy_pass http://app;
    }
}

And now the single most important piece of syntax in this chapter: if you write a URI after the address (even just a /), nginx replaces the matched location prefix with that URI; if you do not, the original URI is passed untouched.

Headers: behind a proxy, the app is blind

The application no longer sees the user's IP (it sees nginx), does not know the user arrived over HTTPS (the internal hop is plain HTTP), and does not know the public hostname. All of that has to travel in headers:

location / {
    proxy_pass http://app;

    proxy_set_header Host              $host;                       # the real hostname
    proxy_set_header X-Real-IP         $remote_addr;                # client IP
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;  # the proxy chain
    proxy_set_header X-Forwarded-Proto $scheme;                     # http or https
    proxy_set_header X-Forwarded-Host  $host;
    proxy_set_header X-Forwarded-Port  $server_port;
}

Nginx's default for Host is $proxy_host, i.e. the name of the upstream block, not the user's domain — so without this override every link the app builds is wrong. $proxy_add_x_forwarded_for means "whatever arrived in the header, plus the current client IP", preserving the chain. $host is normalized (no port, lower-case, filled from server_name when the header is absent) and is what you want in 99% of cases, unlike the raw $http_host. RFC 7239 also defines a single Forwarded: for=...;proto=...;host=... header, which Spring understands too.

The Java side: making Spring Boot trust those headers

If you only send the headers and change nothing in the app, nothing happens: request.getScheme() still says http, redirects go to http://, and OAuth2 breaks with an invalid redirect_uri. The official switch is one property:

# native: the embedded web server's own support (RemoteIpValve in Tomcat)
# framework: Spring's own filter (ForwardedHeaderFilter / ForwardedHeaderTransformer)
server.forward-headers-strategy=native
# only these addresses are allowed to set forwarded headers
server.tomcat.remoteip.internal-proxies=10\\.0\\.1\\.\\d{1,3}

NATIVE delegates to the embedded server (in Tomcat that is RemoteIpValve, which by default trusts private ranges such as 10/8, 192.168/16 and 127/8), FRAMEWORK uses Spring's own filter which understands both X-Forwarded-* and Forwarded, and NONE — the default, except on recognised cloud platforms — does no processing at all.

Timeouts and buffering

proxy_connect_timeout 3s;    # default 60s — TCP connection setup only
proxy_send_timeout    30s;   # default 60s — between two write operations
proxy_read_timeout    30s;   # default 60s — between two read operations

proxy_read_timeout is not a cap on the whole response; it caps the gap between two consecutive bytes, so a stream that emits something every 10 seconds never times out. Keep proxy_connect_timeout to a few seconds (an internal connection either happens instantly or not at all), and set proxy_read_timeout slightly higher than the service's own internal timeout so the user gets the application's meaningful error rather than a shapeless 504 (see the resilience chapter).

With proxy_buffering on (the default) nginx reads the response into buffers (proxy_buffer_size for the header, proxy_buffers for the body, spilling to disk beyond that), releases the expensive application connection, and then feeds the client at the client's own speed — which is what protects your application threads from slow clients. But for live responses (SSE, log streaming) buffering means the user sees nothing until the end:

location /api/stream {
    proxy_pass http://app;
    proxy_buffering off;      # pass bytes through as they arrive
    gzip off;                 # compression buffers too
    proxy_read_timeout 1h;
}

If you would rather not create a location per streaming endpoint, the application can return the X-Accel-Buffering: no header; nginx honours it and disables buffering for that response only. The mirror-image setting is proxy_request_buffering (default on), which reads the entire request body before contacting the app; for streaming uploads you must turn it off, knowing that the application is then directly exposed to slow clients and retrying to another server is no longer possible.

WebSockets and keepalive

A WebSocket starts as an HTTP request carrying Upgrade: websocket, and nginx does not forward those headers by default:

map $http_upgrade $connection_upgrade {   # at http level
    default upgrade;
    ''      close;
}

location /ws/ {
    proxy_pass http://app;
    proxy_http_version 1.1;                       # the default since 1.29.7
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 3600s;                     # otherwise it dies every 60s
    proxy_send_timeout 3600s;
}

Ninety percent of WebSocket failures behind nginx have two causes: forgetting those two headers (which ends in 400 Bad Request or a fallback to polling), and the default 60-second proxy_read_timeout that closes an idle connection exactly one minute in, producing reports of "mysterious disconnects".

Every fresh TCP connection to the app costs a handshake and a socket in TIME_WAIT; with keepalive, connections stay pooled:

upstream app {
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
    keepalive 64;              # idle connections per worker
    keepalive_requests 1000;   # default
    keepalive_timeout  60s;    # default
}

8. Static files, compression and browser caching

Spring Boot can serve static files from classpath:/static, but every such request consumes a thread and the whole filter chain; handing the job to nginx frees CPU and gives finer control over cache headers:

# versioned assets (hashed file names) — cache forever
location ^~ /assets/ {
    root /var/www/app;
    expires 1y;
    add_header Cache-Control "public, immutable" always;
    access_log off;
    try_files $uri =404;
}

# HTML must never be cached permanently, or users see a stale app
location = /index.html {
    root /var/www/app;
    add_header Cache-Control "no-cache" always;
}

immutable tells the browser not even to revalidate, which is only safe when file names are content-hashed. Alongside it, sendfile on; (kernel-space copy from disk to socket), tcp_nopush on; and open_file_cache push CPU use down further.

gzip              on;      # default is off
gzip_comp_level   5;       # default 1; above 6 rarely pays off
gzip_min_length   1024;    # compressing tiny responses is a loss
gzip_vary         on;      # Vary: Accept-Encoding for intermediate caches
gzip_proxied      any;
gzip_types text/plain text/css application/json application/javascript
           application/xml image/svg+xml;

text/html is always compressed and need not be listed; never add already-compressed formats (JPEG, MP4, ZIP). Brotli typically shrinks text another 15–20% compared to gzip, but it is not part of the open-source nginx core: you must build or install the ngx_brotli module (the same is true for zstd). The practical pattern is gzip for dynamic responses, plus .br and .gz variants generated at build time and served pre-compressed for static assets. One security caveat: the BREACH family of attacks guesses secrets inside a compressed body (such as a CSRF token) by measuring response size, so for responses that mix attacker-controlled data with a secret, either randomise the token per response or disable compression there (see appsec-owasp).

9. Load balancing: spreading traffic and surviving failure

upstream app {
    zone app_zone 64k;              # shared state across all workers
    least_conn;                     # selection algorithm

    server 10.0.1.11:8080 weight=3 max_fails=3 fail_timeout=10s max_conns=200;
    server 10.0.1.12:8080;
    server 10.0.1.13:8080 backup;   # only when everything else is down
    # server 10.0.1.14:8080 down;   # temporarily out of rotation

    keepalive 64;
}

Health checks. Open-source nginx gives you the passive kind only: nginx judges servers by the outcome of real requests, and if max_fails errors occur within fail_timeout, the server leaves rotation for that period and is then retried. The active kind — periodically calling a health path independently of user traffic, via the health_check directive in ngx_http_upstream_hc_module — is part of the commercial subscription. In container environments the right answer is usually to delegate health decisions to the orchestrator: a readiness probe removes an unhealthy instance from the service endpoints while nginx simply distributes traffic (see ms-gateway-discovery).

Upstream server lifecycle under passive health checks. | چرخهٔ عمر سرور بالادستی با health check غیرفعال.

stateDiagram-v2
  [*] --> Healthy
  Healthy --> Suspect: request error or timeout
  Suspect --> Healthy: a request succeeds
  Suspect --> Failed: max_fails reached within fail_timeout
  Failed --> Probing: fail_timeout elapsed
  Probing --> Healthy: probe request succeeds
  Probing --> Failed: probe request fails

proxy_next_upstream error timeout http_502 http_503;   # default: error timeout
proxy_next_upstream_tries 2;
proxy_next_upstream_timeout 5s;

Sticky sessions, and why statelessness wins

If the application keeps sessions in its own memory, a user must always return to the same instance:

upstream app {
    server 10.0.1.11:8080 route=a;
    server 10.0.1.12:8080 route=b;
    sticky cookie srv_id expires=1h httponly secure samesite=lax path=/;
}

The sticky directive with its cookie, route and learn methods has been available in open-source nginx since 1.29.6 (before that it was commercial only, and teams used ip_hash or hash $cookie_jsessionid consistent). Still, the senior judgment is that stickiness is a patch, not an architecture: with sticky sessions a deployment throws away users' carts, horizontal scaling becomes uneven, and a hot instance cannot shed load. The right move is to make the service stateless — keep the session in Redis or in a signed token so any instance can answer any request (see spring-security and caching).

Blue-green and canary at the proxy layer

split_clients "${remote_addr}${http_user_agent}" $pool {
    5%   app_canary;
    *    app_stable;
}

map $http_x_canary $pool_final {      # let QA opt in with a header
    default   $pool;
    "on"      app_canary;
}

server {
    location / {
        proxy_pass http://$pool_final;   # upstream group name inside a variable
    }
}

Three practical conditions separate a canary from "experimenting on users": automated criteria (the canary's error rate and p99 latency must be measured separately, so tag the version in logs and metrics), fast rollback (changing the percentage must be a reload, not a deployment), and stable assignment (the split key must derive from a stable user identifier, otherwise one user bounces between versions and sees bizarre bugs). Blue-green needs the same machinery: two upstream groups and a map that switches between them.

10. TLS: terminating securely at the edge

Cryptography basics, CAs and the chain of trust are built in the crypto-foundations and pki-tls-gpg chapters; here we only take the web-tier view. The most common misconfiguration is this: ssl_certificate must be the fullchain — the server certificate followed by the intermediates in the same file. With a leaf-only certificate, browsers (which usually cache intermediates) show no problem, while Java clients, curl and mobile apps fail validation — a bug that presents as "it is only broken for some people".

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    listen 443 quic reuseport;           # HTTP/3 on the same port number, over UDP
    http2 on;
    http3 on;                            # on by default

    server_name shop.example.com;

    ssl_certificate     /etc/letsencrypt/live/shop/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/shop/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;       # with TLS 1.3, client preference is better
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;

    ssl_session_cache shared:SSL:10m;    # the default, none, means no resumption
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    add_header Alt-Svc 'h3=":443"; ma=86400' always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}

server {                                  # port 80 only for redirects and ACME
    listen 80;
    server_name shop.example.com;
    location /.well-known/acme-challenge/ { root /var/www/acme; }
    location / { return 301 https://$host$request_uri; }
}

HTTP/2 multiplexes many streams over one TCP connection and is enabled with http2 on;. HTTP/3 moves the same idea onto QUIC/UDP so that TCP-level head-of-line blocking disappears; enabling it needs a listen ... quic (ideally with reuseport, on the same port number) plus the Alt-Svc advertisement, because the browser arrives over ordinary HTTPS first and upgrades afterwards.

Strict-Transport-Security tells the browser "never speak http to me for this long". It is a one-way commitment: with a one-year max-age plus includeSubDomains, browsers that saw the header will refuse http until it expires, and any subdomain without TLS becomes unreachable. Start with a short value and grow it; adding preload is a decision that takes months to undo.

mTLS in both directions

# client side: demand a certificate from the caller
ssl_client_certificate /etc/ssl/internal-ca.pem;
ssl_verify_client on;                    # optional is also possible
location / {
    proxy_pass http://app;
    proxy_set_header X-Client-DN $ssl_client_s_dn;   # pass the identity to the app
}

# upstream side: present yourself to an internal service
location /secure/ {
    proxy_pass https://internal-app;
    proxy_ssl_certificate     /etc/ssl/nginx-client.pem;
    proxy_ssl_certificate_key /etc/ssl/nginx-client.key;
    proxy_ssl_trusted_certificate /etc/ssl/internal-ca.pem;
    proxy_ssl_verify       on;           # the default is off
    proxy_ssl_session_reuse on;
}

11. Caching in the proxy layer

proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api:20m
                 max_size=5g inactive=10m use_temp_path=off;

location /api/catalog/ {
    proxy_pass http://app;

    proxy_cache api;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    proxy_cache_valid 200 301 30s;
    proxy_cache_valid 404 5s;
    proxy_cache_lock on;                    # collapse a stampede on one key
    proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
    proxy_cache_background_update on;       # serve stale, refresh in the background
    proxy_cache_revalidate on;

    proxy_no_cache     $cookie_SESSION;     # never store a logged-in user's response
    proxy_cache_bypass $cookie_SESSION;     # and never read from cache for them

    add_header X-Cache-Status $upstream_cache_status always;
}

keys_zone is shared memory for metadata and max_size caps disk usage; inactive evicts a key that is not read within that window even if it is still fresh; use_temp_path=off keeps temporary files on the cache partition and avoids a cross-device copy. $upstream_cache_status is one of MISS, HIT, EXPIRED, STALE, UPDATING, REVALIDATED or BYPASS — without exposing it in logs and headers, "the cache is working" is guesswork.

The proxy cache decision flow. | جریان تصمیم کش proxy.

flowchart TD
  R[Request] --> B{bypass or no_cache?}
  B -- yes --> U[Go to upstream]
  B -- no --> K[Build cache key]
  K --> F{Fresh entry?}
  F -- yes --> H[HIT: serve from cache]
  F -- no --> S{Stale allowed?}
  S -- yes --> ST[STALE now, refresh in background]
  S -- no --> L{Another request filling it?}
  L -- yes --> W[Wait on cache lock]
  L -- no --> U
  U --> SV[Store if cacheable, then serve]

Purging. The proxy_cache_purge directive is part of the commercial subscription. In open source you have three options: the third-party ngx_cache_purge module; deleting the cache file directly (its path is derived from the MD5 of the key and the levels pattern); or, cleanest, versioning the cache key by adding a version variable to proxy_cache_key so that changed data naturally orphans the old key.

12. Protection: keeping attacks at the edge

# 10 requests per second per IP (one megabyte holds roughly 16k states)
limit_req_zone  $binary_remote_addr zone=perip:10m rate=10r/s;
limit_req_zone  $binary_remote_addr zone=login:10m rate=5r/m;
limit_conn_zone $binary_remote_addr zone=conn:10m;

limit_req_status  429;      # the default is 503; 429 is more meaningful
limit_conn_status 429;

location /api/ {
    limit_req  zone=perip burst=20 nodelay;
    limit_conn conn 20;
    proxy_pass http://app;
}

location = /auth/login {
    limit_req zone=login burst=3;   # no nodelay: slow them down, do not reject
    proxy_pass http://app;
}

The mental model for limit_req is a leaky bucket: requests are processed at a fixed rate, burst is the queue that absorbs a short spike, and anything beyond the queue is rejected with an error code. Without nodelay, queued requests are delayed so they proceed at the configured rate; with nodelay they are processed immediately but still consume queue capacity. For interactive APIs nodelay gives a better experience; for login and sensitive paths the delay is deliberately desirable, because it genuinely slows brute force. Use $binary_remote_addr as the key (it uses less memory), and before enforcing anything run a day with limit_req_dry_run on; and read the logs — the first number you pick is almost always too strict.

client_max_body_size    10m;    # the default is only 1m — beyond it, 413
client_body_timeout     10s;
client_header_timeout   10s;    # sending headers slowly = slowloris
send_timeout            10s;
large_client_header_buffers 4 8k;
server_tokens off;              # strip the version from Server and error pages

A slowloris attack opens hundreds of connections and dribbles headers out byte by byte to exhaust server capacity. Three weapons answer it: the short timeouts above, limit_conn per IP, and nginx's own event-driven architecture, for which an idle connection is nearly free — the exact opposite of a thread-per-connection server.

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Content-Security-Policy "default-src 'self'; frame-ancestors 'none'" always;

For blocking known attack shapes, the common options are ModSecurity/Coraza with the OWASP Core Rule Set, or commercial products. Two senior notes: an untuned WAF is full of false positives and must first run in detection-only mode; and a WAF does not replace secure code — it is an extra layer whose real value is buying time to patch a disclosed vulnerability (see appsec-owasp).

13. Operations: reload, diagnosis and tuning

nginx -t && nginx -s reload      # always test first, then reload
systemctl reload nginx           # the same thing via the HUP signal

On reload the master reads the new config and, if it is valid, spawns new workers and tells the old ones to stop accepting connections and exit once their work is done — so no request is dropped. A restart kills the process and starts it again, meaning a brief outage; it is only needed when something outside the config changed: a new binary, a new load_module, or changed service environment variables.

The first two commands in any incident: tail -f /var/log/nginx/error.log, and a quick tally of status codes from the access log. If you write JSON logs you can group by upstream_addr with jq and immediately see whether errors come from one instance or from all of them.

For monitoring, the stub_status module exposes the basic counters (active, accepted, handled connections and total requests):

location = /nginx_status {
    stub_status;
    allow 10.0.0.0/8;
    deny all;
}

The key number is that when accepted and handled differ, nginx hit a resource ceiling and dropped connections. Prometheus exporters turn this output or the logs into metrics (see observability). At the system level, net.core.somaxconn, ulimit -n and the ephemeral port range usually become bottlenecks before nginx itself does — another reason to keep upstream keepalive enabled (see linux-essentials).

14. Choosing a tool, and mapping it onto Kubernetes

The real selection criterion is usually not performance — under real load the differences are negligible next to application response time — but the configuration model. If the topology is static and machines have stable names, a static file (nginx or HAProxy) is simple and reviewable; if services move every few minutes, you want a tool that generates config from the source of truth. Decide by the rate of topology change, not by benchmark charts.

Kubernetes has exactly this same web tier, only the names change: an Ingress/Gateway is a declarative object saying which host and path map to which service and does nothing by itself; a controller is the process that reads that object and configures a real proxy (nginx, Envoy, Traefik, HAProxy) — that is, the same server, location and upstream from this chapter, generated from YAML; and a service mesh brings the same capabilities (mTLS, retries, circuit breaking, percentage routing, uniform metrics) to traffic between services, usually via a proxy beside each pod or at node level.

Mapping this chapter's concepts onto Kubernetes. | نگاشت مفاهیم این فصل به Kubernetes.

flowchart LR
  I[Ingress / Gateway object] --> C[Controller]
  C -->|generates config| P[Proxy data plane]
  P --> S1[Service A pods]
  P --> S2[Service B pods]
  S1 -->|mTLS, retries| M[Mesh sidecar]
  M --> S2

Cheat sheet