nginx Cheatsheet

Top configs.

Testing config

Validating nginx config before reload is the single highest-value habit. nginx -t catches syntax errors and missing files before they take down a working server; running it first is muscle memory worth building.

• nginx -t Syntax validation. Run before every reload; the cost is a second, the cost of skipping it is an outage.
• nginx -T Print the full effective configuration with includes resolved; the right tool when an override is mysteriously not taking effect.
• nginx -V Show compiled-in modules and configure flags; useful when a directive is unrecognised because the binary lacks the module.
• nginx -t -c /etc/nginx/nginx.conf Explicit-config validation; required on hosts with multiple configurations or non-default paths.

Reload and restart

Reload, not restart. Reload sends SIGHUP and forks new workers without dropping connections; restart kills connections and lengthens any incident.

• nginx -s reload In-place reload that preserves existing connections; the right way to apply config changes.
• nginx -s stop / nginx -s quit Graceful or immediate stop; quit waits for in-flight requests, stop drops them.
• systemctl reload nginx Signal wrapper preferred in systemd-managed environments; integrates with unit dependencies.
• Validate-then-reload script. Always nginx -t && nginx -s reload; the && catches typo-broken configs before they hit production.

Logs and debugging

Logs are where every nginx investigation starts. Access, error, and debug logs serve different purposes; reach for the right one and the answer is often visible immediately.

• Access log. /var/log/nginx/access.log. Request volume, status codes, latency, upstream selection. The first place to grep during traffic anomalies.
• Error log. /var/log/nginx/error.log. Config issues, upstream failures, SSL handshake errors. Read it before assuming the application is broken.
• Debug log. error_log debug level. Do not leave on in production; volume is enormous. Useful for tracking down a specific routing or rewrite issue.
• Per-vhost log files. Dedicated access and error log per server block; supports per-tenant investigation without grep gymnastics.

Upstream patterns

Upstream blocks are where nginx earns its load-balancer keep. The algorithm choice, health-check model, and keepalive setting decide whether nginx adds latency or removes it.

• upstream block. Backend list with round-robin by default; least_conn for uneven request cost, ip_hash for sticky sessions without cookies.
• Health checks. Active checks require Plus or third-party modules; open-source nginx does passive checks (mark unhealthy on connection failure, recheck after fail_timeout).
• keepalive directive. Pool upstream connections to avoid TCP handshake on every request; the latency saving is significant on chatty backends.
• Timeout tuning per upstream. Connect, send, and read timeouts; defaults are 60 seconds and rarely the right answer for production.

Performance tuning

Performance tuning is its own discipline. Workers, sendfile, file descriptors, and compression all stack; getting the basics right matters more than tuning any single knob.

• worker_processes auto. Match worker count to CPUs. worker_connections 1024 default; raise to 4096+ on high-traffic frontends to avoid hitting connection caps.
• sendfile on. Zero-copy file serving; significant CPU saving on static-content workloads.
• Open file descriptors. Set host ulimit -n and config worker_rlimit_nofile to match expected concurrent connections; running out of FDs produces confusing 502s.
• gzip and brotli compression. Compression module trades CPU for bandwidth; almost always worth it on text payloads.