Nginx - Configuration File Syntax

Configuration Directives

The Nginx configuration file can be described as a list of directives organized in a logical structure. The entire behavior of the application is defined by the values that you give to those directives.

By default, Nginx makes use of one main configuration file. Now let‘s take a quick peek at the first few lines of this initial setup:

A closer look at the first two lines:

#user nobody;
worker_processes 1;

As you can probably make out from the # character, the first line is a comment. In other words, a piece of text that is not interpreted and has no value whatsoever. Its sole purpose is to be read by whoever opens the file, or to temporarily disable parts of an existing configuration section. You may use the # character at the beginning of a line or following a directive.

The second line is an actual statement—a directive. The first bit (worker_processes) represents a setting key to which you append one or more values. In this case, the value is 1, indicating that Nginx should function with a single worker process (more information about this particular directive is given in further sections).

Note: Directives always end with a semicolon (;).

Each directive has a unique meaning and defines a particular feature of the application. It may also have a particular syntax. For example, the worker_process directive only accepts one numeric value, whereas the user directive lets you specify up to two character strings—one for the user account (the Nginx worker processes should run as) and a second for the user group.

Nginx works in a modular way, and as such, each module comes with a specific set of directives. The most fundamental directives are part of the Nginx Core module and will be detailed in Core Module Directives.

Organization and Inclusions

In the preceding screenshot, you may have noticed a particular directive—include.

include mime.types;

As the name suggests, this directive will perform an inclusion of the specified file. In other words, the contents of the file will be inserted at this exact location. Here is a practical example that will help you understand:

nginx.conf:
　　user nginx nginx;
　　worker_processes 4;
　　include other_settings.conf;

other_settings.conf:
　　error_log logs/error.log;
　　pid logs/nginx.pid;

The final result, as interpreted by Nginx, is as follows:

　　user nginx nginx;
　　worker_processes 4;
　　error_log logs/error.log;
　　pid logs/nginx.pid;

Inclusions are processed recursively. In this case, you have the possibility to use the include directive again in the other_settings.conf file in order to include yet another file.

In the initial configuration setup, there are two files at use — nginx.conf and mime.types. However, in the case of a more advanced configuration, there may be five or more files, as described in the following table:

These filenames were defined conventionally, nothing actually prevents you from regrouping your FastCGI and proxy settings into a common file named proxy_and_fastcgi_config.conf.

Note that the include directive supports filename globbing. In other words, filenames referenced with the * wildcard, where * may match zero, one, or more consecutive characters:

include sites/*.conf;

This will include all files with a name that ends with .conf in the sites folder. This mechanism allows you to create a separate file for each of your websites and include them all at once.

Be careful when including a file — if the specified file does not exist, the configuration checks will fail, and Nginx will not start:

[[email protected] sbin]# ./nginx -t
[emerg]: open() "/usr/local/nginx/conf/dummyfile.conf" failed (2: No such file or directory) in /usr/local/nginx/conf/nginx.conf:48

The previous statement is not true for inclusions with wildcards. Moreover, if you insert include dummy*.conf in your configuration and test it (whether there is any file matching this pattern on your system or not), here is what should happen:

[[email protected] sbin]# ./nginx –t
the configuration file /usr/local/nginx/conf/nginx.conf syntax is ok
configuration file /usr/local/nginx/conf/nginx.conf test is successful

Directive blocks

Directives are brought in by modules — if you activate a new module, a specific set of directives becomes available. Modules may also enable directive blocks, which allow for a logical construction of the configuration:

events {
　　worker_connections 1024;
}

The events block that you can find in the default configuration file is brought in by the Events module. The directives that the module enables can only be used within that block — in the preceding example, worker_connections will only make sense in the context of the events block. There is one important exception though — some directives may be placed at the root of the configuration file because they have a global effect on the server. The root of the configuration file is also known as the main block.

Note that in some cases, blocks can be nested into each other, following a specific logic:

http {
　　server {
　　　　listen 80;
　　　　server_name example.com;
　　　　access_log /var/log/nginx/example.com.log;
　　　　location ^~ /admin/ {
　　　　　　index index.php;
　　　　}
　　}
}

This example shows how to configure Nginx to serve a website, as you can tell from the http block (as opposed to, say, imap, if you want to make use of the mail server proxy features).

Within the http block, you may declare one or more server blocks. A server block allows you to configure a virtual host. The server block, in this example, contains some configuration that applies to all requests with a Host HTTP header exactly matching example.com.

Within this server block, you may insert one or more location blocks. These allow you to enable settings only when the requested URI matches the specified path.

Last but not least, configuration is inherited within children blocks. The access_log directive (defined at the server block level in this example) specifies that all HTTP requests for this server should be logged into a text file. This is still true within the location child block, although you have the possibility of disabling it by reusing the access_log directive:

[…]
　　location ^~ /admin/ {
　　　　index index.php;
　　　　access_log off;
　　}
[…]

In this case, logging will be enabled everywhere on the website, except for the /admin/ location path. The value set for the access_log directive at the server block level is overridden by the one at the location block level.

Advanced language rules

There are a number of important observations regarding the Nginx configuration file syntax. These will help you understand certain syntax rules that may seem confusing if you have never worked with Nginx before.

Directives Accept Specific Syntaxes

You may indeed stumble upon complex syntaxes that can be confusing at first sight:

rewrite ^/(.*)\.(png|jpg|gif)$ /image.php? file=$1&format=$2 last;

Syntaxes are directive-specific. While the listen directive may only accept a port number to open a listening socket, the location block or the rewrite directive support complex expressions in order to match particular patterns.

Later on, we will approach a module (the Rewrite module) which allows for a much more advanced logical structure through the if, set, break, and return directives and the use of variables. With all of these new elements, configuration files will begin to look like programming scripts. Anyhow, the more modules we discover, the richer the syntax becomes.

Diminutives in Directive Values

Finally, you may use the following diminutives for specifying a file size in the context of a directive value:

• k or K: Kilobytes
• m or M: Megabytes

As a result, the following two syntaxes are correct and equal:

client_max_body_size 2M;
client_max_body_size 2048k;

Additionally, when specifying a time value, you may use the following shortcuts:

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

This becomes especially useful in the case of directives accepting a period of time as a value:

client_body_timeout 3m;
client_body_timeout 180s;
client_body_timeout 180;

Note that the default time unit is seconds; the last two lines above thus result in an identical behavior. It is also possible to combine two values with different units:

client_body_timeout 1m30s;
client_body_timeout ‘1m 30s 500ms‘;

The latter variant is enclosed in quotes since values are separated by spaces.

Variables

Modules also provide variables that can be used in the definition of directive values. For example, the Nginx HTTP Core module defines the $nginx_version variable. Variables in Nginx always start with "$" — the dollar sign. When setting the log_format directive, you may include all kinds of variables in the format string:

[…]
　　location ^~ /admin/ {
　　　　access_log logs/main.log;
　　　　log_format main ‘$pid - $nginx_version - $remote_addr‘;
　　}
[…]

Note that some directives do not allow you to use variables:

error_log logs/error-$nginx_version.log;

The preceding directive is valid, syntax-wise. However, it simply generates a file named error-$nginx_version.log, without parsing the variable.

String Values

Character strings that you use as directive values can be written in three forms. First, you may enter the value without quotes:

root /home/example.com/www;

However, if you want to use a particular character, such as a blank space (" "), a semicolon (;), or curly brace ({ and }), you will need to either prefix said character with a backslash (\), or enclose the entire value in single or double quotes:

root ‘/home/example.com/my web pages‘;

Nginx makes no difference whether you use single or double quotes. Note that variables inserted in strings within quotes will be expanded normally, unless you prefix the $ character with a backslash (\).