Nginx core concepts

Nginx configuration files are simply sequences of directives that can take up to eight space-separated arguments, for example:

In the configuration file, the directives are delimited by a semicolon ( ; ) from one
another. Some of the directives may have a block instead of a semicolon. A block is
delimited by curly brackets ( {} ). A block can contain arbitrary text data, for example:

types {
text/html     html htm shtml;
text/css        css;
text/xml      xml;
image/gif   gif;
image/jpeg                          jpeg jpg;
application/x-javascript js;
application/atom+xml   atom;
application/rss+xml        rss;

A block can also contain a list of other directives. In this case, the block is called a
section. A section can enclose other sections, thus establishing a hierarchy of sections.
Most important directives have short names; this reduces the effort required to
maintain the configuration file.


Value types
In general, a directive can have arbitrary quoted or unquoted strings as arguments.
But many directives have arguments that have common value types. To help you
quickly get your head around the value types I listed them in the following table:

Value type         Format                                Example of a value
Flag                     [on|off]                                       on, off
Signed integer -?[0-9]+                                     1024
Size                     [0-9]+([mM]|[kK])?               23M, 12348k
Offset                 [0-9]+([mM]|[kK]|[gG])?     43G, 256M
Milliseconds    [0-9]+[yMwdhms]?                30s, 60m


Variables are named objects that can be assigned a textual value. Variables can only
appear inside the http section. A variable is referred to by its name, prefixed by the
dollar ( $ ) symbol. Alternatively, a variable reference can enclose a variable name in
curly brackets to prevent merging with surrounding text.
Variables can be used in any directive that accepts them, as shown here:
proxy_set_header Host $http_host;
This directive sets the HTTP header host in a forwarded request to HTTP host
name from the original request. This is equivalent to the following:
proxy_set_header Host ${http_host};

With the following syntax, you can specify the host name:
proxy_set_header Host ${http_host}_squirrel;

The preceding command will append a string _squirrel to the value of the original host name. Without curly brackets, the string _squirrel would have been interpreted as a part of the variable name, and the reference would have pointed to a variable “http_host_squirrel” rather than http_host .

There are also special variable names:
•Variables from $1 to $9 refer to the capture arguments in the regular
expressions, as shown here:
location ~ /(.+)\.php$ {
proxy_set_header X-Script-Name $1;

The preceding configuration will set the HTTP header X-Script-Name in the forwarded request to the name of the PHP script in the request URI.
The captures are specified in a regular expression using round brackets.
•Variables that start with $arg_ refer to the corresponding query argument in the original HTTP request, as shown here:
proxy_set_header X-Version-Name $arg_ver;

The preceding configuration will set the HTTP header X-Version-Name in the forwarded request to the value of the ver query argument in the
original request.
•Variables that start with $http_ refer to the corresponding HTTP header line in the original request.
•Variables that start with $sent_http_ refer to the corresponding HTTP header line in the outbound HTTP request.
•Variables that start with $upstream_http_ refer to the corresponding HTTP header line in the response received from an upstream.
•Variables that start with $cookie_ refer to the corresponding cookie in the original request.
•Variables that start with $upstream_cookie_ refer to the corresponding cookie in the response received from an upstream

Variables must be declared by Nginx modules before they can be used in the configuration. Built-in Nginx modules provide a set of core variables that allow you to operate with the data from HTTP requests and responses. Refer to the Nginx documentation for the complete list of core variables and their functions.

Any Nginx configuration section can contain inclusions of other files via the include directive. This directive takes a single argument containing a path to a file to be included, as shown here:
* A simple relative inclusion. The target file’s path
* is relative to the location of the current configuration file.
include mime.types;
* A simple inclusion using an absolute path.

include /etc/nginx/conf/site-defaults.conf;
Once specified, the include directive instructs Nginx to process the contents of the file or files specified by the argument of this directive as if they were specified in place of the include directive.

The include directive can also contain a globbed path with wild cards, either relative or absolute. In this case, the globbed path is expanded and all files matching the specified pattern are included in no particular order. Take a look
at the following code:
* A simple glob inclusion. This will include all files
* ending on “.conf” located in /etc/nginx/sites-enabled
include /etc/nginx/sites-enabled/*.conf;
The include directive with wild cards is an obvious solution for including site configurations, as their number can vary greatly. Using the include directive, you can properly structure the configuration file or reuse certain parts multiple times.

A section is a directive that encloses other directives in its block. Each section’s delimiters must be located in the same file, while the content of a section can span multiple files via the include directive.

The http section
The http section enables and configures the HTTP service in Nginx. It has the server and upstream declarations. As far as individual directives are concerned, the http section usually contains those that specify defaults for the entire HTTP service.
The http section must contain at least one server section in order to process HTTP requests. Here is a typical layout of the http section:

http {
server {
The server section
The server section configures an HTTP or HTTPS virtual host and specifies listening addresses for them using the listen directive. At the end of the configuration stage, all listening addresses are grouped together and all listening addresses are activated at startup.

The server section contains the location sections, as well as sections that can be enclosed by the location section (see description of other sections types for details). Directives that are specified in the server section itself go into the so-called default location. In that regard, the server section serves the purpose of the location section itself.

When a request comes in via one of the listening addresses, it is routed to the server sections that match a virtual host pattern specified by the server_name directive. The request is then routed further to the location that matches the path of the request URI or processed by the default location if there is no match.
The upstream section
The upstream section configures a logical server that Nginx can pass requests to for further processing. This logical server can be configured to be backed by one or more physical servers external to Nginx with concrete domain names or IP addresses.

Upstream can be referred to by name from any place in the configuration file where a reference to a physical server can take place. In this way, your configuration can be made independent of the underlying structure of the upstream, while the upstream structure can be changed without changing your configuration.
The location section
The location section is one of the workhorses in Nginx. The location directive takes parameters that specify a pattern that is matched against the path of the request URI. When a request is routed to a location, Nginx activates configuration that is enclosed by that location section.

There are three types of location patterns: simple, exact, and regular expression location patterns.
A simple location has a string as the first argument. When this string matches the initial part of the request URI, the request is routed to that location. Here is an example of a simple location:
location /images {
root /usr/local/html/images;

Any request with a URI that starts with /images , such as /images/powerlogo.png ,/images/calendar.png , or /images/social/github-icon.png will be routed to this location. A URI with a path that equals to /images will be routed to this location as well.
Exact locations are designated with an equals ( = ) character as the first argument and have a string as the second argument, just like simple locations do. Essentially, exact locations work just like simple locations, except that the path in the request URI has to match the second argument of the location directive exactly in order to be routed to that location:
location = /images/empty.gif {

The preceding configuration will return an empty GIF file if and only if the URI /images/empty.gif is requested.
Regular expression locations
Regular expression locations are designated with a tilde ( ~ ) character or ~* (for case-insensitive matches) as the first argument and have a regular expression as the second argument. Regular expression locations are processed after both simple and exact locations. The path in the request URI has to match the regular expression in the second argument of the location directive in order to be routed to that
location. A typical example is as follows:
location ~ \.php$ {
According to the preceding configuration, requests with URIs that end with .php will be routed to this location. The location sections can be nested. For that, you just need to specify a location section inside another location section.


All settings can be attributed to three categories:
• Those that make sense only in the entire HTTP service (marked red)
• Those that make sense in the virtual host configuration (marked blue)
• Those that make sense on all levels of configuration (marked green)
The settings from the first category do not have any inheritance rules, because they cannot inherit values from anywhere. They can be specified in the http section only and can be applied to the entire HTTP service. These are settings set by directives,such as variables_hash_max_size , variables_hash_bucket_size , server_names_hash_max_size , and server_names_hash_bucket_size .

The settings from the second category can inherit values only from the http section. They can be specified both in the http and server sections, but the settings applied to a given virtual host are determined by inheritance rules. These are settings set by directives, such as client_header_timeout , client_header_buffer_size , and large_client_header_buffers.

Finally, the settings from the third category can inherit values from any section up to http . They can be specified in any section inside the HTTP service configuration, and the settings applied to a given context are determined by inheritance rules.
The arrows on the figure illustrate value propagation paths. The colors of the arrows specify the scope of the setting. The propagation rules along a path are as follows: When you specify a value for a parameter at a certain level of the configuration,it overrides the value of the same parameter at the outer levels if it is set, and automatically propagates to the inner levels of the configuration. Let’s take a
look at the following example:
location / {
# The outer section
root /var/www/;
gzip on;
location ~ \.js$ {
# Inner section 1
gzip off;
location ~ \.css$ {
# Inner section 2
The value of the root directive will propagate to the inner sections, so there is no need to specify it again. The value of the gzip directive in the outer section will propagate to the inner sections, but will be overridden by the value of the gzip directive inside the first inner section. The overall effect of that will be that gzip compression will be enabled everywhere in the other section, except for the first inner section.
When a value for some parameter is not specified in a given configuration section, it is inherited from a section that encloses the current configuration section. If the enclosing section does not have this parameter set, the search goes to the outer level and so on. If a value for a certain parameter is not specified at all, a built-in default value is used.

The First sample configuration
error_log logs/error.log;
events {
use epoll;
worker_connections  1024;
http {
include   mime.types;
default_type application/octet-stream;
server {
listen 80;
location / {
proxy_pass http://localhost:8080;
include proxy_params;
location ~ ^(/images|/js|/css) {
root html;
expires 30d;

This configuration first instructs Nginx to write the error log to logs/error.log .Then, it sets up Nginx to use the epoll event processing method ( use epoll ) and allocates memory for 1024 connections per worker ( worker_connections 1024 ).After that, it enables the HTTP service and configures certain default settings for the HTTP service ( include mime.types , default_type application/octet-stream ).It creates a virtual host and sets its names to and ( server_name ). The virtual host is made available at the default listening address and port 80 ( listen 80 ).
We then configure two locations. The first location passes every request routed to it into a web application server running at http://localhost:8080 ( proxy_pass http://localhost:8080 ). The second location is a regular expression location. By specifying it we effectively exclude a set of paths from the first location. We use this location to return static data such as images, JavaScript files, and CSS files. We set the base directory for our media files as html( root html ). For all media files, we set the expiration date as 30 days ( expires 30d ).

To try out this configuration, back up your default configuration file and replace the content of the default configuration file with the preceding configuration.

Then, restart Nginx for the settings to take effect. After this is done, you can navigate to the URL http://localhost/ to check out your new configuration.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s