nginx.conf Reference for Common Scenarios

TL;DR

• Bottom line: nginx is the most deployed web server/reverse proxy — these config patterns cover 90% of use cases: reverse proxy, static files, SSL termination, load balancing, and rate limiting.
• Key tool/command: nginx -t && nginx -s reload
• Watch out for: Never use if for routing inside location blocks — it causes surprising behavior. Use map or separate server blocks.
• Works with: nginx 1.24+ (mainline 1.27+), OpenSSL 3.x, Let's Encrypt / certbot, all Linux distros.

Constraints

• Always run nginx -t before nginx -s reload.
• Set server_tokens off — never expose version.
• SSL minimum: TLS 1.2. Disable SSLv3, TLS 1.0, TLS 1.1.
• Never use if inside location blocks for routing.
• worker_connections * worker_processes must not exceed ulimit -n.
• Keep proxy_buffering on (default).

Quick Reference

Decision Tree

START
├── Serving static files only?
│   ├── YES → Static file server config
│   └── NO ↓
├── Proxying to one backend?
│   ├── YES → Single reverse proxy
│   └── NO ↓
├── Multiple backends?
│   ├── YES → Upstream load balancer
│   └── NO ↓
├── Need SSL termination?
│   ├── YES → SSL block with Let's Encrypt
│   └── NO ↓
└── DEFAULT → Reverse proxy + SSL + security headers

Step-by-Step Guide

1. Install nginx

Install on your platform. [src6]

sudo apt update && sudo apt install -y nginx

Verify: nginx -v → nginx version shown

2. Configure reverse proxy

Route to backend application. [src1]

server {
    listen 80;
    server_name example.com;
    server_tokens off;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        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;
    }
}

Verify: sudo nginx -t && sudo nginx -s reload

3. Add SSL with Let's Encrypt

Enable HTTPS. [src2]

sudo certbot --nginx -d example.com

Verify: curl -I https://example.com → HTTP/2 200

4. Add rate limiting

Protect against abuse. [src5]

# In http block
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

# In location
location /api/ {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://backend;
}

Verify: send burst of requests, check for 429 responses

Code Examples

Static file server with caching

# Input:  Static file requests
# Output: Files with cache headers

server {
    listen 80;
    server_name static.example.com;
    root /var/www/static;
    server_tokens off;

    location ~* \.(css|js)$ { expires 1y; add_header Cache-Control "public, immutable"; }
    location ~* \.(png|jpg|svg|woff2)$ { expires 1y; add_header Cache-Control "public, immutable"; }
    location ~ /\. { deny all; return 404; }
}

Production reverse proxy + SSL + security

# Input:  Production nginx.conf
# Output: Hardened reverse proxy

user nginx;
worker_processes auto;
worker_rlimit_nofile 65535;

events { worker_connections 4096; multi_accept on; }

http {
    include /etc/nginx/mime.types;
    server_tokens off;
    sendfile on;
    keepalive_timeout 65;

    gzip on;
    gzip_types text/plain text/css application/json application/javascript image/svg+xml;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:SSL:10m;

    include /etc/nginx/conf.d/*.conf;
}

Anti-Patterns

Wrong: Using if for routing

# ❌ BAD — "if is evil" in nginx
location / {
    if ($request_uri ~* "/api") { proxy_pass http://api; }
}

Correct: Separate location blocks

# ✅ GOOD — explicit matching
location /api/ { proxy_pass http://api_backend; }
location / { proxy_pass http://web_backend; }

Wrong: Missing Host header

# ❌ BAD — backend sees proxy_host
location / { proxy_pass http://127.0.0.1:3000; }

Correct: Forward all headers

# ✅ GOOD — original context preserved
location / {
    proxy_pass http://127.0.0.1:3000;
    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;
}

Wrong: No security headers

# ❌ BAD — version exposed, no protection
server { listen 80; server_name example.com; }

Correct: Hardened headers

# ✅ GOOD — all protections enabled
server {
    listen 443 ssl http2;
    server_tokens off;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Strict-Transport-Security "max-age=63072000" always;
}

Common Pitfalls

• Skipping nginx -t before reload: Syntax errors crash the server. Fix: always nginx -t && nginx -s reload. [src3]
• proxy_pass trailing slash mismatch: Different behavior with/without trailing slash. Fix: be consistent. [src3]
• Low client_max_body_size: Default 1MB rejects uploads. Fix: set to 10m or higher. [src4]
• Missing worker_rlimit_nofile: FD limits hit under load. Fix: set to 65535. [src4]
• Disabling proxy_buffering: Workers block on slow clients. Fix: keep on (default). [src4]
• SSLv3/TLS 1.0/1.1: Vulnerable protocols. Fix: ssl_protocols TLSv1.2 TLSv1.3;. [src5]
• Public /nginx_status: Leaks server info. Fix: allow 127.0.0.1; deny all;. [src7]

Diagnostic Commands

# Test config syntax
sudo nginx -t

# Reload (zero-downtime)
sudo nginx -s reload

# Show compiled modules
nginx -V

# View access logs live
tail -f /var/log/nginx/access.log

# Check open connections
ss -tlnp | grep nginx

# Test SSL
openssl s_client -connect example.com:443 -tls1_2

# Check cert expiry
echo | openssl s_client -connect example.com:443 2>/dev/null | openssl x509 -noout -dates

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• The if directive is NOT a general-purpose conditional — only reliable for return and rewrite in server context.
• proxy_pass URI handling changes based on trailing slash presence.
• nginx does NOT auto-reload when config changes — explicit nginx -s reload required.
• HTTP/3 (QUIC) requires mainline 1.25+ compiled with --with-http_v3_module.