My notes on NGINX administration basics, tips & tricks, caveats, and gotchas.
Hi-diddle-diddle, he played on his
fiddle and danced with lady pigs.
Number three said, "Nicks on tricks!
I'll build my house with EN-jin-EKS!".
The Three Little Pigs: Who's Afraid of the Big Bad Wolf?
Other chapters
- HTTP Basics
- SSL/TLS Basics
- NGINX Basics
- Helpers
- Installing from prebuilt packages
- Installing from source
- Automatic installation for RHEL/Debian/BSD
- Nginx package
- Dependencies
- Patches
- 3rd party modules
- Configure options
- Compiler and linker
- SystemTap
- Installation Nginx on CentOS 7
- Installation OpenResty on CentOS 7
- Installation Tengine on Ubuntu 18.04
- Installation Nginx on FreeBSD 11.3
- Installation Nginx on FreeBSD 11.3 from ports
- Analyse configuration
- Monitoring
- Testing
- Build OpenSSL 1.0.2-chacha version
- Send request and show response headers
- Send request with http method, user-agent, follow redirects and show response headers
- Send multiple requests
- Testing SSL connection
- Testing SSL connection with SNI support
- Testing SSL connection with specific SSL version
- Testing SSL connection with specific cipher
- Verify 0-RTT
- Load testing with ApacheBench (ab)
- Load testing with wrk2
- Load testing with locust
- TCP SYN flood Denial of Service attack
- HTTP Denial of Service attack
- Debugging
- Show information about processes
- Check memory usage
- Show open files
- Dump configuration
- Get the list of configure arguments
- Check if the module has been compiled
- Show the most accessed IP addresses
- Show the top 5 visitors (IP addresses)
- Show the most requested urls
- Show the most requested urls containing 'string'
- Show the most requested urls with http methods
- Show the most accessed response codes
- Analyse web server log and show only 2xx http codes
- Analyse web server log and show only 5xx http codes
- Show requests which result 502 and sort them by number per requests by url
- Show requests which result 404 for php files and sort them by number per requests by url
- Calculating amount of http response codes
- Calculating requests per second
- Calculating requests per second with IP addresses
- Calculating requests per second with IP addresses and urls
- Get entries within last n hours
- Get entries between two timestamps (range of dates)
- Get line rates from web server log
- Trace network traffic for all processes
- List all files accessed by a NGINX
- Check that the gzip_static module is working
- Which worker processing current request
- Capture only http packets
- Extract User Agent from the http packets
- Capture only http GET and POST packets
- Capture requests and filter by source ip and destination port
- Dump a process's memory
- GNU Debugger (gdb)
- Shell aliases
- Configuration snippets
- Nginx server header removal
- Custom log formats
- Log only 4xx/5xx
- Restricting access with basic authentication
- Restricting access with client certificate
- Restricting access by geographical location
- Dynamic error pages with SSI
- Blocking/allowing IP addresses
- Blocking referrer spam
- Limiting referrer spam
- Limiting the rate of requests with burst mode
- Limiting the rate of requests with burst mode and nodelay
- Limiting the rate of requests per IP with geo and map
- Limiting the number of connections
- Using trailing slashes
- Properly redirect all HTTP requests to HTTPS
- Adding and removing the www prefix
- Proxy/rewrite and keep the original URL
- Proxy/rewrite and keep the part of original URL
- Proxy/rewrite without changing the original URL (in browser)
- Modify 301/302 response body
- Redirect POST request with payload to external endpoint
- Route to different backends based on HTTP method
- Allow multiple cross-domains using the CORS headers
- Set correct scheme passed in X-Forwarded-Proto
- Other snippets
- Recreate base directory
- Create a temporary static backend
- Create a temporary static backend with SSL support
- Generate password file with htpasswd command
- Generate private key without passphrase
- Generate CSR
- Generate CSR (metadata from existing certificate)
- Generate CSR with -config param
- Generate private key and CSR
- Generate ECDSA private key
- Generate private key with CSR (ECC)
- Generate self-signed certificate
- Generate self-signed certificate from existing private key
- Generate self-signed certificate from existing private key and csr
- Generate multidomain certificate
- Generate wildcard certificate
- Generate certificate with 4096 bit private key
- Generate DH public parameters
- Display DH public parameters
- Convert DER to PEM
- Convert PEM to DER
- Verification of the private key
- Verification of the public key
- Verification of the certificate
- Verification of the CSR
- Check whether the private key and the certificate match
- Base Rules (14)
- Organising Nginx configuration
- Format, prettify and indent your Nginx code
- Use reload option to change configurations on the fly
- Separate listen directives for 80 and 443
- Define the listen directives explicitly with address:port pair
- Prevent processing requests with undefined server names
- Never use a hostname in a listen or upstream directives
- Use only one SSL config for the listen directive
- Use geo/map modules instead of allow/deny
- Map all the things...
- Set global root directory for unmatched locations
- Use return directive for URL redirection (301, 302)
- Configure log rotation policy
- Don't duplicate index directive, use it only in the http block
- Debugging (4)
- Performance (11)
- Adjust worker processes
- Use HTTP/2
- Maintaining SSL sessions
- Use exact names in a server_name directive where possible
- Avoid checks server_name with if directive
- Use $request_uri to avoid using regular expressions
- Use try_files directive to ensure a file exists
- Use return directive instead of rewrite for redirects
- Enable PCRE JIT to speed up processing of regular expressions
- Make an exact location match to speed up the selection process
- Use limit_conn to improve limiting the download speed
- Hardening (28)
- Always keep NGINX up-to-date
- Run as an unprivileged user
- Disable unnecessary modules
- Protect sensitive resources
- Hide Nginx version number
- Hide Nginx server signature
- Hide upstream proxy headers
- Force all connections over TLS
- Use only the latest supported OpenSSL version
- Use min. 2048-bit private keys
- Keep only TLS 1.3 and TLS 1.2
- Use only strong ciphers
- Use more secure ECDH Curve
- Use strong Key Exchange with Perfect Forward Secrecy
- Prevent Replay Attacks on Zero Round-Trip Time
- Defend against the BEAST attack
- Mitigation of CRIME/BREACH attacks
- HTTP Strict Transport Security
- Reduce XSS risks (Content-Security-Policy)
- Control the behaviour of the Referer header (Referrer-Policy)
- Provide clickjacking protection (X-Frame-Options)
- Prevent some categories of XSS attacks (X-XSS-Protection)
- Prevent Sniff Mimetype middleware (X-Content-Type-Options)
- Deny the use of browser features (Feature-Policy)
- Reject unsafe HTTP methods
- Prevent caching of sensitive data
- Control Buffer Overflow attacks
- Mitigating Slow HTTP DoS attacks (Closing Slow Connections)
- Reverse Proxy (7)
- Use pass directive compatible with backend protocol
- Be careful with trailing slashes in proxy_pass directive
- Set and pass Host header only with $host variable
- Set properly values of the X-Forwarded-For header
- Don't use X-Forwarded-Proto with $scheme behind reverse proxy
- Always pass Host, X-Real-IP, and X-Forwarded headers to the backend
- Use custom headers without X- prefix
- Load Balancing (2)
- Others (2)
- Configuration Examples
Before you start playing with NGINX please read an official Beginner’s Guide. It's a great introduction for everyone.
Nginx (/ˌɛndʒɪnˈɛks/ EN-jin-EKS, stylized as NGINX or nginx) is an open source HTTP and reverse proxy server, a mail proxy server, and a generic TCP/UDP proxy server. It is originally written by Igor Sysoev. For a long time, it has been running on many heavily loaded Russian sites including Yandex, Mail.Ru, VK, and Rambler. In the April 2019 NGINX was the most commonly used HTTP server (see Netcraft survey).
NGINX is a fast, light-weight and powerful web server that can also be used as a:
- fast HTTP reverse proxy
- reliable load balancer
- high performance caching server
- full-fledged web platform
Generally, it provides the core of complete web stacks and is designed to help build scalable web applications. When it comes to performance, NGINX can easily handle a huge amount of traffic. The other main advantage of the NGINX is that allows you to do the same thing in different ways.
NGINX is also known as a Apache Killer. It is event-based, so it does not follow Apache's style of spawning new processes or threads for each web page request. Generally, it was created to solve the C10K problem.
Unlike traditional servers, NGINX doesn't rely on threads to handle requests and it was written with a different architecture in mind - one which is much more suitable for nonlinear scalability in both the number of simultaneous connections and requests per second.
For me, it is a one of the best and most important service that I used in my SysAdmin career.
These essential documents should be the main source of knowledge for you:
In addition, I would like to recommend three great docs focuses on the concept of the HTTP protocol:
- HTTP Made Really Easy
- Hypertext Transfer Protocol Specification
- Web technology for developers - HTTP
If you love security keep your eye on this one: Cryptology ePrint Archive. It provides access to recent research in cryptology and explores many subjects of security (e.g. Ciphers, Algorithms, SSL/TLS protocols). I also recommend to read Bulletproof SSL and TLS. Yep, it's definitely the most comprehensive book about deploying TLS for me.
When I was studying architecture of HTTP servers I became interested in NGINX. I found a lot of information about it but I've never found one guide that covers the most important things in a suitable form. I was a little disappointed.
I was interested in everything: NGINX internals, functions, security best practices, performance optimisations, tips & tricks, hacks and rules, but for me all documents treated the subject lightly.
Of course, Official Documentation is the best place but I know that we also have other great resources:
- agentzh's Nginx Tutorials
- Nginx Guts
- Nginx discovery journey
- Emiller’s Guide To Nginx Module Development
- Emiller’s Advanced Topics In Nginx Module Development
These are definitely the best assets for us and in the first place you should seek help there.
Moreover, in order to improve your knowledge please see Books chapter. It contains top literature on NGINX.
For me, however, there hasn't been a truly in-depth and reasonably simple cheatsheet which describe a variety of configurations and important cross-cutting topics for HTTP servers. I think, the configuration you provided should work without any talisman. That's why I created this repository.
This handbook is a collection of rules, helpers, notes, papers, best practices, and recommendations gathered and used by me (also in production environments). Many of them refer to external resources.
There are a lot of things you can do to improve NGINX server and this guide will attempt to cover as many of them as possible.
Throughout this handbook you will explore the many features and capabilities of the NGINX. You'll find out, for example, how to testing the performance or how to resolve debugging problems. You will learn configuration guidelines, security design patterns, ways to handle common issues and how to stay out of them. I explained here a few best tips to avoid pitfalls and configuration mistakes.
In this handbook I added set of guidelines and examples has also been produced to help you administer of the NGINX. They give us insight into NGINX internals also.
Mostly, I apply the rules presented here on the NGINX working as a reverse proxy. However, does not to prevent them being implemented for NGINX as a standalone server.
If you do not have the time to read hundreds of articles (just like me) this multipurpose handbook may be useful. I created it in the hope that it will be useful especially for System Administrators and Experts of web-based applications. I think it can also be a good complement to official documentation.
I did my best to make this handbook a single and consistent. Is organized in an order that makes logical sense to me. Of course, I still have a lot to improve and to do. I hope you enjoy it, and fun with it.
Remember about the following most important things:
Do not follow guides just to get 100% of something. Think about what you actually do at your server!
Blindly deploying of the rules described here can damage your web application.
There are no settings that are perfect for everyone.
The only correct approach is to understand your exposure, measure and tune.
These guidelines provides (in some places) recommendations for very restrictive setup.
A real community, however, exists only when its members interact in a meaningful way that deepens their understanding of each other and leads to learning.
If you find something which doesn't make sense, or something doesn't seem right, please make a pull request and please add valid and well-reasoned explanations about your changes or comments.
Before adding a pull request, please see the contributing guidelines.
If this project is useful and important for you, you can bring positive energy by giving some good words or supporting this project. Thank you!
What needs to be done? Look at the following ToDo list:
New chapters:
- Bonus Stuff
- HTTP Basics
- SSL/TLS Basics
- Reverse Proxy
- Caching
- Core modules
- 3rd party modules
- Web Application Firewall
- ModSecurity
- Debugging
Existing chapters:
Introduction
- Prologue
- Why I created this handbook
- Who this handbook is for
- Before you start
- Contributing & Support
- Checklist to rule them all
Bonus Stuff
- Fully automatic installation
- Static error pages generator
Books
- ModSecurity 3.0 and NGINX: Quick Start Guide
- Cisco ACE to NGINX: Migration Guide
External Resources
- Nginx official
- Nginx Forum
- Nginx Mailing List
- NGINX-Demos
- Presentations & Videos
- NGINX: Basics and Best Practices
- NGINX Installation and Tuning
- Nginx Internals (by Joshua Zhu)
- Nginx internals (by Liqiang Xu)
- How to secure your web applications with NGINX
- Tuning TCP and NGINX on EC2
- Extending functionality in nginx, with modules!
- Nginx - Tips and Tricks.
- Nginx Scripting - Extending Nginx Functionalities with Lua
- How to handle over 1,200,000 HTTPS Reqs/Min
- Using ngx_lua / lua-nginx-module in pixiv
- Static analyzers
- nginx-minify-conf
- Comparison reviews
- NGINX vs. Apache (Pro/Con Review, Uses, & Hosting for Each)
- Web cache server performance benchmark: nuster vs nginx vs varnish vs squid
- Builder tools
- Nginx-builder
- Benchmarking tools
- wrk2
- httperf
- slowloris
- slowhttptest
- GoldenEye
- Debugging tools
- strace
- GDB
- SystemTap
- stapxx
- htrace.sh
- Other stuff
- OWASP Cheat Sheet Series
- Mozilla Web Security
- Application Security Wiki
- OWASP ASVS 4.0
- The System Design Primer
- awesome-scalability
- Web Architecture 101
HTTP Basics
- Features and architecture
- URI vs URL
- HTTP Headers
- HTTP Methods
- Request
- Request line
- Methods
- Request URI
- HTTP version
- Request header fields
- Message body
- Generate requests
- Request line
- Response
- Status line
- HTTP version
- Status codes and reason phrase
- Response header fields
- Message body
- Status line
SSL/TLS Basics
- TLS versions
- TLS handshake
- Cipher suites
- Diffie-Hellman key exchange
NGINX Basics
- Configuration syntax
- Comments
- End of lines
- Variables, Strings, and Quotes
- Directives, Blocks, and Contexts
- External files
- Measurement units
- Regular expressions with PCRE
- Enable syntax highlighting
- Connection processing
- Event-Driven architecture
- Multiple processes
- Simultaneous connections
- HTTP Keep-Alive connections
- Server blocks logic
- Matching location
- if in location
- Nested locations
- rewrite vs return
- try_files directive
- if, break and set
- root vs alias
- internal directive
- External and internal redirects
- Matching location
- Log files
- Conditional logging
- Manually log rotation
- Reverse proxy
- Passing requests
- Trailing slashes
- Processing headers
- Passing headers
- Importance of the Host header
- Redirects and X-Forwarded-Proto
- A warning about the X-Forwarded-For
- Improve extensibility with Forwarded
- Load balancing algorithms
- Backend parameters
- Upstream servers with SSL
- Round Robin
- Weighted Round Robin
- Least Connections
- Weighted Least Connections
- IP Hash
- Generic Hash
- Fair module
- Other methods
- Rate Limiting
- Variables
- Directives, keys, and zones
- Burst and nodelay parameters
- Core modules
- ngx_http_geo_module
- 3rd party modules
- ngx_set_misc
- ngx_http_geoip_module
Helpers
- Installing from source
- Automatic installation for RHEL/Debian/BSD
- Compiler and linker
- Debugging Symbols
- SystemTap
- stapxx
- Separation and improvement of installation methods
- Installation Nginx on CentOS 7
- Installation OpenResty on CentOS 7
- Installation Tengine on Ubuntu 18.04
- Installation Nginx on FreeBSD 11.3
- Installation Nginx on FreeBSD 11.3 from ports
- Monitoring
- CollectD, Prometheus, and Grafana
- nginx-vts-exporter
- CollectD, InfluxDB, and Grafana
- Telegraf, InfluxDB, and Grafana
- CollectD, Prometheus, and Grafana
- Testing
- Build OpenSSL 1.0.2-chacha version
- Send request and show response headers
- Send request with http method, user-agent, follow redirects and show response headers
- Send multiple requests
- Testing SSL connection
- Testing SSL connection with SNI support
- Testing SSL connection with specific SSL version
- Testing SSL connection with specific cipher
- Verify 0-RTT
- Load testing with ApacheBench (ab)
- Standard test
- Test with Keep-Alive header
- Load testing with wrk2
- Standard scenarios
- POST call (with Lua)
- Random paths (with Lua)
- Multiple paths (with Lua)
- Random server address to each thread (with Lua)
- Multiple json requests (with Lua)
- Debug mode (with Lua)
- Analyse data pass to and from the threads
- Parsing wrk result and generate report
- Load testing with locust
- Multiple paths
- Multiple paths with different user sessions
- TCP SYN flood Denial of Service attack
- HTTP Denial of Service attack
- Debugging
- Show information about processes
- Check memory usage
- Show open files
- Dump configuration
- Get the list of configure arguments
- Check if the module has been compiled
- Show the most requested urls with http methods
- Show the most accessed response codes
- Calculating requests per second with IP addresses and urls
- Check that the gzip_static module is working
- Which worker processing current request
- Capture only http packets
- Extract User Agent from the http packets
- Capture only http GET and POST packets
- Capture requests and filter by source ip and destination port
- Server Side Include (SSI) debugging
- Dump a process's memory
- GNU Debugger (gdb)
- Dump configuration from a running process
- Show debug log in memory
- Core dump backtrace
- SystemTap cheatsheet
- stapxx
- Errors & Issues
- Common errors
- Configuration snippets
- Nginx server header removal
- Custom log formats
- Log only 4xx/5xx
- Restricting access with client certificate
- Restricting access by geographical location
- GeoIP 2 database
- Custom error pages
- Dynamic error pages with SSI
- Limiting the rate of requests per IP with geo and map
- Using trailing slashes
- Properly redirect all HTTP requests to HTTPS
- Adding and removing the www prefix
- Proxy/rewrite and keep the original URL
- Proxy/rewrite and keep the part of original URL
- Proxy/rewrite without changing the original URL (in browser)
- Modify 301/302 response body
- Redirect POST request with payload to external endpoint
- Route to different backends based on HTTP method
- Redirect users with certain IP to special location
- Allow multiple cross-domains using the CORS headers
- Set correct scheme passed in X-Forwarded-Proto
- Tips and methods for high load traffic testing (cheatsheet)
- Location matching examples
- Passing requests to the backend
- The HTTP backend server
- The uWSGI backend server
- The FastCGI backend server
- The memcached backend server
- The Redis backend server
- HTTPS traffic to upstream servers
- TCP and UDP load balancing
- Lua snippets
- nginscripts snippets
- Other snippets
- Recreate base directory
- Create a temporary static backend
- Create a temporary static backend with SSL support
- Generate password file with htpasswd command
- Generate private key without passphrase
- Generate CSR
- Generate CSR (metadata from existing certificate)
- Generate CSR with -config param
- Generate private key and CSR
- Generate ECDSA private key
- Generate private key with CSR (ECC)
- Generate self-signed certificate
- Generate self-signed certificate from existing private key
- Generate self-signed certificate from existing private key and csr
- Generate multidomain certificate
- Generate wildcard certificate
- Generate certificate with 4096 bit private key
- Generate DH public parameters
- Display DH public parameters
- Convert DER to PEM
- Convert PEM to DER
- Verification of the private key
- Verification of the public key
- Verification of the certificate
- Verification of the CSR
- Check whether the private key and the certificate match
Base Rules
- Format, prettify and indent your Nginx code
- Never use a hostname in a listen or upstream directives
- Making a rewrite absolute (with scheme)
- Use return directive for URL redirection (301, 302)
- Configure log rotation policy
- Don't duplicate index directive, use it only in the http block
Debugging
- Disable daemon, master process, and all workers except one
- Use core dumps to figure out why NGINX keep crashing
- Use mirror module to copy requests to another backend
- Dynamic debugging with echo module
- Dynamic debugging with SSI
Performance
- Avoid multiple index directives
- Use $request_uri to avoid using regular expressions
- Use try_files directive to ensure a file exists
- Don't pass all requests to the backend - use try_files
- Use return directive instead of rewrite for redirects
- Enable PCRE JIT to speed up processing of regular expressions
- Set proxy timeouts for normal load and under heavy load
- Configure kernel parameters for high load traffic
Hardening
- Keep NGINX up-to-date
- Use only the latest supported OpenSSL version
- Prevent Replay Attacks on Zero Round-Trip Time
- Enable OCSP Stapling
- Prevent caching of sensitive data
- Set properly files and directories permissions (also with acls) on a paths
- Implement HTTPOnly and secure attributes on cookies
Reverse Proxy
- Use pass directive compatible with backend protocol
- Be careful with trailing slashes in proxy_pass directive
- Set and pass Host header only with $host variable
- Set properly values of the X-Forwarded-For header
- Don't use X-Forwarded-Proto with $scheme behind reverse proxy
- Always pass Host, X-Real-IP, and X-Forwarded headers to the backend
- Use custom headers without X- prefix
- Set proxy buffers and timeouts
Others
- Define security policies with security.txt
If you have any idea, send it back to me or add a pull request.
This checklist contains all rules (68) from this handbook.
Generally, I think that each of these principles is important and should be considered. I tried, however, to separate them into four levels of priority which I hope will help guide your decision.
Remember, these are only guidelines. My point of view may be different from yours so if you feel these priority levels do not reflect your configurations commitment to security, performance or whatever else, you should adjust them as you see fit.
RULE | CHAPTER | PRIORITY |
---|---|---|
Define the listen directives explicitly with address:port pair Prevents soft mistakes which may be difficult to debug. |
Base Rules | |
Prevent processing requests with undefined server names It protects against configuration errors, e.g. traffic forwarding to incorrect backends. |
Base Rules | |
Never use a hostname in a listen or upstream directives While this may work, it will comes with a large number of issues. |
Base Rules | |
Configure log rotation policy Save yourself trouble with your web server: configure appropriate logging policy. |
Base Rules | |
Use HTTP/2 HTTP/2 will make our applications faster, simpler, and more robust. |
Performance | |
Enable PCRE JIT to speed up processing of regular expressions NGINX with PCRE JIT is much faster than without it. |
Performance | |
Always keep NGINX up-to-date Use newest NGINX package to fix vulnerabilities, bugs, and to use new features. |
Hardening | |
Run as an unprivileged user Use the principle of least privilege. This way only master process runs as root. |
Hardening | |
Protect sensitive resources Hidden directories and files should never be web accessible. |
Hardening | |
Hide upstream proxy headers Don't expose what version of software is running on the server. |
Hardening | |
Force all connections over TLS Protects your website especially for handle sensitive communications. |
Hardening | |
Use min. 2048-bit private keys 2048 bits private keys are sufficient for commercial use. |
Hardening | |
Keep only TLS 1.3 and TLS 1.2 Use TLS with modern cryptographic algorithms and without protocol weaknesses. |
Hardening | |
Use only strong ciphers Use only strong and not vulnerable cipher suites. |
Hardening | |
Use more secure ECDH Curve Use ECDH Curves with according to NIST recommendations. |
Hardening | |
Use strong Key Exchange with Perfect Forward Secrecy Establishes a shared secret between two parties that can be used for secret communication. |
Hardening | |
Defend against the BEAST attack The server ciphers should be preferred over the client ciphers. |
Hardening | |
HTTP Strict Transport Security Tells browsers that it should only be accessed using HTTPS, instead of using HTTP. |
Hardening | |
Reduce XSS risks (Content-Security-Policy) CSP is best used as defence-in-depth. It reduces the harm that a malicious injection can cause. |
Hardening | |
Control the behaviour of the Referer header (Referrer-Policy) The default behaviour of referrer leaking puts websites at risk of privacy and security breaches. |
Hardening | |
Provide clickjacking protection (X-Frame-Options) Defends against clickjacking attack. |
Hardening | |
Prevent some categories of XSS attacks (X-XSS-Protection) Prevents to render pages if a potential XSS reflection attack is detected. |
Hardening | |
Prevent Sniff Mimetype middleware (X-Content-Type-Options) Tells browsers not to sniff MIME types. |
Hardening | |
Reject unsafe HTTP methods Only allow the HTTP methods for which you, in fact, provide services. |
Hardening | |
Prevent caching of sensitive data It helps to prevent critical data (e.g. credit card details, or username) leaked. |
Hardening | |
Use pass directive compatible with backend protocol Set pass directive only to working with compatible backend layer protocol. |
Reverse Proxy | |
Set properly values of the X-Forwarded-For header Identify clients communicating with servers located behind the proxy. |
Reverse Proxy | |
Don't use X-Forwarded-Proto with $scheme behind reverse proxy Prevent pass incorrect value of this header. |
Reverse Proxy | |
Organising Nginx configuration Well organised code is easier to understand and maintain. |
Base Rules | |
Format, prettify and indent your Nginx code Formatted code is easier to maintain, debug, and can be read and understood in a short amount of time. |
Base Rules | |
Use reload option to change configurations on the fly Graceful reload of the configuration without stopping the server and dropping any packets. |
Base Rules | |
Use return directive for URL redirection (301, 302) The by far simplest and fastest because there is no regexp that has to be evaluated. |
Base Rules | |
Maintaining SSL sessions Improves performance from the clients’ perspective. |
Performance | |
Use exact names in a server_name directive where possible Helps speed up searching using exact names. |
Performance | |
Avoid checks server_name with if directive It decreases NGINX processing requirements. |
Performance | |
Use $request_uri to avoid using regular expressions By default, the regex is costly and will slow down the performance. |
Performance | |
Use try_files directive to ensure a file exists Use it if you need to search for a file, it saving duplication of code also. |
Performance | |
Use return directive instead of rewrite for redirects Use return directive to more speedy response than rewrite. |
Performance | |
Disable unnecessary modules Limits vulnerabilities, improve performance and memory efficiency. |
Hardening | |
Hide Nginx version number Don't disclose sensitive information about NGINX. |
Hardening | |
Hide Nginx server signature Don't disclose sensitive information about NGINX. |
Hardening | |
Use only the latest supported OpenSSL version Stay protected from SSL security threats and don't miss out new features. |
Hardening | |
Prevent Replay Attacks on Zero Round-Trip Time 0-RTT is disabled by default but you should know that enabling this option creates a significant security risks. |
Hardening | |
Mitigation of CRIME/BREACH attacks Disable HTTP compression or compress only zero sensitive content. |
Hardening | |
Deny the use of browser features (Feature-Policy) A mechanism to allow and deny the use of browser features. |
Hardening | |
Control Buffer Overflow attacks Prevents errors are characterised by the overwriting of memory fragments of the NGINX process. |
Hardening | |
Mitigating Slow HTTP DoS attacks (Closing Slow Connections) Prevents attacks in which the attacker sends HTTP requests in pieces slowly. |
Hardening | |
Set and pass Host header only with $host variable Use of the $host is the only one guaranteed to have something sensible. |
Reverse Proxy | |
Always pass Host, X-Real-IP, and X-Forwarded headers to the backend It gives you more control of forwarded headers. |
Reverse Proxy | |
Enable DNS CAA Policy Allows domain name holders to indicate to CA whether they are authorized to issue digital certificates. |
Others | |
Separate listen directives for 80 and 443 Help you maintain and modify your configuration. |
Base Rules | |
Use only one SSL config for the listen directive The most of the SSL changes will affect only the default server. |
Base Rules | |
Use geo/map modules instead of allow/deny Provides the perfect way to block invalid visitors. |
Base Rules | |
Set global root directory for unmatched locations Specifies the root directory for an undefined locations. |
Base Rules | |
Don't duplicate index directive, use it only in the http block Watch out for duplicating the same rules. |
Base Rules | |
Adjust worker processes You can adjust this value to maximum throughput under high concurrency. |
Performance | |
Make an exact location match to speed up the selection process Exact location matches are often used to speed up the selection process. |
Performance | |
Use limit_conn to improve limiting the download speed Limits NGINX download speed per connection. |
Performance | |
Be careful with trailing slashes in proxy_pass directive Incorrect setting could end up with some strange url. |
Reverse Proxy | |
Use custom headers without X- prefix The use of custom headers with X- prefix is discouraged. |
Reverse Proxy | |
Tweak passive health checks Improve behaviour of the passive health checks. |
Load Balancing | |
Define security policies with security.txt Helps make things easier for companies and security researchers. |
Others | |
Map all the things... Map module provides a more elegant solution for clearly parsing a big list of regexes. |
Base Rules | |
Use custom log formats This is extremely helpful for debugging specific location directives. |
Debugging | |
Use debug mode to track down unexpected behaviour There's probably more detail than you want, but that can sometimes be a lifesaver. |
Debugging | |
Disable daemon, master process, and all workers except one This simplifies the debugging and lets test configurations rapidly. |
Debugging | |
Use core dumps to figure out why NGINX keep crashing Enable core dumps when your NGINX instance receive an unexpected error or when it crashed. |
Debugging | |
Don't disable backends by comments, use down parameter Is a good solution to marks the server as permanently unavailable. |
Load Balancing |
Here you'll find a few of the different things I've worked and which included to this repository. I hope that these extras will be useful to you.
Many of these recipes have been applied to the configuration of my private website.
An example configuration is in configuration examples chapter. It's also based on this version of printable high-res hardening cheatsheets.
Read about SSL Labs grading here (SSL Labs Grading 2018).
Short SSL Labs grades explanation:
A+ is clearly the desired grade, both A and B grades are acceptable and result in adequate commercial security. The B grade, in particular, may be applied to configurations designed to support very wide audiences (for old clients).
I finally got A+ grade and following scores:
- Certificate = 100%
- Protocol Support = 100%
- Key Exchange = 90%
- Cipher Strength = 90%
Look also at the following recommendations. In my opinion, the right configuration of NGINX should give the following SSL Labs scores:
-
Recommended
- A+
- Certificate: 100/100
- Protocol Support: 95/100
- Key Exchange: 90/100
- Cipher Strength: 90/100
-
Perfect but restrictive
- A+
- Certificate: 100/100
- Protocol Support: 100/100
- Key Exchange: 100/100
- Cipher Strength: 100/100
Read about Mozilla Observatory here.
I also got the highest note on the Observatory:
I created two versions of printable posters with hardening cheatsheets (High-Res 5000x8200) based on recipes from this handbook:
For
*.xcf
and
-
A+ with all 100%’s on @ssllabs and 120/100 on @mozilla observatory:
It provides the highest scores of the SSL Labs test. Setup is very restrictive with 4096-bit private key, only TLS 1.2, and also modern strict TLS cipher suites (non 128-bits).
-
A+ on @ssllabs and 120/100 on @mozilla observatory with TLS 1.3 support:
It provides less restrictive setup with 2048-bit private key, TLS 1.3 and 1.2, and also modern strict TLS cipher suites (128/256-bits). The final grade is also in line with the industry standards. Recommend using this configuration.
I created a set of scripts for unattended installation of NGINX from the raw, uncompiled code. It allows you to easily install, create a setup for dependencies (like zlib
or openssl
), and customized with installation parameters.
For more information please see Installing from source - Automatic installation chapter.
I created a simple to use generator for static pages with errors to replace the default error pages that comes with any web server like NGINX.
For more information please see HTTP Static Error Pages Generator.
Authors: Valery Kholodkov
Excel in Nginx quickly by learning to use its most essential features in real-life applications.
- Learn how to set up, configure, and operate an Nginx installation for day-to-day use
- Explore the vast features of Nginx to manage it like a pro, and use them successfully to run your website
- Example-based guide to get the best out of Nginx to reduce resource usage footprint
This short review comes from this book or the store.
Authors: Derek DeJonghe
You’ll find recipes for:
- Traffic management and A/B testing
- Managing programmability and automation with dynamic templating and the NGINX Plus API
- Securing access through encrypted traffic, secure links, HTTP authentication subrequests, and more
- Deploying NGINX to AWS, Azure, and Google cloud-computing services
- Using Docker to deploy containers and microservices
- Debugging and troubleshooting, performance tuning, and practical ops tips
This short review comes from this book or the store.
Authors: Martin Fjordvald, Clement Nedelcu
Harness the power of Nginx to make the most of your infrastructure and serve pages faster than ever.
- Discover possible interactions between Nginx and Apache to get the best of both worlds
- Learn to exploit the features offered by Nginx for your web applications
- Get your hands on the most updated version of Nginx (1.13.2) to support all your web administration requirements
This short review comes from this book or the store.
Authors: Rahul Sharma
Optimize NGINX for high-performance, scalable web applications.
- Configure Nginx for best performance, with configuration examples and explanations
- Step-by-step tutorials for performance testing using open source software
- Tune the TCP stack to make the most of the available infrastructure
This short review comes from this book or the store.
Authors: Dimitri Aivaliotis
Written for experienced systems administrators and engineers, this book teaches you from scratch how to configure Nginx for any situation. Step-by-step instructions and real-world code snippets clarify even the most complex areas.
This short review comes from this book or the store.
Authors: Faisal Memon, Owen Garrett, Michael Pleshakov
Learn in this ebook how to get started with ModSecurity, the world’s most widely deployed web application firewall (WAF), now available for NGINX and NGINX Plus.
This short review comes from this book or the store.
Authors: Faisal Memon
This ebook provides step-by-step instructions on replacing Cisco ACE with NGINX and off-the-shelf servers. NGINX helps you cut costs and modernize.
In this ebook you will learn:
- How to migrate Cisco ACE configuration to NGINX, with detailed examples
- Why you should go with a software load balancer, and not hardware
This short review comes from this book or the store.
:black_small_square: Nginx Project
:black_small_square: Nginx Documentation
:black_small_square: Nginx Wiki
:black_small_square: Nginx Admin's Guide
:black_small_square: Nginx Pitfalls and Common Mistakes
:black_small_square: Development guide
:black_small_square: Nginx Forum
:black_small_square: Nginx Mailing List
:black_small_square: Nginx Read-only Mirror
:black_small_square: NGINX-Demos
:black_small_square: OpenResty
:black_small_square: The Tengine Web Server
:black_small_square: NGINX vs. Apache (Pro/Con Review, Uses, & Hosting for Each)
:black_small_square: Web cache server performance benchmark: nuster vs nginx vs varnish vs squid
:black_small_square: agentzh's Nginx Tutorials
:black_small_square: Introduction to nginx.conf scripting
:black_small_square: Nginx discovery journey
:black_small_square: Nginx Guts
:black_small_square: Nginx Cheatsheet
:black_small_square: Nginx Tutorials, Linux Sysadmin Configuration & Optimizing Tips and Tricks
:black_small_square: Nginx boilerplate configs
:black_small_square: Awesome Nginx configuration template
:black_small_square: Nginx Quick Reference
:black_small_square: A collection of resources covering Nginx and more
:black_small_square: A collection of useful Nginx configuration snippets
:black_small_square: Nginx Tuning For Best Performance by Denji
:black_small_square: Nginx Optimization: understanding sendfile, tcp_nodelay and tcp_nopush
:black_small_square: TLS has exactly one performance problem: it is not used widely enough
:black_small_square: SSL/TLS Deployment Best Practices
:black_small_square: SSL Server Rating Guide
:black_small_square: How to Build a Tough NGINX Server in 15 Steps
:black_small_square: Top 25 Nginx Web Server Best Security Practices
:black_small_square: Nginx Secure Web Server
:black_small_square: Strong ciphers for Apache, Nginx, Lighttpd and more
:black_small_square: Strong SSL Security on Nginx
:black_small_square: Enable cross-origin resource sharing (CORS)
:black_small_square: NAXSI - WAF for Nginx
:black_small_square: ModSecurity for Nginx
:black_small_square: Transport Layer Protection Cheat Sheet
:black_small_square: Security/Server Side TLS
:black_small_square: Browser support tables for modern web technologies
:black_small_square: NGINX: Basics and Best Practices
:black_small_square: NGINX Installation and Tuning
:black_small_square: Nginx Internals (by Joshua Zhu)
:black_small_square: Nginx internals (by Liqiang Xu)
:black_small_square: How to secure your web applications with NGINX
:black_small_square: Tuning TCP and NGINX on EC2
:black_small_square: Extending functionality in nginx, with modules!
:black_small_square: Nginx - Tips and Tricks.
:black_small_square: Nginx Scripting - Extending Nginx Functionalities with Lua
:black_small_square: How to handle over 1,200,000 HTTPS Reqs/Min
:black_small_square: Using ngx_lua / lua-nginx-module in pixiv
:black_small_square: NGINX Conf 2014
:black_small_square: NGINX Conf 2015
:black_small_square: NGINX Conf 2016
:black_small_square: NGINX Conf 2017
:black_small_square: NGINX Conf 2018 | Deep Dive Track
:black_small_square: NGINX Conf 2018 | Keynotes and Sessions
:black_small_square: NGINX Rate Limit, Burst and nodelay sandbox
:black_small_square: Nginx config generator on steroids
:black_small_square: Mozilla SSL Configuration Generator
:black_small_square: nginx-config-builder
:black_small_square: gixy - is a tool to analyze Nginx configuration to prevent security misconfiguration and automate flaw detection.
:black_small_square: nginx-config-formatter - Nginx config file formatter/beautifier written in Python.
:black_small_square: nginxbeautifier - format and beautify Nginx config files.
:black_small_square: nginx-minify-conf - creates a minified version of a Nginx configuration.
:black_small_square: GoAccess - is a fast, terminal-based log analyzer (quickly analyze and view web server statistics in real time).
:black_small_square: Graylog - is a leading centralized log management for capturing, storing, and enabling real-time analysis.
:black_small_square: Logstash - is an open source, server-side data processing pipeline.
:black_small_square: ngxtop - parses your Nginx access log and outputs useful, top-like, metrics of your Nginx server.
:black_small_square: Nginx-builder - is a tool for building deb or rpm package NGINX from the source code.
:black_small_square: ab - is a single-threaded command line tool for measuring the performance of HTTP web servers.
:black_small_square: siege - is an http load testing and benchmarking utility.
:black_small_square: wrk - is a modern HTTP benchmarking tool capable of generating significant load.
:black_small_square: wrk2 - is a constant throughput, correct latency recording variant of wrk.
:black_small_square: bombardier - is a HTTP(S) benchmarking tool.
:black_small_square: gobench - is a HTTP/HTTPS load testing and benchmarking tool.
:black_small_square: hey - is a HTTP load generator, ApacheBench (ab) replacement, formerly known as rakyll/boom.
:black_small_square: boom - is a script you can use to quickly smoke-test your web app deployment.
:black_small_square: httperf - the httperf HTTP load generator.
:black_small_square: JMeter™ - is designed to load test functional behavior and measure performance.
:black_small_square: Gatling - is a powerful open-source load and performance testing tool for web applications.
:black_small_square: locust - is an easy-to-use, distributed, user load testing tool.
:black_small_square: slowloris - low bandwidth DoS tool. Slowloris rewrite in Python.
:black_small_square: slowhttptest - application layer DoS attack simulator.
:black_small_square: GoldenEye - GoldenEye Layer 7 (KeepAlive+NoCache) DoS test tool.
:black_small_square: strace - is a diagnostic, debugging and instructional userspace utility (linux syscall tracer) for Linux.
:black_small_square: GDB - allows you to see what is going on `inside' another program while it executes.
:black_small_square: SystemTap - provides infrastructure to simplify the gathering of information about the running Linux system.
:black_small_square: stapxx - simple macro language extensions to SystemTap.
:black_small_square: htrace.sh - is a simple Swiss Army knife for http/https troubleshooting and profiling.
:black_small_square: Programming in Lua (first edition)
:black_small_square: Scripting Nginx with Lua
:black_small_square: Emiller’s Guide To Nginx Module Development
:black_small_square: Emiller’s Advanced Topics In Nginx Module Development
:black_small_square: NGINX Tutorial: Developing Modules
:black_small_square: An Introduction To OpenResty (nginx + lua) - Part 1
:black_small_square: An Introduction To OpenResty - Part 2 - Concepts
:black_small_square: An Introduction To OpenResty - Part 3
:black_small_square: OpenResty (Nginx) with dynamically generated certificates
:black_small_square: Programming OpenResty
:black_small_square: SSL Server Test by SSL Labs
:black_small_square: SSL/TLS Capabilities of Your Browser
:black_small_square: Test SSL/TLS (PCI DSS, HIPAA and NIST)
:black_small_square: SSL analyzer and certificate checker
:black_small_square: Test your TLS server configuration (e.g. ciphers)
:black_small_square: Scan your website for non-secure content
:black_small_square: Public Diffie-Hellman Parameter Service/Tool
:black_small_square: Analyse the HTTP response headers by Security Headers
:black_small_square: Analyze your website by Mozilla Observatory
:black_small_square: CAA Record Helper
:black_small_square: Linting tool that will help you with your site's accessibility, speed, security and more
:black_small_square: Service to scan and analyse websites
:black_small_square: Tool from above to either encode or decode a string of text
:black_small_square: Online translator for search queries on log data
:black_small_square: Online regex tester and debugger: PHP, PCRE, Python, Golang and JavaScript
:black_small_square: Online tool to learn, build, & test Regular Expressions
:black_small_square: Online Regex Tester & Debugger
:black_small_square: nginx-regex-tester
:black_small_square: A web app for encryption, encoding, compression and data analysis
:black_small_square: Nginx location match tester
:black_small_square: Nginx location match visible
:black_small_square: Web technology for developers
:black_small_square: OWASP Cheat Sheet Series
:black_small_square: Mozilla Web Security
:black_small_square: Application Security Wiki
:black_small_square: OWASP ASVS 4.0
:black_small_square: Transport Layer Security (TLS) Parameters
:black_small_square: Security/Server Side TLS by Mozilla
:black_small_square: TLS Redirection (and Virtual Host Confusion)
:black_small_square: TLS Security 6: Examples of TLS Vulnerabilities and Attacks
:black_small_square: Guidelines for Setting Security Headers
:black_small_square: Secure your web application with these HTTP headers
:black_small_square: Security HTTP Headers
:black_small_square: Analysis of various reverse proxies, cache proxies, load balancers, etc.
:black_small_square: Regular-Expressions
:black_small_square: HTTPS on Stack Overflow: The End of a Long Road
:black_small_square: The Architecture of Open Source Applications - Nginx
:black_small_square: BBC Digital Media Distribution: How we improved throughput by 4x
:black_small_square: The C10K problem by Dan Kegel
:black_small_square: The Secret To 10 Million Concurrent Connections
:black_small_square: High Performance Browser Networking
:black_small_square: The System Design Primer
:black_small_square: awesome-scalability
:black_small_square: Web Architecture 101
:black_small_square: Learn where some of the network sysctl variables fit into the Linux/Kernel network flow
:black_small_square: jemalloc vs tcmalloc vs dlmalloc
:black_small_square: GLB: GitHub’s open source load balancer
Go to the Table of Contents or read the next chapters:
- HTTP Basics
Something about HTTP.
- SSL/TLS Basics
Something about SSL/TLS.
- NGINX Basics
Explanation of the NGINX mechanisms.
- Helpers
One-liners, commands, utilities for building NGINX, and more
- Base Rules (14)
The basic set of rules to keep NGINX in good condition.
- Debugging (4)
A few things for troubleshooting configuration problems.
- Performance (11)
Many methods to make sure the NGINX as fast as possible.
- Hardening (28)
Hardening approaches and security standards.
- Reverse Proxy (7)
A few rules about the NGINX proxy server.
- Load Balancing (2)
You may improve of some rules about the NGINX working as a load balancer.
- Others (2)
Something about other interesting rules.
- Configuration Examples
Here are some configuration examples.