Table of Contents

• Beginner's Guide
  • Processes
  • Directives
• Reference
  • core
  • http
  • proxy
  • rewrite
• Details
  • site-enabled, site-available
• Use Cases
  • Reverse Proxy with preserving request host
  • Server Block Examples
• Links

Beginner's Guide

$ nginx -s stop   # fast shutdown
$ nginx -s quit   # graceful shutdown
$ nginx -s reload # reloading the configuration file
$ nginx -s reopen # reopening the log files

Processes

• one master process and several worker processes
• master process reads and evaluates configuration, and maintain worker processes.

Directives

• simple: name and parameters, separated by spaces, ends with ;
• block: Instead of the semicolon, it ends with a block surrounded by {}
• A block surrounding directives is called a context
• Top level context is called the main context
• # to comment a line

Reference

core

events

• Where directives relating connection processing are placed

#+BEGIN_EXAMPLE
  events {
      use kqueue;
      worker_connections 2048;
  }

include

• Directives in files are inlcuded in the current context

include mime.types;
include vhosts/*.conf;

worker_processes

• Setting it to the number of available CPU cores would be a good start
• The value auto will try to autodetect it

worker_processes auto;

http

location

• The matching is performed against a normalized URI,
• normalized URI
  • Decoding the text encoded in the “%XX” form
  • resolving references to relative path components “.” and “..”
  • possible compression of two or more adjacent slashes into a single slash.
• If there exists exact match(=) its configuration used
• Pick the longest prefix match
• Regex checked, in order of appearance
  1. first regex match configuration used
  2. no regex match, the longest prefix match used.

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

# '^~' modifier skips regex check
location ^~ /images/ {
    [ configuration D ]
}

# '~*' modifier for regex case insensitive match
# '~' for case sensitive
location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

/                        -> A
/index.html              -> B
/documents/document.html -> C
/images/1.gif            -> D
/documents/1.jpg         -> E

types

• Maps file name extensions to MIME types of responses

types {
    text/html  html;
    image/gif  gif;
    image/jpeg jpg;
}

proxy

proxy_pass

If the proxy_pass directive is specified with a URI, then when a request is passed to the server, the part of a normalized request URI matching the location is replaced by a URI specified in the directive:

location /name/ {
    proxy_pass http://127.0.0.1/remote/;
}

/name will be replaced with /remote

If proxy_pass is specified without a URI, the request URI is passed to the server in the same form as sent by a client when the original request is processed, or the full normalized request URI is passed when processing the changed URI:

location /name/ {
    rewrite    /name/([^/]+) /users?name=$1 break;
    proxy_pass http://127.0.0.1;
}

In this case, the URI specified in the directive is ignored and the full changed request URI is passed to the server.

proxy_redirect

• Sets the text that should be changed in the Location and Refresh header fields of a proxied server response

# will rewrite this string to “Location: http://frontend/one/some/uri/”.
proxy_redirect http://localhost:8000/two/ http://frontend/one/;

proxy_hideheader

• By default, nginx does not pass the header fields Date, Server, X-Pad, and X-Accel-... from the response of a proxied server to a client.
• The proxy_hideheader directive sets additional fields that will not be passed
• proxy_passheader for the opposite

rewrite

rewrite

location  /foo {
  rewrite /foo(.*) /$1  break;
  proxy_pass         http://localhost:3200;
  proxy_redirect     off;
  proxy_set_header   Host $host;
}

Details

site-enabled, site-available

• The sites-available folder is for storing all of your vhost configurations, whether or not they're currently enabled.
• The sites-enabled folder contains symlinks to files in the sites-available folder. This allows you to selectively disable vhosts by removing the symlink.
• sites- are from Apache HTTP Server convention
• The default nginx.conf contains following lines:

##
# Virtual Host Configs
##

include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;

Use Cases

Reverse Proxy with preserving request host

It seems that some hosts use Host header to redirect the client. nginx passes $proxy_host, which contains the address of proxied server, by default.

Some proxied servers redirect the client to a URL of their original host. By setting proxy_set_header Host $host, nginx passes Host as its own address. By this, nginx keep clients communicating with it.

user www-data www-data;
worker_processes auto;

events {
}

http {
  server {
    listen 80;
    location / {
      proxy_pass http://localhost:8080;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
    }
  }
}

Server Block Examples

• Same as Virtual Host of Apache

Links