Nginx Configuration Syntax

The third post in the Nginx series.

Nginx configuration consists essentially of key-value pairs called directives, which can be organised and grouped in blocks.

#Directives

A directive is a key-value(s) pair that looks something like this:

worker_processes 5;
error_log logs/error.log info;

Directives may accept more than 1 value, like the error_log directive. Directives may also have type restrictions on values - the worker_processes directive only accepts a single integer as a value.

Directives are terminated with semicolons.

Each module may introduce its own directives and blocks (discussed below) that can be set.

#Importing

Nginx configuration files can be imported with the include directive:

include mime.types;

The effect of this importing is that the contents of the file will be inserted at the exact location of the include directive.

include directives are processed recursively.

The include directive supports filename globbing:

include sites/*.conf

where * may match any number (>0) of consecutive characters. This will import all of the .conf files in the sites folder.

If a file specified by an include directive cannot be found, Nginx’s configuration check will fail, unless the include directive path includes a wildcard:

include non-existent.conf # will fail
include non-existent*.conf # will pass

#Blocks

Modules may introduce blocks, which are logical structures that group module-specific directives together. Many directives can only be used within their associated blocks. The root of the main configuration file is also known as the main block.

Blocks may be nested. Below we define a http block as introduced by the Nginx HTTP module. The http block accepts multiple server blocks defining Nginx virtual hosts, and each server block itself accepts multiple location blocks which contain directives specific to certain locations of the website:

http {

  server {
    listen 80;
    server_name wowdomain.com;
    access_log /var/log/nginx/wowdomain.com.log;

      location ^~ /admin {
        access_log off;
      }
  }

}

In nested blocks, directives are inherited by child blocks and can be overriden. In this example, logging will be disabled just for the /admin/ path of wowdomain.com.

Units

One may use units:

client_max_body_size 2M;

• k or K: Kilobytes
• m or M: Megabytes
• ms: Milliseconds
• s: Seconds
• m: Minutes
• h: Hours
• d: Days
• w: Weeks
• M: Months (30 days)
• y: Years (365 days)

Variables

Variables in Nginx start with $. Some modules introduce variables can be used when setting directives.

Some directives do not support variables:

error_log logs/error-$nginx_version.log;

will actually log to a file called error-$nginx_version.log.

String values

Strings may be inputted without quotes unless they include blank spaces, semicolons or curly braces, then they need to be escaped with backslashes or enclosed in single/double quotes.

Variables in quoted strings are expanded normally unless the $ is escaped.

Comments

Comments is Ruby-like, with lines prepended by a #:

# this is a comment