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

Containers

Docker container images are also available for the last two versions. The image is available from DockerHub as docker.io/library/nginx (or simply nginx when using docker(1) specifically).

Try:

docker run --detach --name my-nginx \
  --mount type=bind,src=/path/to/web/root,dst=/usr/share/nginx/html,readonly \
  --publish 127.0.0.1:8080:80 \
  nginx:latest

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 then reroutes based on the syntax. In the below example, if $uri does not exist, the request is routed to the @uwsgi location.

try_files $uri @uwsgi;

location / {
  root /var/www;
}

location @uwsgi {
  include uwsgi_params;
  uwsgi_pass unix:///run/myapp.sock;
}

location ~ .(png|gif|jpe?g)$ {
  root /usr/local/share/myapp/static;
}

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

Configuration Syntax

• Location

• Http

• Server

Proxying

• FastCGI

• Uwsgi

Advanced Configuration

• Authentication

• Compression

• Encryption

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 (~).

See also

nginx(8)

CategoryRicottone