paulgorman.org/technical

nginx

(January 2017)

Nginx is a web server.

Configuration

The base config file for nginx is /etc/nginx/nginx.conf. However, many linux distributions split the configuration into multiple files, linked by includes from the main file.

On Alpine:

# Includes virtual hosts configs.
include /etc/nginx/conf.d/*.conf;

On Debian:

# Virtual Host Configs
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;

Comments start with a pound #.

The nginx configuration is logically tree-like in structure, with branches/scopes delimited by curly braces {}. Nginx calls each branch/scope a context. Generally, a child context inherits configuration from its parent; configuration options flow from the trunk of the tree out to its branches. A child context can override the configuration default inherited from its parent.

Each context contains configuration directives. Not all directives are valid in all contexts.

The nginx.conf file contains an implicit global/main/root context (although it’s not wrapped in curly braces). Directives in the global context may include:

user www-data;
worker_processes auto;
pid /run/nginx.pid;
pcre_jit on;
include /etc/nginx/modules-enabled/*.conf;

The ngingx.conf global context often contain only two immedate child contexts: “events” and “http”. The events context contains connection-oriented directives:

events {
	# Maximum simultaneous connections opened by a worker process:
	worker_connections 768;
}

The bulk of the configuration directives reside in the “http” context and its children. It sets some default directives, then includes a “server” context for each virtual server.

http {
	include /etc/nginx/mime.types;
	default_type application/octet-stream;
	sendfile on;
	tcp_nopush on;
	tcp_nodelay on;
	keepalive_timeout 65;
	types_hash_max_size 2048;
	server_tokens off;
	ssl_protocols TLSv1 TLSv1.1 TLSv1.2; # Dropping SSLv3, ref: POODLE
	ssl_prefer_server_ciphers on;
	# Virtual servers:
	include /etc/nginx/conf.d/*.conf;
}

Those included /etc/nginx/conf.d/*.conf files likely contain a “server” context.

server {
	listen 80 default_server;
	listen [::]:80 default_server;
	root /var/www/html;
	index index.html index.php index.htm;
	server_name _;
	location / {
			# First attempt to serve request as file, then
			# as directory, then fall back to displaying a 404.
			try_files $uri $uri/ =404;
	}
	location ~ \.php$ {
		include snippets/fastcgi-php.conf;
		fastcgi_pass unix:/var/run/php5-fpm.sock;
	}
	location /cgi-bin/ {
		include /etc/nginx/fastcgi.conf;
		gzip off;
		fastcgi_pass  unix:/var/run/fcgiwrap.sock;
	}
}

Note that both the fastcgi process and nginx need read and write permission to the socket file.

Location Blocks

Each server block may have multiple location blocks. For each request, Nginx chooses between location blocks based on the best match.

location optional_modifier location_pattern {
	...
}

These are the possible optional modifiers to the location match:

How does Nginx choose between location blocks?

Pitfalls and Common Mistakes