# 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:

- none: Nginx treats the pattern as a prefix. Any request with a URI that begins like the pattern matches the location. "/site" matches "/site" or "/site1" or "/site/sub".
- `=`: The request hits the location if the URI is an exact match for the pattern (e.g. "/site" matches only "/site", not "/site1" nor "/site/sub").
- `~`: Nginx treats the location pattern as a case-sensitive regular expression.
- `~*`: Nginx treats the location pattern as a case-insensitive regular expression.
- `^~`: If this block is selected as the best non-regular expression match, regular expression matching will not take place.

How does Nginx choose between location blocks?


## Pitfalls and Common Mistakes ##

## Links ##

- https://www.nginx.com/resources/wiki/start/
- http://nginx.org/en/docs/beginners_guide.html
- https://www.digitalocean.com/community/tutorials/understanding-the-nginx-configuration-file-structure-and-configuration-contexts
- https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/
- https://www.nginx.com/resources/wiki/start/topics/examples/fcgiwrap/
- https://www.digitalocean.com/community/tutorials/understanding-nginx-server-and-location-block-selection-algorithms