NGINX

nginx(8) is a web and proxy server written for modern workloads (chiefly multi-threading).

Installation

Most Linux and BSD distributions offer a nginx package.

On Ubuntu, to ensure all security patches have been applied, use the upstream PPA.

sudo add-apt-repository ppa:nginx/stable
sudo apt update
sudo apt install nginx

Configuration

To check the configuration of nginx(8), run...

nginx -t

Server blocks

Servers listen on one or more addresses and ports, specified on the listen directive. If the address is left off, nginx(8) listens on all addresses for that server. Servers can share addresses and/or ports.

If nginx(8) receives a request, it is routed between the listening servers based on the domain name. Each server is meant to represent a single web domain, which should be specified on the server_name directive. If a server needs to respond as any domain, enter _ as the name.

If no server name matches, the request is routed to the default server, which is marked by the default_server option on the listen directive. nginx(8) requires one (and only one) server be marked as default.

Typically, the default server is configured with a server name of _ and returns error 444 to all requests.

server {
  listen 80 default_server;
  server_name _;
  return 444;
}

server {
  listen 80;
  server_name example.com;

  root /var/www;

  location / {
    try_files $uri $uri/ /index.html;
  }
}

Locations

Generally, locations map to the local file system. The try_files directive checks if a file exists, and will return an error otherwise.

root /var/www;

location / {
  try_files $uri $uri/ /index.html;
}

location /static/ {
  root /usr/local/share/myapp;
}

location /robots.txt {
  root /var/www;
}

These prefix locations can be nested, and nginx(8) will serve the location with the longest matching prefix.

As noted below, regular expression locations will take priority over prefix locations. Try location ^~ /static to override this.

Regular Expression Locations

Regular expression locations are checked in the order they appear in the server block, and the first match is served.

location ~* /images/ {
  # This operator is case sensitive
}

location ~* /Images/ {
  # This operator is case insensitive
}

These locations take priority over prefix locations, except for those using the ^~ operator.

Exact Locations

= is a short circuit operator. If a request matches an exact location exactly, nginx(8) immediately serves it. This is mainly useful for the root index.

location = / {
  try_files $uri $uri/ /index.html;
}

Named Locations

Named locations, which are identified by the @ prefix, do not map to directories. Named locations cannot be nested and cannot contain nested locations.

These locations are used for routing.

try_files $uri @uwsgi;
location @uwsgi {
  include /etc/nginx/uwsgi_params;
  uwsgi_pass unix:///var/www/my-wsgi-app/my-wsgi-app.sock;
}

Encryption

See here for details.

Authentication

Restricting Access

To deny requests based on the URI, use a location block.

location ~ ^\.ht {
    return 444;
}

To deny requests based on the HTTP method, use a conditional statement.

if ($request_method !~ ^(GET|HEAD|POST)$ ) {
    return 444;
}

In all circumstances, conditional statements should be the last resort technique. They can be less than intuitive and difficult to debug.

Restricting Referrers

It is sometimes desirable to block referrals.

valid_referers none blocked server_names
               ~example\.com;
if ($invalid_referer) {
    return 403;
}

none matching missing referers ("-"), while blocked matches referers that have been deleted by a firewall.

Literal server names are given with a leading or trailing asterisk (*). Regular expressions are given with a leading tilde (~).

FastCGI

See here for details.

UWSGI

See here for details.

CategoryRicottone