NGINX for Staff Engineers

00Mental model & positioning

NGINX is a single-binary, event-driven, C-based network proxy. It is not "a web server that also proxies" — in modern architectures it is a proxy that also happens to serve files well.

The five jobs NGINX does in production

Why it beat Apache — the C10K story

Apache's prefork/worker MPM allocated a process or thread per connection. Each idle keep-alive connection cost ~1–8 MB of RSS and a scheduler slot. 10,000 concurrent connections meant 10,000 threads: context-switch thrash, memory exhaustion, and latency that degraded superlinearly.

NGINX inverted this: a small fixed number of single-threaded workers, each running a non-blocking event loop over epoll (Linux) / kqueue (BSD). Connection state is a small heap struct (~1 KB), not a stack. Memory scales with active connections, not threads. 100k idle keep-alives on one box is routine.

Where NGINX sits in a modern stack

Editions you must be able to distinguish

01Process & event architecture

Process model

• Master runs as root only to bind privileged ports and read certs/keys, then supervises. It never touches request data.
• Workers drop to an unprivileged user (user nginx;). Each is single-threaded and owns an event loop. Set worker_processes auto; → one per CPU core.
• Cache loader runs at startup, walks the cache dir, and populates the shared-memory key index. Cache manager runs continuously enforcing max_size and inactive eviction.
• Shared memory zones are the only cross-worker state. This is why rate limits are approximately global rather than per-worker — but the counters live in a fixed-size slab that can fill up.

The event loop

Each worker loop iteration:

1. Compute the nearest timer expiry (red-black tree of timers).
2. epoll_wait() with that timeout → get a batch of ready fds.
3. For each ready fd, dispatch its read/write handler — a state machine that does a non-blocking chunk of work and returns.
4. Fire expired timers (request timeouts, keepalive expiry, resolver TTL).
5. Run posted events (deferred work queued by handlers).

Non-blocking disk I/O

# Offload blocking file reads to a thread pool so the loop keeps spinning
thread_pool default threads=32 max_queue=65536;

location /video/ {
    aio       threads=default;   # async read via pool
    directio  16m;                # bypass page cache for big files
    sendfile  off;                # sendfile and directio are mutually exclusive
    output_buffers 2 1m;
}

This is the pattern for large-media serving: without it, one cold 1 GB read blocks the worker for the duration of the seek+read.

Connection acceptance & the thundering herd

listen 443 ssl reuseport;   # declare on ONE server block per addr:port only
http2 on;

Memory model

• Per-connection pool: small arena allocator, freed wholesale at connection close — near-zero fragmentation, no GC pauses.
• Per-request pool: same idea, freed at request end.
• Shared slab zones: fixed size, declared in config. zone=name:10m. Roughly 16k $binary_remote_addr states per MB for limit_req; ~8k cache keys per MB for proxy_cache_path.

02Request processing phases

This is the highest-signal architecture question in an NGINX interview. Modules register handlers into ordered phases; understanding the order explains almost every "why did my directive not apply?" bug.

Response bodies then pass through the output filter chain (in order): ssi → sub_filter → gzip/brotli → chunked → writer. Headers pass through the header filter chain (add_header, headers_more, CORS).

Internal redirects

location / {
    try_files $uri $uri/ /index.html;   # each fallback re-enters FIND_CONFIG
}

location @fallback {                     # named location: only reachable internally
    proxy_pass http://legacy_backend;
}

location /api/ {
    error_page 404 = @fallback;             # "=" makes it adopt the fallback's status
    proxy_pass http://api_backend;
}

X-Accel-Redirect is the same machinery driven by the upstream: your app authorizes a download, then returns an empty 200 with X-Accel-Redirect: /protected/file.zip, and NGINX serves the file from an internal location. The app never streams bytes.

location /protected/ {
    internal;                            # 404 for direct client requests
    alias /var/data/files/;
}

03Configuration model

Context hierarchy

# ── main (global) ─────────────────────────────
user  nginx;
worker_processes  auto;
worker_rlimit_nofile 65535;
pid /run/nginx.pid;
error_log /var/log/nginx/error.log warn;
load_module modules/ngx_http_brotli_filter_module.so;

events {
    worker_connections 16384;
    multi_accept on;
    use epoll;
}

http {                                # ── L7 HTTP ──
    include mime.types;
    default_type application/octet-stream;

    upstream app { server 10.0.1.10:8080; }

    server {                          # virtual host
        listen 443 ssl;
        server_name api.example.com;

        location /v1/ {               # URI-scoped policy
            if ($request_method = POST) { ... }   # avoid — see gotchas
        }
    }
}

stream {                              # ── L4 TCP/UDP ──
    upstream pg { server 10.0.2.5:5432; }
    server { listen 5432; proxy_pass pg; }
}

Inheritance rules — the part people get wrong

server {
    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Frame-Options DENY always;

    location /api/ {
        add_header X-API-Version "2";   ← HSTS AND X-Frame-Options ARE NOW GONE for /api/
    }
}

Variables

04server & location matching

Step 1 — choosing the server block

1. Filter by listen — most specific IP:port match wins (10.0.0.1:80 beats *:80).
2. Among those, match server_name against the Host header, in this precedence:
   1. Exact: api.example.com
   2. Leading wildcard, longest first: *.example.com
   3. Trailing wildcard: www.example.*
   4. Regex, first match in config order: ~^(?<sub>.+)\.example\.com$
3. No match → the default_server for that listen, else the first server block defined.

server {                          # catch-all: unknown Host, direct IP hits, scanners
    listen 80 default_server;
    listen 443 ssl default_server;
    ssl_reject_handshake on;      # 1.19.4+: refuse TLS for unknown SNI
    server_name _;
    return 444;                     # nginx-special: close connection, no response
}

Step 2 — choosing the location

# Worked example — request: GET /images/logo.png
location /            { ... }   # prefix, len 1  → remembered
location /images/     { ... }   # prefix, len 8  → longest, remembered
location ~* \.(png|jpg)$ { ... } # regex        → EVALUATED, MATCHES → WINS

# Now add ^~ and the regex never runs:
location ^~ /images/  { ... }   # → WINS, regexes skipped

root vs alias — the eternal confusion

# root: location path is APPENDED to root
location /static/ {
    root /var/www;          # /static/a.js  →  /var/www/static/a.js
}

# alias: location path is REPLACED by alias
location /static/ {
    alias /var/www/assets/;  # /static/a.js  →  /var/www/assets/a.js
}

map — the right tool for conditional logic

# map builds a hash table, evaluated lazily, no "if" needed
map $http_user_agent $is_bot {
    default          0;
    ~*(googlebot|bingbot|crawler)  1;
}

map $request_method $limit_key {
    default  "";                   # empty key = limit not applied
    POST     $binary_remote_addr;
    PUT      $binary_remote_addr;
}

map $http_upgrade $connection_upgrade {   # canonical websocket map
    default upgrade;
    ''      close;
}

# Multi-input decisions: chain maps or use a composite key
map "$host:$uri" $backend {
    default                 app_default;
    ~^api\.  api_pool;
}

location /x {
    set $a 1;
    if ($http_x) { set $a 2; }   # creates nested ctx
    proxy_pass http://$a;             # may see the WRONG value / segfault paths
}

05Static content serving

server {
    root /var/www/site;

    # ── zero-copy path: file → socket without userspace ──
    sendfile       on;
    tcp_nopush     on;    # with sendfile: fill full packets before sending (TCP_CORK)
    tcp_nodelay    on;    # disable Nagle on keepalive conns → low latency for small responses

    # ── cache open file descriptors + stat() results ──
    open_file_cache          max=200000 inactive=20s;
    open_file_cache_valid    30s;
    open_file_cache_min_uses 2;
    open_file_cache_errors   on;   # cache 404s too

    location ^~ /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
        gzip_static on;         # serve pre-built app.js.gz if present
        brotli_static on;       # serve pre-built app.js.br if present
    }

    # ── SPA fallback ──
    location / {
        try_files $uri $uri/ /index.html;
    }
    location = /index.html {
        add_header Cache-Control "no-cache";   # revalidate the shell every load
    }
}

Compression

gzip on;
gzip_comp_level 5;          # 5 is the knee; 9 costs 3× CPU for ~2% size
gzip_min_length 256;        # below MTU, compression is a net loss
gzip_proxied any;
gzip_vary on;              # MUST — emits "Vary: Accept-Encoding" for correct CDN caching
gzip_types text/plain text/css application/json application/javascript
           application/xml image/svg+xml application/wasm;
# NOTE: text/html is ALWAYS compressed and must not be listed

brotli on;                # dynamic module; ~15-20% better than gzip for text
brotli_comp_level 4;

Byte-range & large files

location /downloads/ {
    aio threads;
    sendfile on;
    sendfile_max_chunk 2m;      # prevents one huge file monopolising a worker
    max_ranges 1;                # mitigate multi-range amplification DoS
    limit_rate_after 10m;        # first 10MB at full speed…
    limit_rate 2m;               # …then throttle to 2MB/s per connection
}

06Reverse proxy deep dive

The single most-asked config detail: proxy_pass trailing slash

A production-grade proxy block, annotated

location /api/ {
    proxy_pass http://api_pool;

    # ── protocol ────────────────────────────────────────────
    proxy_http_version 1.1;            # REQUIRED for keepalive + chunked + websockets
    proxy_set_header Connection "";    # clear inherited "close" so pooling works

    # ── identity headers ────────────────────────────────────
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host  $host;
    proxy_set_header X-Forwarded-Port  $server_port;
    proxy_set_header X-Request-ID      $request_id;   # trace correlation

    # ── timeouts (tune per endpoint, not globally) ──────────
    proxy_connect_timeout 2s;           # TCP handshake only — keep SHORT
    proxy_send_timeout    30s;          # between successive writes to upstream
    proxy_read_timeout    30s;          # between successive reads — NOT total time

    # ── buffering ───────────────────────────────────────────
    proxy_buffering       on;
    proxy_buffer_size     8k;           # must hold the full response HEADER
    proxy_buffers         16 8k;        # body buffers, per connection
    proxy_busy_buffers_size 16k;
    proxy_max_temp_file_size 256m;     # 0 = never spill to disk

    # ── request body ────────────────────────────────────────
    client_max_body_size  25m;          # else 413
    client_body_buffer_size 256k;
    proxy_request_buffering on;         # off = stream uploads straight through

    # ── failover ────────────────────────────────────────────
    proxy_next_upstream error timeout http_502 http_503 http_504;
    proxy_next_upstream_tries 2;
    proxy_next_upstream_timeout 5s;

    # ── hide leaky upstream headers ─────────────────────────
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;
}

Buffering: the concept interviewers dig into

# Streaming endpoint (SSE / LLM tokens)
location /stream {
    proxy_pass http://app;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 1h;
    chunked_transfer_encoding on;
    add_header X-Accel-Buffering no;   # upstream can also send this header to opt out
}

Timeouts — the mental model

Non-HTTP upstreams

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php-fpm.sock;      # unix socket beats TCP on localhost
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_buffers 16 16k;
}

location /grpc/ { grpc_pass grpc://grpc_pool; }
location /uwsgi/ { include uwsgi_params; uwsgi_pass unix:/run/uwsgi.sock; }
location /scgi/  { include scgi_params;  scgi_pass  127.0.0.1:9000; }

DNS resolution — a genuine production hazard

# PROBLEM: this resolves ONCE at startup/reload and caches forever.
# If the upstream is an ELB/ClusterIP whose IP rotates → traffic to a dead IP.
upstream api { server api.internal.example.com:443; }

# FIX A (OSS): force re-resolution via a variable + resolver
resolver 10.0.0.2 valid=10s ipv6=off;
location /api/ {
    set $api_host api.internal.example.com;
    proxy_pass https://$api_host$request_uri;   # note: must re-append URI
}

# FIX B (Plus): resolve=… on the upstream server, keeps pooling + LB
upstream api {
    zone api 64k;
    server api.internal.example.com:443 resolve;
    keepalive 64;
}

07Load balancing

upstream api_pool {
    zone api_pool 64k;          # shared memory → state shared ACROSS WORKERS

    least_conn;                  # algorithm (declare BEFORE servers)

    server 10.0.1.10:8080 weight=3 max_fails=3 fail_timeout=10s max_conns=200;
    server 10.0.1.11:8080 weight=1;
    server 10.0.1.12:8080 backup;      # only used when all primaries are down
    server 10.0.1.13:8080 down;        # admin-disabled, kept for hash stability
    server 10.0.1.14:8080 slow_start=30s;  /* PLUS: ramp weight after recovery */

    keepalive 64;                 # idle conns kept PER WORKER
    keepalive_requests 1000;
    keepalive_timeout 60s;
}

Algorithms

Upstream keepalive — the biggest single latency win

upstream app { server ...; keepalive 64; }

location / {
    proxy_pass http://app;
    proxy_http_version 1.1;         ← without this, HTTP/1.0, no keepalive
    proxy_set_header Connection ""; ← without this, "Connection: close" is forwarded
}

Missing either line silently disables pooling. Symptom: $upstream_connect_time is non-zero on every request, and you see TIME_WAIT socket buildup on the NGINX box (ss -s). A new TCP+TLS handshake per request adds 1–3 RTTs — often 5–40 ms of pure waste.

Session persistence

# OSS: hash on an app-provided cookie or header
upstream app {
    hash $cookie_sessionid consistent;
    server ...;
}

# PLUS: nginx issues and tracks its own cookie
upstream app {
    sticky cookie srv_id expires=1h domain=.example.com path=/ httponly secure;
}

08Health checks & resilience

Passive (OSS)

upstream app {
    zone app 64k;
    # 3 failures within a 10s window → mark down for 10s, then try ONE probe request
    server 10.0.1.10:8080 max_fails=3 fail_timeout=10s;
}
# What counts as a "failure" is defined by:
proxy_next_upstream error timeout http_502 http_503 http_504;

Note the coupling: fail_timeout is both the window in which failures are counted and the ejection duration. And recovery is "try one live request" — real users pay for the probe.

Active (Plus / Angie)

location / {
    proxy_pass http://app;
    health_check interval=5s fails=3 passes=2 uri=/healthz match=ok;
}
match ok {
    status 200;
    header Content-Type ~ application/json;
    body ~ '"status":\s*"ok"';
}

Circuit-breaker-ish behaviour

upstream app {
    zone app 64k;
    server a:8080 max_conns=100 max_fails=2 fail_timeout=15s;
    server b:8080 max_conns=100 max_fails=2 fail_timeout=15s;
    queue 100 timeout=3s;    /* PLUS: queue instead of instant 502 when max_conns is hit */
}

max_conns is your bulkhead: it caps concurrency per backend so one slow endpoint can't consume the whole app's thread pool. In OSS without queue, exceeding it returns 502 immediately — so pair it with a friendly error_page.

Graceful degradation

server {
    proxy_intercept_errors on;
    error_page 500 502 503 504 /maintenance.html;

    location = /maintenance.html {
        root /var/www/errors;
        internal;
        add_header Retry-After 30 always;
    }

    # Serve stale cache instead of an error — best-in-class degradation
    location / {
        proxy_cache zone1;
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
        proxy_cache_background_update on;
        proxy_pass http://app;
    }
}

09Caching

# ── http{} context ──────────────────────────────────────────
proxy_cache_path /var/cache/nginx/api
                 levels=1:2              # dir fan-out: /a/bc/<md5> — avoids huge dirs
                 keys_zone=api_cache:100m  # ~800k keys (≈8k keys per MB)
                 max_size=20g              # disk ceiling (soft; manager enforces)
                 inactive=60m              # evict if UNREQUESTED this long (independent of TTL)
                 use_temp_path=off;         # write in place, avoid cross-device copy

location /api/ {
    proxy_cache api_cache;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    proxy_cache_methods GET HEAD;

    # ── TTLs per status ──
    proxy_cache_valid 200 301 302  10m;
    proxy_cache_valid 404          1m;    # negative caching stops 404 storms
    proxy_cache_valid any          1m;

    # ── stampede control ──
    proxy_cache_lock on;                 # only ONE request populates a cold key
    proxy_cache_lock_timeout 5s;
    proxy_cache_lock_age 5s;
    proxy_cache_min_uses 2;               # don't cache one-hit-wonders (protects disk)

    # ── stale serving = availability ──
    proxy_cache_use_stale error timeout updating
                          http_500 http_502 http_503 http_504;
    proxy_cache_background_update on;     # serve stale NOW, refresh async
    proxy_cache_revalidate on;            # conditional GET w/ If-Modified-Since / ETag

    # ── bypass rules ──
    proxy_cache_bypass $http_authorization $cookie_session $arg_nocache;
    proxy_cache_no_cache $http_authorization $cookie_session;

    # ── ignore upstream cache-busting headers (use with care) ──
    proxy_ignore_headers Cache-Control Expires Set-Cookie X-Accel-Expires;

    add_header X-Cache-Status $upstream_cache_status always;
    proxy_pass http://api_pool;
}

proxy_cache_bypass vs proxy_cache_no_cache

You almost always want both for authenticated traffic. Setting only bypass is a well-known cause of cache poisoning where one user's private response gets served to everyone.

Microcaching — the highest-ROI trick

# Cache even "dynamic, personalized" pages for ONE second.
# 5,000 rps on a hot endpoint → 1 rps hits your app. 99.98% offload.
location / {
    proxy_cache micro;
    proxy_cache_valid 200 1s;
    proxy_cache_lock on;
    proxy_cache_use_stale updating error timeout;
    proxy_cache_background_update on;
    proxy_pass http://app;
}

The insight: for anonymous, read-heavy traffic, one second of staleness is invisible to users but collapses a traffic spike by three orders of magnitude. This is the standard answer to "how would you survive a front-page traffic spike without scaling the app tier?"

Cache stampede / thundering herd

Purging

# PLUS: native
location ~ /purge(/.*) {
    allow 10.0.0.0/8; deny all;
    proxy_cache_purge api_cache "$scheme$request_method$host$1";
}

# OSS options:
#  a) ngx_cache_purge third-party module
#  b) compute md5 of the cache key and rm the file:
#     echo -n "httpsGETexample.com/path" | md5sum
#     → /var/cache/nginx/api/<last-char>/<2 chars before>/<md5>
#  c) versioned cache keys — bump a $cache_version prefix on deploy (cleanest)

10TLS, HTTP/2 and HTTP/3

server {
    listen 443 ssl reuseport;
    listen [::]:443 ssl;
    http2 on;                                # 1.25.1+ (was `listen … http2`)

    listen 443 quic reuseport;                 # HTTP/3 over QUIC (UDP), 1.25.0+
    add_header Alt-Svc 'h3=":443"; ma=86400';  # advertise h3 to clients

    ssl_certificate     /etc/ssl/fullchain.pem;   # leaf + intermediates, in order
    ssl_certificate_key /etc/ssl/privkey.pem;

    # ── protocol & ciphers ──
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;             # modern advice: trust client order (TLS1.3)
    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_ecdh_curve X25519:prime256v1;

    # ── session resumption (huge CPU + RTT saver) ──
    ssl_session_cache   shared:SSL:50m;         # ~200k sessions; SHARED across workers
    ssl_session_timeout 1d;
    ssl_session_tickets on;
    ssl_session_ticket_key /etc/ssl/ticket1.key;  # rotate; share across the fleet
    ssl_session_ticket_key /etc/ssl/ticket2.key;  # older key, decrypt-only

    # ── OCSP stapling: server fetches revocation proof so clients don't have to ──
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/ssl/chain.pem;
    resolver 1.1.1.1 8.8.8.8 valid=300s;

    # ── TLS 1.3 0-RTT: 1 fewer RTT, but REPLAYABLE ──
    ssl_early_data on;
    proxy_set_header Early-Data $ssl_early_data;   # app must reject non-idempotent 0-RTT

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

Handshake cost — why termination is worth it

Multiple certs & SNI

# Dual RSA + ECDSA on one server block — client negotiates the best it supports
ssl_certificate     /etc/ssl/ecdsa.crt;   ssl_certificate_key /etc/ssl/ecdsa.key;
ssl_certificate     /etc/ssl/rsa.crt;     ssl_certificate_key /etc/ssl/rsa.key;

# Cert selection by SNI variable (avoids thousands of server blocks)
ssl_certificate     /etc/ssl/certs/$ssl_server_name.crt;
ssl_certificate_key /etc/ssl/certs/$ssl_server_name.key;
# (variables in ssl_certificate disable the cert cache → use ssl_certificate_cache in 1.27.4+)

mTLS (client certificates)

ssl_client_certificate /etc/ssl/ca.pem;
ssl_verify_client on;            # or `optional` to allow both and branch
ssl_verify_depth 2;
ssl_crl /etc/ssl/revoked.crl;

proxy_set_header X-Client-DN     $ssl_client_s_dn;
proxy_set_header X-Client-Verify $ssl_client_verify;   # SUCCESS | FAILED:reason | NONE
proxy_set_header X-Client-Serial $ssl_client_serial;

HTTP/2 & HTTP/3 notes worth stating

# HTTP/2 tuning
http2_max_concurrent_streams 128;
keepalive_requests 1000;         # h2 counts each STREAM as a request — raise this
# CVE-2023-44487 "Rapid Reset": mitigated in 1.25.3; also cap streams + keepalive_time

11Rate limiting & traffic shaping

Three independent limiters

# ── http{} ─────────────────────────────────────────────────
# 1. REQUEST RATE — leaky bucket, per key
limit_req_zone $binary_remote_addr zone=perip:10m  rate=10r/s;
limit_req_zone $server_name        zone=persrv:10m rate=1000r/s;
limit_req_zone $http_x_api_key     zone=perkey:20m rate=100r/s;

# 2. CONCURRENT CONNECTIONS
limit_conn_zone $binary_remote_addr zone=conn_perip:10m;

# 3. BANDWIDTH — per connection
#    (limit_rate / limit_rate_after, set in location or via $limit_rate)

limit_req_status  429;      # default is 503 — 429 is semantically correct
limit_conn_status 429;
limit_req_log_level warn;

location /api/ {
    limit_req  zone=perip burst=20 nodelay;
    limit_req  zone=persrv burst=200;      # multiple limits ALL apply; strictest wins
    limit_conn conn_perip 20;
    limit_rate 1m;
}

How the leaky bucket actually behaves

# Whitelist internal networks + trusted partners from the limiter
geo $limit_exempt {
    default          0;
    10.0.0.0/8       1;
    192.168.0.0/16   1;
}
map $limit_exempt $limit_key {
    0 $binary_remote_addr;   # limited
    1 "";                    # exempt
}
limit_req_zone $limit_key zone=perip:10m rate=10r/s;

Tiered limits by plan

map $http_x_api_key $plan {
    default       free;
    ~^pk_pro_     pro;
    ~^pk_ent_     ent;
}
map $plan $free_key { free $http_x_api_key; default ""; }
map $plan $pro_key  { pro  $http_x_api_key; default ""; }

limit_req_zone $free_key zone=free:10m rate=10r/s;
limit_req_zone $pro_key  zone=pro:10m  rate=500r/s;

location /api/ {
    limit_req zone=free burst=20 nodelay;
    limit_req zone=pro  burst=1000 nodelay;
}

12Security hardening & WAF

Baseline hardening

server_tokens off;                       # hide version in Server header + error pages
more_clear_headers Server;                # headers_more: remove it entirely

# Body / header size caps (DoS surface)
client_max_body_size        10m;
client_body_buffer_size     128k;
client_header_buffer_size   1k;
large_client_header_buffers 4 8k;
client_body_timeout         10s;
client_header_timeout       10s;

# Method allow-list
if ($request_method !~ ^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$) { return 405; }

# Block hidden files, backups, VCS
location ~ /\.(?!well-known) { deny all; access_log off; }
location ~* \.(bak|old|sql|env|git|swp)$ { deny all; }

# Security headers — repeat in EVERY location that sets any add_header
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
add_header X-Content-Type-Options    "nosniff" always;
add_header X-Frame-Options           "DENY" always;
add_header Referrer-Policy           "strict-origin-when-cross-origin" always;
add_header Content-Security-Policy    "default-src 'self'; frame-ancestors 'none'" always;
add_header Permissions-Policy         "geolocation=(), camera=(), microphone=()" always;

real_ip — get this wrong and every IP-based control is bypassable

set_real_ip_from 10.0.0.0/8;         # ONLY list proxies you actually control
set_real_ip_from 173.245.48.0/20;    # e.g. Cloudflare ranges
real_ip_header   X-Forwarded-For;
real_ip_recursive on;                 # walk XFF right-to-left, skipping trusted IPs

Access control

location /admin/ {
    allow 10.0.0.0/8;
    allow 2001:db8::/32;
    deny all;
    auth_basic "restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    satisfy all;      # require BOTH ip and password (default). `any` = either.
}

WAF options

load_module modules/ngx_http_modsecurity_module.so;
server {
    modsecurity on;
    modsecurity_rules_file /etc/nginx/modsec/main.conf;
}

Slowloris and friends

13Auth at the edge

auth_request — delegate authz to a service

server {
    location /api/ {
        auth_request /_authz;

        # pull identity out of the auth response and pass it downstream
        auth_request_set $user_id $upstream_http_x_user_id;
        auth_request_set $scopes  $upstream_http_x_scopes;
        proxy_set_header X-User-Id $user_id;
        proxy_set_header X-Scopes  $scopes;

        proxy_pass http://api_pool;
    }

    location = /_authz {
        internal;
        proxy_pass http://authz_service;
        proxy_pass_request_body off;               # auth svc doesn't need the body
        proxy_set_header Content-Length "";
        proxy_set_header X-Original-URI    $request_uri;
        proxy_set_header X-Original-Method $request_method;
        proxy_set_header Authorization     $http_authorization;
    }

    error_page 401 = @login;
    location @login { return 302 https://auth.example.com/login?rd=$scheme://$host$request_uri; }
}

Semantics: 2xx from the subrequest → allow. 401/403 → deny with that status. Anything else → 500.

JWT validation

/* NGINX PLUS — native */
location /api/ {
    auth_jwt "api";
    auth_jwt_key_file /etc/nginx/jwks.json;      # or auth_jwt_key_request for JWKS URL
    proxy_set_header X-Sub $jwt_claim_sub;
    proxy_pass http://api;
}

# OSS — njs or OpenResty
js_import auth.js;
location /api/ {
    auth_request /_jwt;
    proxy_pass http://api;
}
location = /_jwt { internal; js_content auth.verify; }

CORS done correctly

map $http_origin $cors_origin {
    default "";
    ~^https://(app|admin)\.example\.com$  $http_origin;   # echo only allowed origins
}

location /api/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin      $cors_origin always;
        add_header Access-Control-Allow-Methods     "GET, POST, PUT, DELETE, OPTIONS" always;
        add_header Access-Control-Allow-Headers     "Authorization, Content-Type" always;
        add_header Access-Control-Allow-Credentials "true" always;
        add_header Access-Control-Max-Age           86400 always;
        add_header Content-Length 0;
        return 204;
    }
    add_header Access-Control-Allow-Origin      $cors_origin always;
    add_header Access-Control-Allow-Credentials "true" always;
    add_header Vary Origin always;    ← REQUIRED or caches will serve the wrong ACAO
    proxy_pass http://api;
}

14Performance tuning

Capacity arithmetic

worker_processes auto;
worker_cpu_affinity auto;          # pin workers to cores → better cache locality
worker_rlimit_nofile 200000;
worker_shutdown_timeout 30s;      # cap how long old workers linger after reload

events {
    worker_connections 65535;
    multi_accept on;               # drain the whole accept queue per loop iteration
    use epoll;
}

http {
    sendfile on; tcp_nopush on; tcp_nodelay on;
    keepalive_timeout 75s;
    keepalive_requests 10000;
    reset_timedout_connection on;   # RST instead of FIN → free memory immediately
    server_names_hash_bucket_size 128;
    types_hash_max_size 4096;
    access_log /var/log/nginx/access.log main buffer=64k flush=5s;
    open_file_cache max=200000 inactive=20s;
}

Kernel tuning (/etc/sysctl.conf)

net.core.somaxconn = 65535              # accept queue depth (listen backlog ceiling)
net.core.netdev_max_backlog = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.ip_local_port_range = 1024 65535  # ephemeral ports for upstream conns
net.ipv4.tcp_tw_reuse = 1                # reuse TIME_WAIT for OUTGOING conns (safe)
net.ipv4.tcp_fin_timeout = 15
net.ipv4.tcp_slow_start_after_idle = 0   # don't reset cwnd on idle keepalives
net.ipv4.tcp_congestion_control = bbr
net.core.default_qdisc = fq
net.ipv4.tcp_fastopen = 3
fs.file-max = 2097152

# and in nginx:
listen 443 ssl backlog=65535;         # must be ≤ somaxconn

Ephemeral port exhaustion

A proxy opening a fresh TCP connection per upstream request burns one ephemeral port per request, each lingering in TIME_WAIT for 60s. With ~28k usable ports that caps you around 470 rps per upstream IP. Symptoms: connect() failed (99: Cannot assign requested address).

• Fix #1 (do this): upstream keepalive pooling — removes the problem entirely.
• Fix #2: widen ip_local_port_range, enable tcp_tw_reuse.
• Fix #3: more upstream IPs/ports — the 4-tuple includes the destination, so N backends give you N× the ports.
• Fix #4: Unix domain sockets for same-host upstreams (php-fpm, sidecars).

TLS CPU

• ECDSA certs are ~4–10× cheaper to sign than RSA-2048. Serve both, let clients pick.
• Session resumption converts a full handshake into a symmetric-key operation — the single biggest TLS win.
• Check openssl speed and whether AES-NI is available; on ARM/older CPUs prefer CHACHA20-POLY1305.
• ssl_buffer_size 4k; reduces TTFB for small responses (default 16k means the first record waits to fill).

Tuning checklist by symptom

15Logging & observability

Structured access logs

log_format json escape=json
  '{'
    '"ts":"$time_iso8601",'
    '"req_id":"$request_id",'
    '"remote_addr":"$remote_addr",'
    '"host":"$host",'
    '"method":"$request_method",'
    '"uri":"$request_uri",'
    '"status":$status,'
    '"bytes_sent":$body_bytes_sent,'
    '"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",'
    '"scheme":"$scheme",'
    '"tls_ver":"$ssl_protocol",'
    '"tls_cipher":"$ssl_cipher",'
    '"tls_reused":"$ssl_session_reused",'
    '"http_ver":"$server_protocol",'
    '"ua":"$http_user_agent",'
    '"referer":"$http_referer",'
    '"conn_reqs":$connection_requests
  '}';

access_log /var/log/nginx/access.log json buffer=64k flush=5s;
access_log syslog:server=10.0.0.5:514,tag=nginx,severity=info json;

# sample only 1% of successful requests, log ALL errors
map $status $loggable { ~^[23] 0; default 1; }
access_log /var/log/nginx/errors.log json if=$loggable;

The four latency variables — how to read them

Metrics

# OSS: minimal built-in stats
location = /nginx_status {
    stub_status;
    allow 127.0.0.1; allow 10.0.0.0/8; deny all;
    access_log off;
}
# → Active connections: 291
#   server accepts handled requests
#    16630948 16630948 31070465
#   Reading: 6 Writing: 179 Waiting: 106

/* PLUS: rich JSON API — per-upstream, per-zone, per-cache */
location /api { api write=on; allow 10.0.0.0/8; deny all; }
location = /dashboard.html { root /usr/share/nginx/html; }

• nginx-prometheus-exporter — scrapes stub_status (or the Plus API) into Prometheus.
• nginx-module-vts / Angie — per-server-zone and per-upstream metrics on OSS.
• Log-derived metrics — Vector/Fluent Bit parsing the JSON log into histograms is often the most flexible route (gives you true per-route p99).

Distributed tracing

# Propagate a correlation ID (works with any tracing backend)
proxy_set_header X-Request-ID $request_id;
add_header       X-Request-ID $request_id always;

# Native OpenTelemetry module (nginx 1.25.2+ / otel-nginx)
load_module modules/ngx_otel_module.so;
otel_exporter { endpoint otel-collector:4317; }
otel_service_name nginx-edge;
otel_trace on;
otel_trace_context propagate;   # inject/extract W3C traceparent

Golden signals to alert on

16Zero-downtime reload & binary upgrade

Config reload — SIGHUP

Binary upgrade (new nginx version, no dropped connections)

kill -USR2 $(cat /run/nginx.pid)   # old master renames pid→pid.oldbin, execs NEW binary
                                   # both masters now share the listen sockets
kill -WINCH $(cat /run/nginx.pid.oldbin)  # old workers finish & exit; old MASTER stays

# verify new version is healthy, then either:
kill -QUIT $(cat /run/nginx.pid.oldbin)   # commit: retire old master
# or roll back:
kill -HUP  $(cat /run/nginx.pid.oldbin)   # old master respawns its workers
kill -QUIT $(cat /run/nginx.pid)          # retire the new one

Signal reference

Safe deploy pipeline

# 1. render config from templates
# 2. syntax + semantic validation in a throwaway container
nginx -t -c /tmp/candidate/nginx.conf
# 3. diff against running config, require review for security-header changes
# 4. canary: reload ONE node, watch 5xx + latency for 5 min
# 5. rolling reload across the fleet with a health gate between nodes
# 6. automatic rollback: keep last-known-good config, reload it on SLO breach

# drain a node before maintenance (health endpoint returns 503 → LB removes it)
touch /etc/nginx/drain && sleep 30 && systemctl reload nginx

location = /healthz {
    access_log off;
    if (-f /etc/nginx/drain) { return 503 "draining"; }
    return 200 "ok";
    add_header Content-Type text/plain;
}

17Debugging playbook

First five commands

nginx -t                      # syntax check
nginx -T                      # dump the FULLY RESOLVED config (all includes) — invaluable
nginx -V                      # version + compile flags + which modules exist
ps -eo pid,ppid,rss,cmd | grep nginx
ss -s ; ss -tan state time-wait | wc -l

Turn on debug logging for one client only

# requires --with-debug (check nginx -V)
events { debug_connection 203.0.113.42; }     # or a CIDR
error_log /var/log/nginx/debug.log debug;
# This logs every phase transition for that one IP without drowning the box.

Error-log messages → root cause

Status codes NGINX itself generates

Live inspection

# which upstream served each request, and how long it took
tail -f access.log | jq -r '[.upstream_addr,.status,.upstream_response_time,.uri]|@tsv'

# connection state distribution
ss -tan | awk '{print $1}' | sort | uniq -c | sort -rn

# is a worker blocked? (should be in epoll_wait almost always)
strace -p $(pgrep -f 'nginx: worker' | head -1) -c -f

# flame graph a hot worker
perf record -F 99 -p $(pgrep -f 'nginx: worker' | head -1) -g -- sleep 30

# reproduce a request exactly as nginx sees it
curl -v --resolve api.example.com:443:10.0.1.5 https://api.example.com/health
openssl s_client -connect example.com:443 -servername example.com -tls1_3

18Stream module — L4 TCP/UDP proxying

stream {
    log_format basic '$remote_addr [$time_local] $protocol $status '
                     '$bytes_sent $bytes_received $session_time $upstream_addr';
    access_log /var/log/nginx/stream.log basic;

    # ── TCP load balancing (e.g. Postgres read replicas) ──
    upstream pg_read {
        zone pg_read 64k;
        least_conn;
        server 10.0.2.11:5432 max_fails=2 fail_timeout=10s;
        server 10.0.2.12:5432 max_fails=2 fail_timeout=10s;
    }
    server {
        listen 5432;
        proxy_pass pg_read;
        proxy_connect_timeout 2s;
        proxy_timeout 10m;              # idle timeout for the whole session
        proxy_socket_keepalive on;
    }

    # ── UDP (DNS, syslog, QUIC, game traffic) ──
    upstream dns { server 10.0.3.1:53; server 10.0.3.2:53; }
    server {
        listen 53 udp;
        proxy_pass dns;
        proxy_responses 1;             # expect exactly 1 datagram back
        proxy_timeout 1s;
    }

    # ── TLS passthrough routed by SNI (no decryption!) ──
    map $ssl_preread_server_name $sni_backend {
        api.example.com   api_tls;
        admin.example.com admin_tls;
        default           default_tls;
    }
    upstream api_tls     { server 10.0.4.1:443; }
    upstream admin_tls   { server 10.0.4.2:443; }
    upstream default_tls { server 10.0.4.3:443; }

    server {
        listen 443;
        ssl_preread on;              # peek at the ClientHello WITHOUT terminating
        proxy_pass $sni_backend;
    }

    # ── PROXY protocol: preserve client IP through an L4 hop ──
    server {
        listen 8443 proxy_protocol;    # accept PROXY header from an upstream LB
        set_real_ip_from 10.0.0.0/8;
        proxy_pass backend;
        proxy_protocol on;            # and emit it downstream
    }
}

PROXY protocol chain

19gRPC, WebSocket, SSE

gRPC

upstream grpc_svc {
    zone grpc_svc 64k;
    server 10.0.5.1:50051;
    server 10.0.5.2:50051;
    keepalive 32;
}

server {
    listen 443 ssl;
    http2 on;                          # gRPC REQUIRES HTTP/2 end to end

    location /helloworld.Greeter/ {       # route by fully-qualified service name
        grpc_pass grpc://grpc_svc;         # grpcs:// for TLS to upstream
        grpc_set_header X-Request-ID $request_id;
        grpc_read_timeout 1h;             # streaming RPCs are long-lived
        grpc_send_timeout 1h;
        grpc_socket_keepalive on;
    }

    # map gRPC status onto a sane error when the backend is gone
    error_page 502 = /grpc_unavailable;
    location = /grpc_unavailable {
        internal;
        add_header grpc-status 14 always;   # UNAVAILABLE
        add_header grpc-message "upstream unavailable" always;
        return 204;
    }
}

WebSocket

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

location /ws/ {
    proxy_pass http://ws_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host       $host;

    proxy_read_timeout  3600s;      # else idle sockets are killed after 60s
    proxy_send_timeout  3600s;
    proxy_buffering off;
    proxy_socket_keepalive on;
}

Server-Sent Events

location /events {
    proxy_pass http://sse_backend;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;           ← without this the client gets NOTHING until the end
    proxy_cache off;
    gzip off;                      ← gzip buffers too
    chunked_transfer_encoding off;
    proxy_read_timeout 24h;
}

20OpenResty, njs & modules

Module types

# Commonly-added modules
load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_geoip2_module.so;
load_module modules/ngx_http_headers_more_filter_module.so;   # merge/remove headers
load_module modules/ngx_http_modsecurity_module.so;
load_module modules/ngx_http_js_module.so;                    # njs
load_module modules/ngx_otel_module.so;

njs — JavaScript, first-party, lightweight

# /etc/nginx/njs/hmac.js
#   function verify(r) {
#     var sig = r.headersIn['X-Signature'];
#     ... compute expected ...
#     if (sig !== expected) { r.return(403); return; }
#     r.return(204);
#   }
#   export default { verify };

js_import hmac from njs/hmac.js;
js_set $tenant hmac.tenantFromToken;      # compute a variable in JS

location = /_verify { internal; js_content hmac.verify; }
location /api/ { auth_request /_verify; proxy_pass http://api; }

OpenResty / Lua — full request-phase control

lua_shared_dict ratelimit 10m;

location /api/ {
    access_by_lua_block {
        -- distributed rate limit backed by Redis
        local redis = require "resty.redis"
        local red = redis:new()
        red:set_timeouts(100, 100, 100)          -- NON-BLOCKING (cosocket)
        local ok = red:connect("redis", 6379)
        if not ok then return end                -- fail OPEN, not closed
        local key = "rl:" .. ngx.var.http_x_api_key
        local n = red:incr(key)
        if n == 1 then red:expire(key, 1) end
        red:set_keepalive(10000, 100)             -- return conn to pool
        if n > 100 then
            ngx.header["Retry-After"] = 1
            return ngx.exit(429)
        end
    }
    proxy_pass http://api;
}

Lua phase hooks map onto NGINX phases: set_by_lua → rewrite_by_lua → access_by_lua → content_by_lua → header_filter_by_lua → body_filter_by_lua → log_by_lua. Plus init_by_lua (master, pre-fork) and init_worker_by_lua (per worker — where you start background timers).

GeoIP

geoip2 /etc/nginx/GeoLite2-Country.mmdb {
    auto_reload 60m;
    $geoip2_country_code country iso_code;
}
map $geoip2_country_code $blocked { default 0; XX 1; YY 1; }
server { if ($blocked) { return 403; } }

21NGINX in Kubernetes

Two different controllers — know the difference

# Ingress with the common annotations
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "25m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "3"
    nginx.ingress.kubernetes.io/limit-rps: "100"
    nginx.ingress.kubernetes.io/limit-burst-multiplier: "5"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
    # canary: route 10% of traffic to this Ingress' backend
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "10"
    # or header-based canary for internal testing
    nginx.ingress.kubernetes.io/canary-by-header: "X-Canary"
spec:
  ingressClassName: nginx
  tls:
    - hosts: [api.example.com]
      secretName: api-tls
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /v1
            pathType: Prefix
            backend: { service: { name: api-svc, port: { number: 80 } } }

Ingress vs Gateway API

Ingress is expressively limited, so every vendor bolted on annotations — which are unportable and untyped. Gateway API (GatewayClass / Gateway / HTTPRoute / GRPCRoute) is the successor: role-oriented (infra team owns Gateway, app team owns HTTPRoute), typed, and supports header matching, traffic splitting, and request mirroring natively. Expect a question on this if the role is platform-flavoured.

NGINX as sidecar vs mesh

NGINX can be a sidecar, but it lacks a control plane: no xDS, no automatic mTLS identity (SPIFFE), no per-service circuit-breaker telemetry, no centralised policy. That's why meshes standardised on Envoy. NGINX's sweet spot in k8s is the north-south edge; Envoy owns east-west.

22NGINX vs Envoy vs HAProxy vs the rest

23Real-world architectures

A. Multi-tier edge for a high-traffic site

B. Canary / blue-green / A-B

# ── Weighted canary via split_clients (deterministic per user!) ──
split_clients "$cookie_uid$remote_addr" $variant {
    5%    canary;
    5%    canary_b;
    *     stable;
}
map $variant $pool {
    canary    app_v2;
    canary_b  app_v3;
    default   app_v1;
}
# Header override wins so QA can force a variant
map $http_x_force_variant $final_pool {
    v2       app_v2;
    v3       app_v3;
    default  $pool;
}

location / {
    proxy_pass http://$final_pool;
    add_header X-Variant $variant always;    # log & measure per variant
}

split_clients hashes the key with MurmurHash2, so the same user always lands in the same bucket across requests — essential or your A/B test is noise. Include something stable (user id) in the key, not just $request_id.

# ── Blue-green: flip an included file and reload ──
# /etc/nginx/active_pool.conf  contains:  set $active blue;
include /etc/nginx/active_pool.conf;
location / { proxy_pass http://app_$active; }

# ── Mirror traffic to a new stack without affecting users ──
location / {
    mirror /_shadow;
    mirror_request_body on;
    proxy_pass http://app_v1;
}
location = /_shadow {
    internal;
    proxy_pass http://app_v2$request_uri;
    proxy_connect_timeout 1s;
    # response is DISCARDED; client never waits on it
}

C. API gateway pattern

upstream users_svc  { zone u 64k; server users:8080;  keepalive 32; }
upstream orders_svc { zone o 64k; server orders:8080; keepalive 32; }

server {
    listen 443 ssl; http2 on;
    server_name api.example.com;

    # global policy
    limit_req zone=perkey burst=50 nodelay;
    auth_request /_authz;
    proxy_set_header X-Request-ID $request_id;

    # versioned routes; note ^~ so no regex is evaluated
    location ^~ /v1/users/  { rewrite ^/v1/users/(.*) /$1 break; proxy_pass http://users_svc; }
    location ^~ /v1/orders/ { rewrite ^/v1/orders/(.*) /$1 break; proxy_pass http://orders_svc; }

    # cacheable public reads
    location ^~ /v1/catalog/ {
        auth_request off;
        proxy_cache api_cache;
        proxy_cache_valid 200 60s;
        proxy_cache_lock on;
        proxy_pass http://catalog_svc;
    }

    # deprecation / sunset
    location ^~ /v0/ {
        add_header Sunset "Wed, 31 Dec 2026 23:59:59 GMT" always;
        add_header Deprecation "true" always;
        proxy_pass http://legacy_svc;
    }

    location = /_authz { internal; proxy_pass http://authz; ... }
}

D. Surviving a traffic spike (the "HN front page" question)

1. Microcache anonymous responses for 1s → app sees ~1 rps per distinct URL.
2. proxy_cache_lock on + use_stale updating + background_update → no stampede on expiry.
3. max_conns per backend → bulkhead so the app tier can't be overwhelmed.
4. limit_req keyed on IP with generous burst → shave off abusive clients only.
5. proxy_cache_use_stale error timeout http_5xx → if the app dies, keep serving the last good copy.
6. Static error_page fallback for anything not in cache — degraded, not down.
7. Push assets to the CDN with Cache-Control: immutable and long TTLs so NGINX never sees them.

E. Multi-region failover

upstream region_pool {
    zone region_pool 64k;
    server us-east.internal:443 max_fails=2 fail_timeout=10s;   # local
    server us-west.internal:443 backup;                        # DR — only on total local failure
    keepalive 32;
}
location / {
    proxy_pass https://region_pool;
    proxy_ssl_server_name on;            ← REQUIRED: send SNI upstream
    proxy_ssl_name $host;
    proxy_ssl_verify on;
    proxy_ssl_trusted_certificate /etc/ssl/internal-ca.pem;
    proxy_ssl_session_reuse on;
    proxy_next_upstream error timeout http_502 http_503;
    proxy_next_upstream_tries 2;
}

24Top 20 gotchas — rapid fire

25Interview Q&A bank

Click to reveal. Answers are written as you'd actually say them — with the trade-off, not just the fact.

Architecture & internals

Configuration

Load balancing & resilience

Caching

TLS & protocols

Operations

Design & judgement

26System design scenarios

27Cheat sheet

Commands

nginx -t                 # validate config
nginx -T                 # validate + dump FULL resolved config
nginx -V                 # version, compile flags, modules
nginx -s reload          # graceful reload
nginx -s quit            # graceful shutdown
nginx -s reopen          # reopen logs (logrotate)
nginx -c /path/nginx.conf -p /path/prefix
nginx -g "daemon off;"   # foreground — for containers/systemd

Directive quick reference

Sane defaults to open with

worker_processes auto;
worker_rlimit_nofile 65535;
events { worker_connections 16384; multi_accept on; }
http {
    sendfile on; tcp_nopush on; tcp_nodelay on;
    keepalive_timeout 75s; keepalive_requests 1000;
    client_max_body_size 10m;
    client_header_timeout 10s; client_body_timeout 10s;
    server_tokens off;
    reset_timedout_connection on;
    gzip on; gzip_vary on; gzip_comp_level 5; gzip_min_length 256;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:SSL:50m; ssl_session_timeout 1d;
    access_log /var/log/nginx/access.log json buffer=64k flush=5s;
}

287-day study plan