Nginx HTTP Module and Configuration

Nginx’s HTTP module comes with its own set of directives and structure blocks.

Structure Blocks

`http`

The http block acts as the overarching block for all directives and sub-blocks.

`server`

A server block defines a website, as identified by a hostname (or many), or in Nginx parlance, a virtual host. server blocks cannot be placed outside of a http block.

`location`

A location block allows you to define settings for specific locations in a website. location blocks can be placed in a server block or nested within another location block.

A location block is specified with a pattern that will be matched against the requested URI. This pattern can be quite complex, involving location modifiers.

`=` modifier

This modifier means the URI must match the pattern exactly. Only simple strings can be specified (no regular expressions).

No modifier

This modifier means the URI must begin with the pattern. Only simple strings can be specified (no regular expressions).

`~` modifier

This modifier means the URI must match the pattern, and is case sensitive. Regular expressions are allowed.

`~*` modifier

This modifier means the URI must match the pattern, and is case insensitive. Regular expressions are allowed.

`^~` modifier

This modifier behaves the same as no modifier, except that Nginx will stop searching for other patterns if it has matched a location block with this modifier (see below for search order and priority).

`@` modifier

This modifier is used to define a named location block, which can only be accessed internally by try_files or error_page (see below).

As an example, given a pattern of /abcd or ^/abcd$:

http://website.com/abcd will match all modifiers
http://website.com/ABCD will match ~* modifier, as well as = and no modifier if your OS is case-insensitive
http://website.com/abcd?param1=param2 will match all modifiers (query strings are ignored)
http://website.com/abcd/ will match only no modifier, due to the trailing slash
http://website.com/abcde will match only no modifier

Search order and priority

Different modifiers have different priorities when Nginx is searching for a location block that matches a particular URI.

In order from most important to least important:

Matching on the = modifier
Matching exactly on no modifier
Matching on the ^~ modifier
Matching on the ~ and ~* modifiers
Matching on no modifier

Module Directives

Socket and host configuration

`listen`

Context: server

Sets the address and port for IP, or path for a UNIX-domain socket. If the address is left out, then a wildcard (*) is assumed. If the port is left out, port 80 is assumed (unless the master process is run without root privileges, in which case port 8000 will be assumed).

Also accepts ssl and spdy parameters for SSL and SPDY (SPDY practically requires SSL) connections respectively:

listen 443 ssl spdy;

More information on configuring Nginx for HTTPS.

`server_name`

Context: server

Sets the hostname for the server block. Nginx will match against all server blocks’ server_name directive, choosing the first block that matches. If none of them match, then Nginx will match against the listen directive’s address parameter (see above).

Allows wildcards and regex. Allows multiple hostnames.

`tcp_nodelay`

Context: http, server, location Default: on

Enables or disables the TCP_NODELAY socket option for keep-alive connections. TCP implements a mechanism, using an algorithm called Nagle’s algorithm, that delays sending data over the packet by some empirically determined time (Linux sets it at 200ms) to reduce the number of overly-small packets being sent out and causing network congestion. In other words, it temporally buffers the data being sent. However, this feature is somewhat irrelevant nowadays, with much more bandwidth available on the interwebs. Recommended to keep on (disable Nagle’s algorithm).

`tcp_nopush`

Context: http, server, location Default: off

The tcp_nopush option corresponds to the TCP_CORK option in the Linux TCP stack. TCP_CORK, like TCP_NODELAY, buffers data by blocking packets from being sent through the socket until the amount of data in the window reaches the Maximum Segment Size (MSS)¹. Disabling tcp_nopush will allow partial frames to be sent. This option is only affected when the sendfile directive is enabled.

`sendfile`

Context: http, server, location Default: off

One of the reasons why Nginx is famous for its speed in serving static files is due to the sendfile option, which uses the OS’s sendfile(2) function. The Linux’s man page explains it best:

sendfile() copies data between one file descriptor and another. Because this copying is done within the kernel, sendfile() is more efficient than the combination of read(2) and write(2), which would require transferring data to and from user space.

The sendfile() function itself takes 4 arguments, the first two of which are the file descriptors for reading (in_fd) and writing (out_fd). However, the man page specifies that:

The in_fd argument must correspond to a file which supports mmap(2)-like operations (i.e., it cannot be a socket).

Thus, sendfile() cannot be used for Unix sockets. That means sendfile() doesn’t work in conjunction with Unicorn for serving Rails applications. Still, you can and should enable sendfile for serving static files.

tcp_nodelay, tcp_nopush and sendfile can work in conjunction. tcp_nopush ensures that only full packets are sent out, reducing network (header) overhead. When the last packet is sent, tcp_nopush is disabled by Nginx, and tcp_nodelay allows the the packet to be sent immediately, instead of waiting 200ms.

`reset_timedout_connection`

Context: http, server, location Default: off

Turning this on will free up the memory assigned to the socket if the socket connection times out. Recommended to turn on.

Paths and Documents

`root`

Context: http, server, location, if

The location of the document root containing the files to be served.

`alias`

Context: location

Aliases a specified location to another location, for example:

server {
  server_name localhost;
  location /test/ {
    alias /test2/
  }
}

Requests to http://localhost/test/ will be served from http://localhost/test2/

`error_page`

Context: http, server, location, if

Allows you to specify error pages for 4-500 errors:

error_page 404 /404.html
error_page 500 /server_error.html

`index`

Context: http, server, location

Defines the default page to serve if no filename is specified in the request. If autoindex is enabled, then Nginx will attempt to index the files automatically.

`try_files`

Context: server, location

A directive that specifies the files to attempt to serve within a server or location block. A contrived example demonstrates how try_files works:

location / {
  try_files $uri $uri.html $uri.php $uri.xml @proxy;
}

# the following is a "named location block"

location @proxy {
  proxy_pass 127.0.0.1:8080;
}

try_files $uri is the “normal” behavior, where Nginx tries to locate the document with the exact specified URI. If it does not correspond to any existing file, Nginx will try to append .html to the URI and try, then with .php, then .xml, in that order. If all of these fail, then it defers the request to another location block. Another location block, if specified, must be the last argument.

Client requests

`keepalive_requests`

Context: http, server, location Default: 100

Defines the maximum number of requests that Nginx allows per keep-alive connection.

`keepalive_timeout`

Context: http, server, location Default: 75

Defines the maximum number of seconds Nginx will wait for before closing a keep-alive connection. It also accepts an optional second argument that Nginx will use to add a Keep-Alive: timeout= HTTP header:

keepalive_timeout 45 30;

`send_timeout`

Context: http, server, location Default: 60

Defines the maximum number of seconds Nginx will wait between two write operations to the client before closing the inactive connection.

`client_body_timeout`

Context: http, server, location Default: 60

Defines the maximum number of seconds Nginx will wait between two read operations from the client before responding with a 408 Request Timeout error.

`client_max_body_size`

Context: http, server, location Default: 1m

Defines the maximum size of a client request body. Needs to be set appropriately if user file uploads are expected.

MIME types

Before serving a file, Nginx will inspect its file extension to determine what value to set in the response’s Content-Type header. Nginx already includes a basic set of MIME types in its default configuration file: include mime.types;. To handle file extensions not covered in mime.types, one can include a types block:

types {
  image/jpeg jpg;
  application/json json;
}

Limits and restrictions

`limit_rate`

Context: http, server, location, if Default: No limit

Limits the transfer rate of client connections.

`limit_rate_after`

Context: http, server, location, if Default: None

Sets the amount of data to allow transferring before the limit_rate directive takes effect.

`internal`

Prevents external requests from accessing the specific location block:

location /admin/ {
  internal;
}

File processing and caching

`open_file_cache`

Context: http, server, location Default: Off

Enables Nginx caching for file descriptors. It accepts two arguments: max=X, where X refers to the maximum number of entries that can be cached, and inactive=Y, where Y refers to the number of seconds a cache entry should be stored. Y defaults to 60 seonds, meaning that cache entries will be cleared after 60 seconds, unless the open_file_cache_min_uses directive is specified (see below).

`open_file_cache_errors`

Context: http, server, location Default: Off

Enables Nginx caching for errors related to file lookups, such as incorrect file permissions or non-existence of files. This is so that Nginx doesn’t have to repeatedly attempt accessing files it cannot serve.

`open_file_cache_min_uses`

Context: http, server, location Default: 1

This directive allows you to tell Nginx not to remove file descriptors from the cache if its accessed more than a certain number of times, as defined by this directive:

open_file_cache_min_uses 2;

`open_file_cache_valid`

Context: http, server, location Default: 60

Defines the number of seconds Nginx will wait for before revalidating a cached entry.

Other directives

`server_tokens`

Context: http, server, location Default: On

Tells Nginx whether to include its version number in the response.

`underscores_in_headers`

Context: http, server Default: Off

Allow or disallow underscores in custom HTTP header names (such as X_AUTH_TOKEN).

MSS is usually 40 or 60 bytes smaller than the Maximum Transmission Unit (MTU), since it doesn’t account for the TCP header or IP header. ↩

Nginx HTTP Module and Configuration

#Structure Blocks

http

server

location

= modifier

No modifier

~ modifier

~* modifier

^~ modifier

@ modifier

Search order and priority

#Module Directives

Socket and host configuration

listen

server_name

tcp_nodelay

tcp_nopush

sendfile

reset_timedout_connection

Paths and Documents

root

alias

error_page

index

try_files

Client requests

keepalive_requests

keepalive_timeout

send_timeout

client_body_timeout

client_max_body_size

MIME types

Limits and restrictions

limit_rate

limit_rate_after

internal

File processing and caching

open_file_cache

open_file_cache_errors

open_file_cache_min_uses

open_file_cache_valid

Other directives

server_tokens

underscores_in_headers

#Footnotes

Structure Blocks

`http`

`server`

`location`

`=` modifier

`~` modifier

`~*` modifier

`^~` modifier

`@` modifier

Module Directives

`listen`

`server_name`

`tcp_nodelay`

`tcp_nopush`

`sendfile`

`reset_timedout_connection`

`root`

`alias`

`error_page`

`index`

`try_files`

`keepalive_requests`

`keepalive_timeout`

`send_timeout`

`client_body_timeout`

`client_max_body_size`

`limit_rate`

`limit_rate_after`

`internal`

`open_file_cache`

`open_file_cache_errors`

`open_file_cache_min_uses`

`open_file_cache_valid`

`server_tokens`

`underscores_in_headers`

Footnotes