Nginx Cheatsheet

Load Balancing

Use this Nginx reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

Upstream Block

http {
    upstream myapp {
        server 10.0.0.1:3000;
        server 10.0.0.2:3000;
        server 10.0.0.3:3000;
    }

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

Balancing Methods

Method	Directive	Description
Round-robin	(default, no keyword)	Requests distributed sequentially
Weighted round-robin	`weight=N` on each server	Higher weight → more requests
Least connections	`least_conn;`	Route to server with fewest active connections
IP hash	`ip_hash;`	Same client IP always hits same backend
Generic hash	`hash $variable [consistent];`	Hash on any variable (URI, cookie, etc.)
Random	`random [two least_conn];`	Pick randomly; optionally pick best of two

upstream myapp {
    least_conn;
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
}

upstream myapp_weighted {
    server 10.0.0.1:3000 weight=5;
    server 10.0.0.2:3000 weight=1;
}

upstream sticky {
    ip_hash;
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
}

upstream by_url {
    hash $request_uri consistent;
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
}

Server Parameters

Parameter	Example	What it does
`weight=N`	`weight=3`	Relative request share (default 1)
`max_fails=N`	`max_fails=3`	Failures before marking server down
`fail_timeout=T`	`fail_timeout=30s`	How long to consider server down
`backup`	`backup`	Only used when all non-backup servers are down
`down`	`down`	Permanently mark as unavailable (for maintenance)
`max_conns=N`	`max_conns=100`	Cap simultaneous connections (requires `zone`)

upstream myapp {
    server 10.0.0.1:3000 weight=5 max_fails=3 fail_timeout=30s;
    server 10.0.0.2:3000 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.0.3:3000 backup;
}

Health Checks (Open Source — Passive)

Nginx OSS uses passive health checks: a server is marked down after max_fails failed responses within fail_timeout.

upstream myapp {
    server 10.0.0.1:3000 max_fails=2 fail_timeout=10s;
    server 10.0.0.2:3000 max_fails=2 fail_timeout=10s;
}

Active health checks (health_check; directive) require Nginx Plus.

Keepalive Connections to Upstream

upstream myapp {
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
    keepalive 32;   # Max idle keepalive connections per worker
}

# Required in the proxy location
location / {
    proxy_pass http://myapp;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

Shared Memory Zone (for state across workers)

upstream myapp {
    zone myapp 64k;    # Shared among all workers
    server 10.0.0.1:3000 max_conns=50;
    server 10.0.0.2:3000 max_conns=50;
}

Required for max_conns to be enforced consistently across workers (and for the NGINX Plus live-activity API).

Upstream with Unix Sockets

upstream php_fpm {
    server unix:/run/php/php8.2-fpm.sock weight=1;
}

Slow Start (Nginx Plus only)

server 10.0.0.1:3000 slow_start=30s;
# Ramp up weight from 0 to configured value over 30 s after coming back up

Connection Stats (stub_status)

stub_status reports only aggregate connection counts — it has no per-upstream server state. Per-upstream status/dashboards are an NGINX Plus API feature; on OSS, infer backend health from $upstream_addr/$upstream_status in access logs and from error-log entries.

# Enable stub_status (built-in module)
server {
    listen 127.0.0.1:8080;
    location /nginx_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}

curl http://127.0.0.1:8080/nginx_status
# Active connections: 291
# server accepts handled requests
#  16630948 16630948 31070465
# Reading: 6 Writing: 179 Waiting: 106