Nginx (pronounced "engine-x") is a high-performance web server, reverse proxy, and load balancer originally created to solve the C10K problem — handling 10,000 concurrent connections. Unlike traditional servers that spawn a process per request, Nginx uses an asynchronous, event-driven architecture with worker processes, enabling it to handle thousands of simultaneous connections with minimal memory. Today, Nginx powers over 30% of the world's busiest websites, excelling in scenarios requiring high concurrency, low latency, and efficient resource use. Notable recent changes include HTTP/2 now being enabled with a standalone http2 on; directive (NGINX 1.25.1+, replacing the deprecated listen ... http2 syntax), Let's Encrypt discontinuing OCSP support in 2025 (making ssl_stapling a no-op for LE certificates), and the resolve parameter for dynamic DNS upstreams becoming open-source in NGINX 1.28+. The key to mastering Nginx is understanding its hierarchical configuration structure (main → http → server → location) and recognizing that context matters — where you place a directive determines its scope and behavior.
What This Cheat Sheet Covers
This topic spans 16 focused tables and 210 indexed concepts, 172 flashcards. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.
A jump-to index of every table row in this cheat sheet.
An interactive map of every table and concept in this topic.
Table 1: Configuration Contexts & Directive Hierarchy
Nginx configuration is organized as nested contexts; each directive is only valid in specific contexts and inherits from its parent unless overridden. Understanding the hierarchy prevents the most common placement errors — such as putting a server block inside location or a root directive in the wrong context.
| Directive | Example | Description | |
|---|---|---|---|
worker_processes auto;error_log /var/log/nginx/error.log; | • The top-level context • controls global settings like worker processes, PID file, error logging, and module loading | ||
http { include mime.types; gzip on;} | • Contains all HTTP-related configuration • parent of all server and upstream blocks • Directives here apply globally across all virtual hosts unless overridden | ||
server { listen 80; server_name example.com;} | • Defines a virtual host • Nginx selects the matching server block based on listen address and server_name • Multiple server blocks can share a port | ||
location /api/ { proxy_pass http://backend;} | • Matches a URI pattern and defines how matching requests are handled • Supports exact ( =), prefix, regex (~), and case-insensitive regex (~*) matching | ||
upstream backend { server 10.0.0.1:8080; server 10.0.0.2:8080;} | • Defines a named group of backend servers for load balancing • Referenced by proxy_pass, fastcgi_pass, etc • Must live inside http context | ||
events { worker_connections 1024;} | • Configures the connection processing model — worker_connections, use (epoll/kqueue), and multi_accept • Required in nginx.conf | ||
stream { server { listen 3306; proxy_pass db_backend; }} | • Top-level context (parallel to http, not inside it) for TCP/UDP proxying and load balancing • requires --with-stream compile flag or the ngx_stream_module dynamic module | ||
if ($http_user_agent ~ MSIE) { rewrite ^(.*)$ /msie/$1 break;} | • Conditionally executes directives • use sparingly — only return and rewrite behave predictably inside if. Many directives used inside if produce unexpected results | ||
geo $country { default unknown; 10.0.0.0/8 internal;} | • Maps client IP ranges to a variable value • evaluated once per connection • More efficient than repeated if checks• Must be in http context | ||
map $uri $new_uri { /old /new; default $uri;} | • Creates a variable whose value depends on another variable • lazy-evaluated only when the derived variable is actually used • Must be in http context, not inside server/location | ||
limit_except GET POST { deny all;} | • Restricts access to specified HTTP methods only • all unlisted methods are handled by the directives inside the block (typically deny or auth). | ||
include /etc/nginx/conf.d/*.conf; | • Inserts external files into the configuration at parse time • supports glob patterns • Use to split large configs into per-site or per-feature files | ||
load_module modules/ngx_http_brotli_filter_module.so; | • Loads a dynamic module at runtime from a .so file• must appear in main context before any blocks that use the module's directives |