Nginx Web Services: Configuration and Implementation

Nginx 1 Web Server Implementation Cookbook

Installing new modules and compiling Nginx

Today, most softwares are designed to be modular and extensible. Nginx, with its great community, has an amazing set of modules out there that lets it do some pretty interesting things. Although most operating system distributions have Nginx binaries in their repositories, it is a necessary skill to be able to compile new, bleeding edge modules, and try them out. Now we will outline how one can go about compiling and installing Nginx with its numerous third-party modules.

How to do it...

1. The first step is to get the latest Nginx distribution, so that you are in sync with the security and performance patches (http://sysoev.ru/nginx/nginx-0.7.67.tar.gz). Do note that you will require sudo or root access to do some of the installation steps going ahead.

   

2. Un-tar the Nginx source code. This is simple, you will need to enter the following command:

   tar -xvzf nginx-0.7.67.tar.gz

3. Go into the directory and configure it. This is essential, as here you can enable and disable the core modules that already come with Nginx. Following is a sample configure command:

   ./configure --with-debug 
   --with-http_ssl_module 
   --with-http_realip_module 
   --with-http_ssl_module 
   --with-http_perl_module 
   --with-http_stub_status_module

   
   You can figure out more about what other modules and configuration flags use:

   ./configure --help

4. If you get an error, then you will need to install the build dependencies, depending on your system. For example, if you are running a Debian based system, you can enter the following command:

   apt-get build-dep nginx

   
   This will install all the required build dependencies, like PCRE and TLS libraries.

5. After this, you can simply go ahead and build it:

   sudo make install

6. This was the plain vanilla installation! If you want to install some new modules, we take the example of the HTTP subscribe-publish module.
7. Download your module (http://pushmodule.slact.net/downloads/nginx_http_push_module-0.692.tar.gz).
8. Un-tar it at a certain location:/path/to/module.
9. Reconfigure Nginx installation:

   ./configure ..... --add-module=/path/to/module

   
   The important part is to point the –add-module flag to the right module path. The rest is handled by the Nginx configuration script.

10. You can continue to build and install Nginx as shown in step 5.

    sudo make install

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

There's more...

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.

Running Nginx in debug mode

Nginx is a fairly stable piece of software which has been running in production for over a decade and has built a very strong developer community around it. But, like all software there are issues and bugs which crop up under the most critical of situations. When that happens, it's usually best to reload Nginx with higher levels of error logging and if possible, in the debug mode.

How to do 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 precompiled 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];

Downloading the example code
You can download the example code files here

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:

There's more...

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.

Easy reloading of Nginx using the CLI

Depending on the system that you have, it will offer one clean way of reloading your Nginx setup

• Debian based: /etc/init.d/Nginx reload
• Fedora based: service Nginx reload
• FreeBSD/BSD: service Nginx reload
• Windows: Nginx -s reload

All the preceding commands reload Nginx; they send a HUP signal to the main Nginx process. You can send quite a few control signals to the Nginx master process, as outlined in the following table. These let you manage some of the basic administrative tasks:

How to do it...

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

1. Open a terminal on your system. Most UNIX-based systems already have fairly powerful terminals, while you can use PuTTY on Windows systems.
2. Type in ps auxww | grep nginx. This will output something as shown in the following screenshot:

   

   
   If nothing comes, then it means that Nginx is not running on your system.

3. If you get the preceding output, then you can see the master process and the two worker processes (it may be more, depending on your worker_processes configuration). The important number is 3322, which is basically the PID of the master process.
4. To reload Nginx, you can issue the command kill -HUP <PID of the nginx master process>. In this case, the PID of the master process is 3322. This will basically read the configurations again, gracefully close your current connections, and start new worker processes. You can issue another ps auxww | grep nginx to see new PIDs for the worker processes (4582,4583):

   

5. If the worker PIDs do not change it means that you may have a problem while reloading the configuration files. Go ahead and check the Nginx error log.

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.