nginx Directives Reference

A fast, offline nginx directive lookup

nginx is configured entirely through directives, and each one is only valid in certain blocks. This reference lets you search by directive name, module or description and filter by the context where it applies, so you can wire up a reverse proxy, static host or rewrite rule without digging through the manual. It runs locally in your browser; no configuration is sent anywhere.

How it works

Every entry shows the directive name, the source module (e.g. ngx_http_proxy), the syntax with placeholders, the contexts in which the directive is valid, and the default value where one exists. nginx evaluates configuration as nested blocks: main -> events/http -> server -> location. Inner blocks inherit values from their parents and may override them. A minimal reverse proxy looks like:

server {
  listen 80;
  server_name example.com;
  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
  }
}

After editing, validate with nginx -t and apply with nginx -s reload.

Understanding directive context

The most common source of nginx configuration errors is placing a directive in the wrong block. For example, limit_req_zone must be in the http context — putting it inside a server or location block causes nginx to refuse to start with “directive is not allowed here.” Similarly, keepalive is an upstream context directive, not a proxy_pass argument.

The context filter in this reference is particularly useful when you know what you want to achieve but are not sure where the directive belongs. Filter by location to see what you can tune inside a location {} block, or filter by upstream to see load-balancing options.

Frequently used directive groups

Serving static files

• root — sets the base filesystem path for the request URI
• alias — replaces the matched location prefix with a filesystem path (useful when URL layout differs from disk layout)
• try_files — tries each path in order and falls back to the last argument
• expires — sets Cache-Control and Expires headers for browser caching
• index — specifies which file to serve for directory requests

Reverse proxying

• proxy_pass — the upstream URL or named upstream block
• proxy_set_header — modifies or adds request headers before forwarding
• proxy_read_timeout — how long to wait for the upstream response
• proxy_buffering — whether nginx buffers the full response before sending to the client
• proxy_cache_path and proxy_cache — response caching at the proxy layer

Security headers (via add_header)

• Strict-Transport-Security — tells browsers to enforce HTTPS
• X-Frame-Options — prevents clickjacking by controlling iframe embedding
• X-Content-Type-Options: nosniff — stops MIME-type sniffing
• Content-Security-Policy — restricts origins from which scripts, styles, and media can load

Tips and examples

• Use try_files $uri $uri/ /index.html; to serve a single-page app and fall back to the app shell for client-side routes.
• return 301 https://$host$request_uri; in a port-80 server block forces all traffic to HTTPS.
• Set client_max_body_size higher than the default 1m when accepting file uploads, or large requests fail with a 413.
• add_header ... always ensures the header is also sent on error responses, which matters for security headers like HSTS.