If you have followed steps 1 to 10, it will be really easy for you to install any Nginx module.

If you want to check that the module is installed correctly, you can enter the following command:

nginx -V 

A sample output is something as shown in the following screenshot:

This basically gives you the compilation flags that were used to install this particular binary of Nginx, indirectly listing the various modules that were compiled into it.

If you want the debug mode, then you will need to compile Nginx with the debug flag (--with-debug ). In most cases, most of the distributions have packages where Nginx is pre-compiled with debug flag. Here are the various levels of debugging that you can utilize:

error_log LOGFILE [debug | info | notice | warn | error | crit | debug_core | debug_alloc | debug_mutex | debug_event | debug_http | debug_imap];

If you do not set the error log location, it will log to a compiled-in default log location. This logging is in addition to the normal error logging that you can do per site. Here is what the various specific debug flags do:

Nginx allows us to log errors for specific IP addresses. Here is a sample configuration that will log errors from 192.168.1.1 and the IP range of 192.168.10.0/24:

error_log logs/error.log;
events { 
    debug_connection   192.168.1.1; 
    debug_connection   192.168.10.0/24; 
}

This is extremely useful when you want to debug in the production environment, as logging for all cases has unnecessary performance overheads. This feature allows you to not set a global debug on the error_log , while being able to see the debug output for specific matched IP blocks based on the user's IP address.

Let me run you through the simple steps of how you can reload Nginx from the command line.

This is very useful while writing scripts, which control Nginx configuration. A good example is when you are deploying code on production; you will temporarily point the site to a static landing page.

Let's take a sample configuration file nginx.conf and see how can it be broken into logical, maintainable pieces:

user       www www; #This directive determines the user and group of the processes started
worker_processes  2;
error_log  logs/error.log;
pid        logs/nginx.pid;
events {
    worker_connections  1024;
}
http {
    include       mime.types;
    default_type  application/octet-stream;
    gzip on;
    gzip_min_length 5000;
    gzip_buffers    4 8k;
    gzip_types text/plain text/html text/css application/x-javascript text/xml application/xml application/xml+rss text/javascript;
    gzip_proxied  any;
    gzip_comp_level 2;
    ignore_invalid_headers  on;
    server {
        listen       80;
        server_name  www.example1.com;
        location / {
            root   /var/www/www.example1.com;
            index  index.php index.html index.htm;
        }
        location ~ \.php$ {
            include conf/fcgi.conf;
            fastcgi_pass   127.0.0.1:9000;
        }
    }
}

The preceding configuration is basically serving a simple PHP site at http://www.example1.com using FastCGI. Now we can go ahead and split this file into the following structure:

The following code is for the new nginx.conf

user       www www; 
worker_processes  2;
error_log  logs/error.log;
pid        logs/nginx.pid;
events {
        worker_connections  1024;
}
http {
        include       mime.types;
        default_type  application/octet-stream;
        gzip on;
        gzip_min_length 5000;
        gzip_buffers    4 8k;
        gzip_types text/plain text/html text/css application/x-javascript text/xml application/xml application/xml+rss text/javascript;
        gzip_proxied  any;
        gzip_comp_level 2;
        ignore_invalid_headers  on;
       includes sites-available/*;
}

If you notice, you will see how includes has allowed the inclusion of external configuration files. It should be noted that if we have any errors in any of the files, the Nginx server will fail to reload.

Here is the FastCGI configuration which is used by this setup; generally most Nginx installations provide a default one.

The following is the code for fcgi.conf:

fastcgi_param  QUERY_STRING       $query_string;
fastcgi_param  REQUEST_METHOD     $request_method;
fastcgi_param  CONTENT_TYPE       $content_type;
fastcgi_param  CONTENT_LENGTH     $content_length;
fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
fastcgi_param  REQUEST_URI        $request_uri;
fastcgi_param  DOCUMENT_URI       $document_uri;
fastcgi_param  DOCUMENT_ROOT      $document_root;
fastcgi_param  SERVER_PROTOCOL    $server_protocol;
fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;
fastcgi_param  REMOTE_ADDR        $remote_addr;
fastcgi_param  REMOTE_PORT        $remote_port;
fastcgi_param  SERVER_ADDR        $server_addr;
fastcgi_param  SERVER_PORT        $server_port;
fastcgi_param  SERVER_NAME        $server_name;
fastcgi_index  index.php ;
fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name ;

# PHP only, required if PHP was built with --enable-force-cgi-redirect
fastcgi_param  REDIRECT_STATUS    200;
fastcgi_connect_timeout 60;
fastcgi_send_timeout 180;
fastcgi_read_timeout 180;
fastcgi_buffer_size 128k;
fastcgi_buffers 4 256k;
fastcgi_busy_buffers_size 256k;
fastcgi_temp_file_write_size 256k;
fastcgi_intercept_errors on;

The following is the code for sites-enabled/site1.conf:

server {
    listen       80;
    server_name  www.example1.com;
    location / {
        root   /var/www/www.example1.com;
        index  index.php index.html index.htm;
    }
    location ~ \.php$ {
        include conf/fcgi.conf;
        fastcgi_pass   127.0.0.1:9000;
    }
}

This sort of a file arrangement allows clean separation of the main configuration and the auxiliary ones. It also promotes structured thinking, which is useful when you have to quickly switch or deploy sites.

We will go over the various configurations that you see in these files in other chapters. For example, fcgi.conf is covered in the recipe to get PHP working with Nginx using FastCGI.

Let's take a simple example. You want to set up a simple set of webpages on www.example1.com. Here is the sample configuration which needs to go into the sites-enabled/site1.conf:

server {
	listen 80;
	server_name www.example1.com example1.com;
	access_log /var/log/Nginx/example1.com/access.log;
	error_log /var/log/Nginx/example1.com/error.log;
	location / {
		root /var/www/www.example1.com;
		index index.html index.htm;
	}
}

So let's see how this works. The listen defines the port on which the web server is listening (in this case, its 80)! The server_name lets you easily define the domain that maps to this virtual host configuration. Inside, you can start defining how the virtual host works. In this case it serves set of HTML pages from the /var/www/www.example1.com directory.

So when you reload your Nginx configuration assuming that your DNS records point correctly at your server, you should see your HTML pages load when you access the web address (in this case, http://www.example1.com).

Here is a quick checklist to get you started:

For situations like the one above, one can utilize the default catchall virtual host that Nginx provides; here is a simple example where this default catchall virtual host serves a simple set of web pages.

The following is the code for sites-enabled/default.conf:

server {
	listen   80 default; 
 	server_name  _;
	location / {
		root /var/www/default;
		index index.html index.htm;
	}
}

The key thing to note is the fact that you are listening on the default port and that the server_name is "_" which is the catchall mechanism. So whenever the user enters a domain for which you have no defined virtual host, pages will get server from the /var/www/default directory.

You will need to set a wildcard on the DNS entry. Without the DNS entries, the domain (and subdomains) will never resolve to your server IP. A sample DNS entry is given below which points the domain http://example1.com to the IP 69.9.64.11:

example1.com. IN A 69.9.64.11

Once you know how your DNS works, you can add this to your nginx.conf inside the http section:

server {
	listen 80;
	server_name example1.com *.example1.com;
	location / {
		........
	}	
}

The important part to note is that in this case, you are serving all the subdomains using the same code base. We have also set the virtual host to serve the non-www domain as well (example1.com which is different from www.example1.com).

So when you type a.example1.com, your web application will receive a.example1.com as the domain that was requested from the web server and it can process the HTTP response accordingly.

This particular configuration can be found at the top of the sample configuration file nginx.conf:

user       www www; 
worker_processes  5; 
error_log  logs/error.log; 
pid        logs/nginx.pid; 
worker_rlimit_nofile 8192; 
events { 
  worker_connections  4096; 
}

In the preceding configuration, we can see how the various process configurations work. You first set the UNIX user under which the process runs, then you can set the number of worker processes that Nginx needs to spawn, after that we have some file locations where the errors are logged and the PIDs (process IDs) are saved.

By default, worker_processes is set at 2. It is a crucial setting in a high performance environment as Nginx uses it for the following reasons:

It is recommended that you set worker_processes as the number of cores available on your server. If you know the values of worker_processes and worker_connections, one can easily calculate the maximum number of connections that Nginx can handle in the current setup.

Maximum clients = worker_processes * worker_connections

This is controlled by one simple part of the Nginx configuration. You can simply paste this in the server part of the Nginx configuration:

client_max_body_size 100M; # M stands for megabytes

This preceding configuration will allow you to upload a 100 megabyte file. Anything more than that, and you will receive a 413. You can set this to any value which is less than the available disk space to Nginx, which is primarily because Nginx downloads the file to a temporary location before forwarding it to the backend application.

Nginx also lets us control other factors related to people uploading files on the web application, like timeouts in case the client has a slow connection. A slow client can keep one of your application threads busy and thus potentially slow down your application. This is a problem that is experienced on all the heavy multimedia user-driven sites, where the consumer uploads all kinds of rich data such as images, documents, videos, and so on. So it is sensible to set low timeouts.

client_body_timeout 60; # parameter in seconds
client_body_buffer_size 8k;
client_header_timeout 60; # parameter in seconds
client_header_buffer_size 1k;

So, here the first two settings help you control the timeout when the body is not received at one read-step (basically, if the server is queried and no response comes back). Similarly, you can set the timeout for the HTTP header as well. The following table lists out the various directives and limits you can set around client uploading.

Let's take a simple example and start understanding what one can achieve with it.

This is a simple example where we can see that you can simply include some partials in the larger page, and in addition to that you can create block as well within the page. So the <block> directive allows you to create silent blocks that can be included later, while the <include> directive can be used to include HTML partials from other files, or even URL end points. The <echo> directive is used to output certain variables from within the Nginx context.

You can utilize this feature for all kinds of interesting setups where:

The sample configuration for this particular page would look like this:

server {
	listen 80;
	server_name www.example1.com;
	location / { 
 		add_before_body   /red_block 
 		add_after_body    /blue_block; 
		...
	}
	location /red_block/ {
		…
	}
	location /blue_block/ {
		….
	}
}

This can act as a performance enhancer by allowing you to load CSS based upon the browser only. There can be cases where you want to introduce something into the header or the footer on short notice, without modifying your backend application. This provides an easy fix for those situations.

./configure –with-http_addition_module

Here is the example of one such Nginx directory listing . It is pretty useful when you want to share some files over your local network. To start auto index on any directory all you need to do is to carry out the following example and place it in the server section of the Nginx configuration file:

server {
	location 80;
	server_name www.example1.com;
	location / {
		root /var/www/test;
		autoindex on;
	}
}

This will simply enable auto indexing when the user types in http://www.example1.com. You can also control some other things in the listings in this way:

autoindex_exact_size off;

This will turn off the exact file size listing and will only show the estimated sizes. This can be useful when you are worried about file privacy issues.

autoindex_localtime on;

This will represent the timestamps on the files as your local server time (it is GMT by default):

This image displays a sample index auto-generated by Nginx using the preceding configuration. You can see the filenames, timestamp, and the file sizes as the three data columns.

Let's have a look at a sample configuration which needs to be placed within the HTTP section of the Nginx configuration:

server {
	listen 80;
	server_name www.example1.com;
	location  /  { 
		root /var/www/www.example1.com/test_index;
 		random_index  on; 
	}
}

Let's assume that you have some files in the /var/www/www.example1.com/test_index directory. When you turn on the random index it will scan the directory and then send a randomly picked file instead of the default index.html. The only exceptions are plain files. Whole filenames which start with a dot will not be part of the site of files to be picked from.

So here are two sample test pages, with slightly differing headers. Notice that the URLs are the same. So it will let you determine if the end user is clicking through more with the red link or the blue link using pure statistical methods:

The preceding screenshot displays A.html on opening the site. There is equal probability of opening both the pages, much like the tossing of a coin and getting heads or tails.

So, using the A-B testing as an example, you can set an A.html and a B.html, which would be served to the user randomly. It would allow you to easily measure a lot of interesting client behavior by simply analyzing the Nginx access logs.

Here is a sample configuration for this module. This goes in the server section of the configuration:

userid          on;
userid_name     uid;
userid_domain   example1.com;
userid_path     /;
userid_expires  365d;
userid_p3p      'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"';

Now let's see and understand what the various directives are about. The first userid directive enables this module; the second assigns a name to the cookie which is going to be written on the client side. The next three directives are the standard cookie information that is needed (the primary domain, the path, and the time of expiry). The last directive enables the browser to understand the privacy practices that the website follows. This is done by using the P3P protocol which allows websites to declare their intended usage that they collect about the user. It is basically an XML file that allows you to programmatically display your privacy policy. The following code is a simple example configuration of how you can define a policy where the data is removed after 4 months:

<META xmlns="http://www.w3.org/2002/01/P3Pv1">
  <POLICY-REFERENCES>
    <EXPIRY max-age="10000000"/><!-- about four months -->
  </POLICY-REFERENCES>
</META>

This XML put on the server will objectively define the privacy policies of the site to the incoming bots or users.

On enabling this module, some variables are available in the Nginx configuration which allow you do fairly interesting things. You have access to some variables in the configuration contest, like $uid_got,$uid_set.

These can be used for writing interesting rewrite rules. A simple application using these variables is to log the users coming on your site and then determining the user bounce rates on your website by parsing the logs.

All you need to do is to place this in the server section of your Nginx configuration:

charset         windows-1251; 
source_charset  koi8-r;

This basically defines the fact that the source character set is koi8-r. If the encoding is different from the charset character set, then re-encoding is carried out. In case your original response already has a "Content-Type" header present then you will need to use the following to override and do the re-encoding:

overrride_charset on;

You can also decide how the re-encoding happens by defining a character mapping. A simple example is the following:

charset_map  koi8-r  windows-1251 { 
  C0  FE ; # small yu 
  C1  E0 ; # small a 
  C2  E1 ; # small b 
  C3  F6 ; # small ts 
  # ... 
}

Nginx lets you do these neat little things that can make your site more accessible and usable for the end-user.

You will need to modify your Nginx configuration file and add the following directives:

http {
	gzip             on; 
	gzip_min_length  1000; 
	gzip_comp_level 6;
	gzip_proxied     expired no-cache no-store private auth; 
	gzip_types       text/plain application/xml; 
	gzip_disable     "MSIE [1-6]\.";
	server {
		….
	}
}

This sample configuration allows you to turn on the Gzip compression of the outgoing page for all pages which are over 1000 bytes. This limit is set because compression technology performance degrades as the page size becomes smaller. You can then set the various MIME types for which the compression should occur; this particular example will compress only plain text files and XML files.

Older browsers are not the best when it comes to utilizing this, and you can disable Gzip depending on the browser type. One of the most interesting settings is the level of compression where you need to make a choice between the amount of CPU that you want to spend on compressing and serving the pages (the higher this number, more of your CPU time will go towards compressing and sending pages). It is recommended to follow a middle path on this particular setting; the client also spends more CPU time decompressing the page if you set this. A sensible setting of this value would be six.

For proxy requests, gzip_proxied actually allows or disallows the compression of the response of the proxy request based on the request and the response. You can use the following parameters:

So in the preceding example (expired no-cache no-store private auth) it is clear that the compression is enabled when the Expires header prevents caching, when the Cache-Control contains no-cache, no-store, or private, and when there is an Authorization header present. This allows tremendous control on how the compression is delivered to the client's browser.

Nginx allows you to do pretty interesting things with error pages. Following are some example configurations which can be placed within the HTTP or server section.

We are also going to define a named location using the "@" prefix after location. These locations are not used during the normal processing of any request and are intended to only process internally redirected requests.

location @fallback (
    proxy_pass http://backend;
)
error_page   404          /404.html; 
error_page   502 503 504  /50x.html; 
error_page   403          http://example1.com/forbidden.html; 
error_page   404          = @fallback; 
error_page 404 =200 /.empty.gif; 

The first example allows you to map a simple 404 page to a simple HTML. The next example allows the mapping of various application error codes to another generic application error HTML page. You can also map the error page to some other external site all together (http://example1.com/forbidden.html). The fourth example allows you to map the page to another location, defined as @fallback. The last example is interesting as it actually allows you to change the response code to a 200 (HTTP OK). This is useful in situations where you have excessive 404 pages on the site, and would prefer not sending a 404 back as reply, but a 200 with a very small GIF file in return.

You can utilize this very effectively to give the end user a better experience when they inadvertently reach dead ends and application errors on your site.

If you do not set these error pages correctly, you will get the default Nginx error pages which may not be useful to the user and may turn them away.