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 so you give to those directives.

By default, the 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 and the lines:

#user nobody;
Worker_processes 1;

As can probably make out from the # character, the first line is a comment. In the other words, a piece of text which is not interpreted and have no value whatsoever. Its sole purpose are to being read by whoever opens the file, or to temporarily disable parts of an existing configuration sec tion. The # character at the beginning of a line or following a directive.

The second line was 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-Nginx should function with a single worker process (more informatio n about this particular directive was 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 has a particular syntax. For example, the worker_process directive is accepts one numeric value, whereas the user directive let s you specify-to-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, and as such, each module comes with a specific set of directives. The most fundamental directives is part of the Nginx core module and is detailed in core module directives.

Organization and inclusions

In the preceding screenshot, we have noticed a particular directive-include.

Include Mime.types;

As the name suggests, this directive would perform an inclusion of the specified file. In other words, the contents of the file is inserted at this exact location. Here's a practical example that'll 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 is processed recursively. The the possibility to use the include directive again in the other_settings.conf fil E in order to include yet another file.

In the initial configuration setup, there is the files at use- nginx.conf and mime.types. However, in the case of a more advanced configuration, there is five or more files, as described in the following tabl E:

Standard name	Description
Nginx.conf	Base configuration of the application.
Mime.types	A List of file extensions and their associated MIME types.
Fastcgi.conf	fastcgi-related configuration.
Proxy.conf	proxy-related configuration.
Sites.conf	Configuration of the websites served by Nginx, also known as virtual hosts. It ' s recommended to create separate files for each domain.

These filenames were defined conventionally, nothing actually prevents-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 * could match zero, one, or more Consecuti ve characters:

Include sites/*.conf;

This would include all files with a name, the ends with . conf in the Sites folder. This mechanism allows-create a separate file for each of the your websites and include them all at once.

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

[[email protected] sbin]#/nginx-t[emerg]: Open () "/usr/local/nginx/conf/dummyfile.conf" failed (2:no such file or dire Ctory) in/usr/local/nginx/conf/nginx.conf:48

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

[Email protected] sbin]#/nginx–tthe configuration file/usr/local/nginx/conf/nginx.conf syntax is okconfiguration fil E/usr/local/nginx/conf/nginx.conf Test is successful

Directive blocks

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

Events {
Worker_connections 1024;
}

The events block, the can find in the default configuration file is brought in by the events module. The directives that the module enables can is used within that block-in the preceding example, worker_connecti The ONS would only make sense in the context of the events block. There is one important exception though-some directives could be placed at the root of the configuration file because they There is 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 is nestedinto 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 can tell from the HTTP block (as opposed T O, say, IMAP, if want to make use of the mail server proxy features).

Within the HTTP block, 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, applies to all requests with a Host HTTP head Er exactly matching example.com.

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

Last but not least, the configuration is inherited within children blocks. The access_log directive (defined at the server , block level, this example) specifies, all HTTP req Uests for this server should is logged into a text file. This is still true within the "Child Block", although you has the possibility of disabling it by reusing The access_log directive:

[...]
Location ^~/admin/{
Index index.php;
Access_log off;
}
[...]

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

Advanced language Rules

There is a number of important observations regarding the Nginx configuration file syntax. These would help you understand certain syntax the rules that could seem confusing if you had never worked with Nginx before.

Directives Accept specific syntaxes

Indeed stumble upon complex syntaxes that can is confusing at first sight:

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

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

Later on, we'll 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, the configuration files would begin to look like programming scripts. Anyhow, the more modules we discover, the richer the syntax becomes.

Diminutives in Directive Values

Finally, 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 syntaxes is correct and equal:

Client_max_body_size 2M;
Client_max_body_size 2048k;

Additionally, when specifying a time value, the following shortcuts:

• Ms:milliseconds
• S:seconds
• M:minutes
• H:hours
• D:days
• W:weeks
• M:months (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 The default time unit is seconds; The last of the lines above thus result in an identical behavior. It is also possible to combine the values with different units:

Client_body_timeout 1m30s;
Client_body_timeout ' 1m 30s 500ms ';

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

Variables

Modules also provide variables that can is used in the definition of directive values. For example, the Nginx HTTP Core module defines the $nginx _version variable. Variables in Nginx all start with ' $ ' -the dollar sign. When setting the log_format directive, your 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 does not allow the use of 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's use as directive values can is 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 BR Ace ({ and }), you'll need to either prefix said character with a backslash (\), or enclose t He entire value in a single or double quotes:

Root '/home/example.com/my Web pages ';

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

Nginx-configuration File Syntax