Nginx Cheatsheet - Nginx Configuration & Command Reference
For engineers debugging 502/504s, adjusting location routing, or setting up reverse proxies. The hard part of Nginx is not the sheer number of directives but the details — location matching rules, whether proxy_pass carries a trailing slash, and upstream timeout tuning — which fail silently and only surface as anomalies under traffic. By the end you will validate with nginx -t before reloading, trace upstream errors back to the backend from the error log, and tell apart 502 Bad Gateway from 504 Gateway Timeout.
Commands & Testing 5
nginx -tnginx -s reloadnginx -Tsystemctl restart nginxnginx -VLocation Matching Priority 5
location = /pathlocation ^~ /static/location ~ \.php$location ~* \.(jpg|png)$location /pathReverse Proxy Snippets 5
proxy_pass http://127.0.0.1:8080;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_read_timeout 60s;client_max_body_size 50m;Logs & Troubleshooting 4
tail -f /var/log/nginx/error.logtail -f /var/log/nginx/access.loggrep " 502 " /var/log/nginx/access.logcurl -I http://localhostTips
- Trailing slash in proxy_pass changes semantics: with / replaces location prefix, without it appends.
- Always run nginx -t before reload — a syntax error won't break the running process but reload won't apply.
- For 502: check error.log — "connection refused" means backend is down, "timeout" means backend is too slow.
FAQ
How does Nginx decide the order of location matching?
Priority from highest to lowest: exact match with =, then the ^~ prefix (which stops without checking regexes), then regex ~/~* (the first matching regex wins, in config order), and finally plain longest-prefix matching. Both = and ^~ short-circuit immediately, while regex matching waits until all prefix locations have been tried.
When I get a 404, how do I tell whether the location did not match or the backend really returned 404?
Check the error log. If the request never reached the backend, you will only see an access entry, and the proxy_pass target server receives no request; if the backend returned 404, the log shows the upstream response to the backend request. You can also temporarily add a try_files rule or directly curl the backend port to compare.
What is the difference between proxy_pass with and without a trailing slash?
The key difference is path handling. When proxy_pass includes a URI such as http://upstream/api/, the part of the request that matched the location is appended to that path; when it has no URI (http://upstream or http://upstream/), the original request URI is passed through unchanged. Adding a path is how you rewrite /foo to a backend prefix like /api/... .
How do I troubleshoot a 502 Bad Gateway vs a 504 Gateway Timeout?
A 502 means Nginx could not get a valid response from the backend: first confirm the process is alive, the port is listening, and firewall and proxy_pass address are correct. A 504 means the backend exceeded the configured timeout, so check backend processing time first, then raise proxy_read_timeout/proxy_connect_timeout. Always cross-reference the upstream section of the error log in both cases.
Should I restart or reload after changing Nginx config?
Prefer nginx -s reload or systemctl reload nginx: it reloads gracefully without dropping existing connections and validates the config first. Only fall back to systemctl restart when the change touches parameters that cannot be hot-reloaded, such as listen sockets or worker counts, or when reload keeps failing. Always run nginx -t first.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Jul 21, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us