nginx Directives

Test and Reload

Never restart when a reload will do. Reload keeps existing connections open and falls back to the old config if the new one is broken.

The safe edit loop, in one line:

sudo nginx -t && sudo systemctl reload nginx

Server Blocks

One server block per site (virtual host). nginx picks the block by matching listen port, then server_name: exact name, longest *. wildcard, first matching regex, then the default_server.

A minimal static site:

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    root /var/www/example;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

The nginx config generator builds a full server block from a form.

Location Matching

File order does not decide prefix matches. nginx checks = first, then the longest prefix, then regexes in file order; the first regex hit wins, and only if none match does the longest prefix apply.

Reverse Proxy

proxy_pass forwards requests to an app server. Pass the headers below or the app sees every request as coming from 127.0.0.1 over HTTP.

A complete proxy block, websockets included:

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;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Upstream

An upstream block names a group of backend servers for proxy_pass http://name;. It lives directly inside http, next to your server blocks, not inside one.

upstream app {
    least_conn;
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
    keepalive 32;
}

root vs alias

root appends the full URI to the path; alias replaces the location prefix with the path.

location /img/ { root /var/www; }
# /img/a.png  ->  /var/www/img/a.png

location /img/ { alias /var/www/pics/; }
# /img/a.png  ->  /var/www/pics/a.png

Redirects and Rewrites

For a plain redirect, return is simpler and faster than rewrite.

The classic www and HTTP cleanup, as separate small server blocks:

server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://example.com$request_uri;
}

server {
    listen 443 ssl;
    server_name www.example.com;
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    return 301 https://example.com$request_uri;
}

SSL

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:SSL:10m;
}

Verify what a live server actually presents with the SSL checker, and inspect a cert file with the certificate decoder.

Gzip and Caching

Long cache for fingerprinted static assets:

location ~* \.(css|js|png|jpg|svg|woff2)$ {
    expires 365d;
    add_header Cache-Control "public, immutable";
}

map

map sets one variable from the value of another, and belongs directly inside http. It replaces most if chains.

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

map $host $backend {
    hostnames;
    default          http://127.0.0.1:3000;
    api.example.com  http://127.0.0.1:4000;
    *.example.com    http://127.0.0.1:3000;
}

Variables

Variables are read anywhere a directive takes a value, and any request header is available as $http_<name> with dashes turned into underscores.

Includes and File Locations

Logs and Error Pages

Startup failures land in the systemd journal rather than the error log; see the journalctl cheat sheet for journalctl -u nginx.

Allow, Deny and Auth

Rules are checked top to bottom and the first match wins.

location /admin/ {
    satisfy any;
    allow 192.168.1.0/24;
    deny  all;
    auth_basic "Admin";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Generate the password file with the htpasswd generator.

Timeouts and Limits

Stream

stream proxies raw TCP and UDP (databases, SMTP, game servers). It sits beside http in nginx.conf, never inside it, which is why pasting one into a conf.d/ file returns "stream directive is not allowed here".

stream {
    upstream db {
        server 10.0.0.10:5432;
    }

    server {
        listen 5432;
        proxy_pass db;
    }
}

Global and Events

The top of /etc/nginx/nginx.conf, outside every block. Simple directives here end in a semicolon; block directives take braces and no semicolon.

Modules

nginx: [emerg] unknown directive means nginx does not recognize the name at all. Either it is misspelled, or the module that provides it was never built into this binary or loaded.

Context Rules

Every directive is valid only in certain blocks; using the right directive in the wrong block is the "directive is not allowed here" error. Files under conf.d/ and sites-enabled/ are included inside http, so they can hold server, upstream, and map blocks.

Order and Inheritance

Gotchas

• The trailing slash on proxy_pass changes the URI: with a URI part (http://app/), the matched location prefix is stripped; without one (http://app), the path passes through untouched.
• add_header in a location throws away every add_header inherited from server and http. Repeat the parents' headers or set them all at one level.
• Prefer map and return over if. Inside a location, if combined with anything beyond return or rewrite behaves in famously surprising ways.
• If no block has default_server, the first server block for that port silently answers every unmatched hostname, including raw IP requests.
• When root seems to do nothing, check which server block actually answered (nginx -T), whether the root sits in a location the request never matched, and whether the worker user can traverse every parent directory. The error log prints the exact path nginx tried to open.
• error_page ignores statuses that came from a backend until you add proxy_intercept_errors on;, and the page it points at must be servable by the same server block.