This document provides an overview of installing and configuring the NGINX web server. It discusses installing NGINX from official repositories or from source on Linux systems like Ubuntu, Debian, CentOS and Red Hat. It also covers verifying the installation, basic configurations for web serving, reverse proxying, load balancing and caching. The document discusses modifications that can be made to the main nginx.conf file to improve performance and reliability. It also covers monitoring NGINX using status pages and logs, and summarizes key documentation resources.

1. NGINX: Basics and
Best Practices
Liam Crilly
Director of Product Management
liam@nginx.com

2. Internet
Web Server
Serve content from disk
Application Gateway
FastCGI, uWSGI, Passenger…
Reverse Proxy
Caching, load balancing…
HTTP Traffic
NGINX Overview

3. MORE INFORMATION AT NGINX.COM
Agenda
• Installing NGINX and NGINX Plus
• Basic Configurations
• Improving Performance and Reliability
• Logging and Monitoring

4. MORE INFORMATION AT NGINX.COM
NGINX Installation Options
• Official NGINX repo
• Mainline (recommended) – Actively developed; new minor releases
made every 4-6 weeks with new features and enhancements.
• Stable − Updated only when critical issues or security vulnerabilities
need to be fixed.
• OS vendor and other third-party repos
• Not as frequently updated; Debian Jessie has NGINX 1.6.2 (Sep-
2014)
• Typically built off NGINX Stable branch

5. MORE INFORMATION AT NGINX.COM
NGINX Mainline vs. Stable

6. MORE INFORMATION AT NGINX.COM
NGINX Installation: Debian/Ubuntu
deb http://nginx.org/packages/mainline/OS/ CODENAME nginx
deb-src http://nginx.org/packages/mainline/OS/ CODENAME nginx
Create /etc/apt/sources.list.d/nginx.list with the following contents:
• OS – ubuntu or debian depending on your distro
• CODENAME –
- With debian: wheezy, jessie, or stretch (7.0, 8.0, 9.0)
- With ubuntu: precise, trusty, xenial, or yakkety (12.04, 14.04, 16.04,
16.10)
# wget http://nginx.org/keys/nginx_signing.key
# apt-key add nginx_signing.key
# apt-get update
# apt-get install nginx

7. MORE INFORMATION AT NGINX.COM
NGINX Installation: CentOS/Red Hat
[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/mainline/OS/OSRELEASE/$basearch/
gpgcheck=0
enabled=1
Create /etc/yum.repos.d/nginx.repo with the following contents:
• OS – centos or rhel depending on your distro
• OSRELEASE – 6 or 7 for 6.x or 7.x versions, respectively
# yum install nginx
# systemctl enable nginx
# systemctl start nginx
# firewall-cmd --zone=public --add-port=80/tcp –permanent
# firewall-cmd --reload

8. MORE INFORMATION AT NGINX.COM
NGINX Plus Installation
• Visit cs.nginx.com/repo_setup
• Select OS from drop-down list
• Instructions similar to OSS installation
• Mostly just using different repo and installing
client certificate

9. MORE INFORMATION AT NGINX.COM
Verifying Installation
$ nginx -v
nginx version: nginx/1.13.3
$ ps -ef | grep nginx
root 1088 1 0 19:59 ? 00:00:00 nginx: master process …
nginx 1092 1088 0 19:59 ? 00:00:00 nginx: worker process

10. MORE INFORMATION AT NGINX.COM
Verifying Installation

11. MORE INFORMATION AT NGINX.COM
Key NGINX Commands
nginx -h Shows all command line options
nginx -t Configuration syntax check
nginx -T Displays full, concatenated configuration
nginx -V Shows version and build details
nginx –s reload Gracefully reload NGINX processes
$ sudo nginx –t && sudo nginx –s reload
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

12. MORE INFORMATION AT NGINX.COM
NGINX Installation Misc
• For open source NGINX:
• http://nginx.org/en/linux_packages.html (pre-built packages & modules)
• http://nginx.org/en/download.html (sources)
• For NGINX Plus:
• https://www.nginx.com/products/technical-specs/ (OS and modules)
• https://cs.nginx.com/repo_setup (installation instructions)

13. MORE INFORMATION AT NGINX.COM
Agenda
• Installing NGINX and NGINX Plus
• Basic Configurations
• Improving Performance and Reliability
• Monitoring and Logging

14. MORE INFORMATION AT NGINX.COM
Key Files and Directories
• /etc/nginx − Parent directory for all NGINX configuration
• /etc/nginx/nginx.conf − Top-level NGINX configuration, not modified often
• /etc/nginx/conf.d/default.conf − Configuration for “welcome to nginx” page
• /etc/nginx/conf.d/*.conf − Configuration for virtual servers and upstreams;
for example, www.example.com.conf

15. MORE INFORMATION AT NGINX.COM
Basic Web Server Configuration
server {
listen 80 default_server;
server_name www.example.com;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
}
}
Root location (/) specifies that:
www.example.com/ maps to /usr/share/nginx/html/index.html (then index.htm)
www.example.com/i/file.txt maps to /usr/share/nginx/html/i/file.txt
• server defines the context for a virtual server
• listen specifies IP address/port that NGINX
listens on; if no IP address (as here), NGINX
binds to all IP addresses on system
• default_server specifies to use this server if
hostname is not known
• server_name specifies hostname of virtual
server

16. MORE INFORMATION AT NGINX.COM
Basic SSL Configuration
server {
listen 80 default_server;
server_name www.example.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl default_server;
server_name www.example.com;
ssl_certificate cert.crt
ssl_certificate_key cert.key
ssl_ciphers HIGH;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
}
}
• Force all traffic to SSL
• Good for SEO
• Use Let’s Encrypt to get free SSL
certificates
• Enable HTTP/2 with additional listen
parameter (requires OpenSSL
≥1.0.2)
server {
listen 80 default_server;
server_name www.example.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2 default_server;
server_name www.example.com;
ssl_certificate cert.crt
ssl_certificate_key cert.key
ssl_ciphers HIGH;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
}
}
$ openssl ciphers
ECDHE-RSA-AES256-GCM-SHA384:E
CDHE-ECDSA-AES256-GCM-SHA384:
ECDHE-RSA-AES256-SHA384:ECDH…

17. MORE INFORMATION AT NGINX.COM
Basic Reverse Proxy Configuration
server {
listen 80 default_server;
location ~ [^/].php(/|$) {
fastcgi_split_path_info ^(.+?.php)(/.*)$;
#fastcgi_pass 127.0.0.1:9000;
fastcgi_pass unix:/var/run/php7.0-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
}
}
• Requires PHP FPM:
apt-get install –y php7.0-fpm
• Can also use PHP 5
• Similar directives available for SCGI
and uwsgi
• Additional PHP FPM configuration may
be required

18. MORE INFORMATION AT NGINX.COM
Basic Load Balancing Configuration
upstream my_upstream {
server server1.example.com;
server server2.example.com;
least_conn;
}
server {
location / {
proxy_pass http://my_upstream;
proxy_set_header Host $host;
}
}
• Default load balancing algorithm is Round
Robin
• least_conn selects server with fewest active
connections
• By default NGINX rewrites Host header to
name and port of proxied server
• proxy_set_header overrides and passes
through original client Host header
• least_time factors in connection count and
server response time (available in NGINX
Plus only)

19. MORE INFORMATION AT NGINX.COM
Basic Caching Configuration
proxy_cache_path /path/to/cache levels=1:2
keys_zone=my_cache:10m max_size=10g
inactive=60m use_temp_path=off;
server {
location / {
proxy_cache my_cache;
#proxy_cache_valid 5m;
proxy_set_header Host $host;
proxy_pass http://my_upstream;
}
}
• proxy_cache_path defines the
disk layout, size and location, and
other parameters of the cache
• proxy_cache enables caching for
this context
• proxy_cache_valid for when
upstream returns no Cache-
Control header

20. MORE INFORMATION AT NGINX.COM
Agenda
• Installing NGINX and NGINX Plus
• Basic Configurations
• Improving Performance and Reliability
• Monitoring and Logging

21. MORE INFORMATION AT NGINX.COM
Modifications to Main nginx.conf
user nginx;
worker_processes auto;
# ...
http {
# ...
keepalive_timeout 300s;
keepalive_requests 100000;
}
• Set in main nginx.conf file.
• Default value for worker_processes varies by
system and installation source.
• auto means to create one worker process per core.
This is recommended for most deployments.
• keepalive_timeout controls how long to keep idle
connections to clients open (default: 75 seconds).
• keeplive_requests limits the number of requests
per connection before it’s closed (default: 100).
• keepalive_* directives can be overridden per virtual
server and per location.

22. MORE INFORMATION AT NGINX.COM
HTTP/1.1 Keepalive to Upstreams
upstream my_upstream {
server server1.example.com;
keepalive 32;
}
server {
location / {
proxy_set_header Host $host;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://my_upstream;
}
}
• keepalive enables TCP connection cache
and sets max idle connections per worker
(does not limit the number of upstream
connections).
• By default NGINX uses HTTP/1.0 with
Connection: Close
• proxy_http_version upgrades connection
to HTTP/1.1
• proxy_set_header enables keepalive by
clearing Connection: Close HTTP header

23. MORE INFORMATION AT NGINX.COM
SSL Session Caching
server {
listen 443 ssl default_server;
server_name www.example.com;
ssl_certificate cert.crt
ssl_certificate_key cert.key
ssl_ciphers HIGH;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
}
• Improves SSL/TLS performance
• 1 MB session cache can store about 4,000
sessions
• Cache shared across all NGINX workers

24. MORE INFORMATION AT NGINX.COM
Improved Caching Configuration
proxy_cache_path /path/to/cache levels=1:2
keys_zone=my_cache:10m max_size=10g
inactive=60m use_temp_path=off;
server {
location / {
proxy_cache my_cache;
proxy_cache_revalidate on;
proxy_cache_background_update on;
proxy_cache_use_stale error updating;
proxy_set_header Host $host;
proxy_pass http://my_upstream;
}
}
• proxy_cache_revalidate instructs
NGINX to use
If-Modified-Since when
refreshing cache
• proxy_cache_background_update
instructs NGINX to revalidate
asynchronously, without delaying the
client
• proxy_cache_use_stale instructs
NGINX to send expired cache entries
under certain circumstances and will
honor Stale-while-revalidate
and Stale-if-error parameters

25. MORE INFORMATION AT NGINX.COM
Load Balancing with Health Checks Configuration
upstream my_upstream {
zone my_upstream 64k;
server server1.example.com slow_start=30s;
server server2.example.com slow_start=30s;
}
server {
location / {
proxy_set_header Host $host;
proxy_pass http://my_upstream;
health_check uri=/health mandatory;
}
}
• Polls /health every 5 seconds
• If response is not 2xx or 3xx, server
is marked as failed
• Traffic to recovered/new servers
slowly ramps up traffic over 30
seconds
• Many additional configurable
parameters
• Exclusive to NGINX Plus

26. MORE INFORMATION AT NGINX.COM
Agenda
• Installing NGINX and NGINX Plus
• Basic Configurations
• Improving Performance and Reliability
• Monitoring and logging

27. MORE INFORMATION AT NGINX.COM
NGINX Stub Status Module
server {
location /basic_status {
stub_status;
}
}
• Provides aggregated NGINX
statistics
• Restrict access so it’s not publicly
visible
$ curl http://www.example.com/basic_status
Active connections: 1
server accepts handled requests
7 7 7
Reading: 0 Writing: 1 Waiting: 0

28. MORE INFORMATION AT NGINX.COM
NGINX Plus Extended Status Module
• Provides detailed NGINX Plus
statistics
• Over 40 additional metrics
• Monitoring GUI also available; see
demo.nginx.com
• Exclusive to NGINX Plus
upstream my_upstream {
server server1.example.com;
zone my_upstream 64k;
}
server {
status_zone my_virtual_server;
location / {
proxy_set_header Host $host;
proxy_pass http://my_upstream;
}
}
$ curl https://www.nginx.com/resource/conf/status.conf >
/etc/nginx/conf.d/status.conf

29. MORE INFORMATION AT NGINX.COM
● Over 40 additional metrics compared to open source NGINX
● Per virtual server and per backend server statistics
● JSON output to export to your favorite monitoring tool
"nginx_build": "nginx-plus-r12-p2",
"nginx_version": "1.11.10",
"pid": 98240,
"ppid": 50622,
"processes": {
"respawned": 0
},
"requests": {
"current": 1,
"total": 9915307
},
"server_zones": {
"hg.nginx.org": {
"discarded": 9150,
"processing": 0,
"received": 146131844,
"requests": 597471,
"responses": {
"1xx": 0,
"2xx": 561986,
"3xx": 12839,
"4xx": 7081,
"5xx": 6415,
"total": 588321
},
"sent": 14036626711
},
NGINX Plus Dashboard

30. MORE INFORMATION AT NGINX.COM
NGINX Access Logs
192.168.179.1 - - [15/May/2017:16:36:25 -0700] "GET / HTTP/1.1" 200 612 "-" "Mozilla/5.0
(Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/58.0.3029.110 Safari/537.36" "-"
192.168.179.1 - - [15/May/2017:16:36:26 -0700] "GET /favicon.ico HTTP/1.1" 404 571
"http://fmemon-redhat.local/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36" "-"
192.168.179.1 - - [15/May/2017:16:36:31 -0700] "GET /basic_status HTTP/1.1" 200 100 "-"
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/58.0.3029.110 Safari/537.36" "-"
• Enabled by default. Can be disabled with the access_log off directive.
• By default lists client IP address, date, request , referrer, user agent, etc. Can add
additional NGINX variables, e.g. timing; see nginx.org/en/docs/varindex.html.
• Log format configurable with the log_format directive

31. MORE INFORMATION AT NGINX.COM
Default Log Files
• /var/log/nginx/access.log − Details about requests and responses
• /var/log/nginx/error.log − Details about NGINX errors
log_format simple escape=json
'{"timestamp":"$time_iso8601","client":"$remote_addr","uri":"$uri","status":"$status"}';
server {
listen 80 default_server;
server_name www.example.com;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
}
access_log /var/log/nginx/example.log simple;
error_log /var/log/nginx/example_error.log debug;
}

32. MORE INFORMATION AT NGINX.COM
Summary
• We recommend using the NGINX mainline branch for most deployments
• Put all configuration in separate files in /etc/nginx/conf.d
• Forcing all traffic to SSL improves security and improves search rankings
• Use keepalive connections improve performance by reusing TCP connections
• SSL session caching and HTTP/2 improve SSL performance
• NGINX status module and logging capability provide visibility
Try NGINX Plus for free at nginx.com/free-trial-request

33. MORE INFORMATION AT NGINX.COM
Documentation Resources
• Admin Guide and Tutorials
http://docs.nginx.com/
• Module and directive reference
http://www.nginx.org/en/docs
• Shortcut to specific directive documentation
http://nginx.org/r/directive_name
• Technical blogs and how-to guides
https://www.nginx.com/blog/

34. Q&A

35. MORE INFORMATION AT NGINX.COM
Upcoming Webinars
• Rate Limiting with NGINX and NGINX Plus (July 26, 2017, 10:00 AM PDT)
• Introduction to (Micro)Service Meshes – O’Reilly Webinar (July 27, 2017, 11:00 AM CEST
)
• Performance Tuning and Benchmarking Best Practices (August 23, 11:00 AM CEST)
Register at nginx.com/webinars