NGINX: Basics & Best Practices - EMEA Broadcast

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

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

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

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

NGINX Mainline vs. Stable

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

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

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

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

Verifying Installation

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

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)

Agenda
• Monitoring and Logging

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

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

Basic SSL Configuration
server {
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl default_server;
ssl_certificate cert.crt
ssl_certificate_key cert.key
ssl_ciphers HIGH;
location / {
}
}
• 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 {
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2 default_server;
ssl_ciphers HIGH;
location / {
}
}
$ openssl ciphers
ECDHE-RSA-AES256-GCM-SHA384:E
CDHE-ECDSA-AES256-GCM-SHA384:
ECDHE-RSA-AES256-SHA384:ECDH…

Basic Reverse Proxy Configuration
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

Basic Load Balancing Configuration
upstream my_upstream {
server server1.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)

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_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

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.

HTTP/1.1 Keepalive to Upstreams
keepalive 32;
}
server {
location / {
proxy_http_version 1.1;
proxy_set_header Connection "";
}
}
• 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

SSL Session Caching
server {
listen 443 ssl default_server;
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

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_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

Load Balancing with Health Checks Configuration
zone my_upstream 64k;
server server1.example.com slow_start=30s;
server server2.example.com slow_start=30s;
}
server {
location / {
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

Agenda
• Monitoring and logging

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

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
zone my_upstream 64k;
}
server {
status_zone my_virtual_server;
location / {
}
}
$ curl https://www.nginx.com/resource/conf/status.conf >
/etc/nginx/conf.d/status.conf

● 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

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

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 {
location / {
}
access_log /var/log/nginx/example.log simple;
error_log /var/log/nginx/example_error.log debug;
}

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

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/

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

NGINX: Basics & Best Practices - EMEA Broadcast

In this document