Nginx Web Services: Configuration and Implementation

Exclusive offer: get 50% off this eBook here
Nginx 1 Web Server Implementation Cookbook

Nginx 1 Web Server Implementation Cookbook — Save 50%

Over 100 recipes to master using the Nginx HTTP server and reverse proxy

$23.99    $12.00
by Dipankar Sarkar | July 2011 | Open Source

This article deals with the basics of Nginx configuration and implementation. By the end of it you should be able to compile Nginx on your machine and create virtual hosts.

In this article by Dipankar Sarkar, author of Nginx 1 Web Server Implementation Cookbook, we will cover:

  • Installing new modules and compiling Nginx
  • Running Nginx in debug mode
  • Easy reloading of Nginx using the CLI
  • Splitting configuration files for better management
  • Setting up multiple virtual hosts
  • Setting up a default catch-all virtual host
  • Using wildcards in virtual hosts

 

Nginx 1 Web Server Implementation Cookbook

Nginx 1 Web Server Implementation Cookbook

Over 100 recipes to master using the Nginx HTTP server and reverse proxy

        Read more about this book      

(For more resources on Nginx, see here.)

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.

    Nginx 1 Web Server Implementation Cookbook

  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:

Nginx 1 Web Server Implementation Cookbook

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:

Nginx 1 Web Server Implementation Cookbook

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:

Nginx 1 Web Server Implementation Cookbook

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:

    Nginx 1 Web Server Implementation Cookbook

    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):

    Nginx 1 Web Server Implementation Cookbook

  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.

 

Nginx 1 Web Server Implementation Cookbook Over 100 recipes to master using the Nginx HTTP server and reverse proxy
Published: May 2011
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:

 

        Read more about this book      

(For more resources on Nginx, see here.)

Splitting configuration files for better management

By default, when you are installing Nginx you get this one monolithic configuration file which contains a whole lot of sample configurations. Due to its extremely modular and robust designing, Nginx allows you to maintain your configuration file as a set of multiple linked files.

How to do it...

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:

  • nginx.conf: The central configuration file remains
  • fcgi.conf: This will contain all the FastCGI configurations
  • sites-enabled/: This directory will contain all the sites that are enabled (much like Apache2's sites-enabled directory)
  • sites-available/: This directory will contain all the sites that are not active, but available (again, much like Apache2's sites-available)
  • sites-enabled/site1.conf: This is the sample virtual host configuration of the sample PHP site

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/xjavascript
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.

 

Setting up multiple virtual hosts

Usually any web server hosts one or more domains, and Nginx, like any good web server, allows you to easily configure as many virtual hosts as you want.

How to do it...

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;
}
}

How it works...

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).

There's more...

Here is a quick checklist to get you started:

  1. Create a simple directory with the HTML files.
  2. Create a simple configuration file containing the virtual host configuration for www.example1.com.
  3. Reload Nginx.
  4. Point your DNS server to the correct server running Nginx.
  5. Load www.example1.com.

 

Setting up a default catch-all virtual host

Once you are comfortable setting up the virtual hosts, you will end up in a situation where you have a lot of domains pointing at the IP. In addition to the domains, you would also have the web server responding to the IP addresses it hosts, and many other unused subdomains of the domains pointing at it. We can take a look at this with a simple example, so you have http://www.example1.com pointing at the IP address, you have configured a virtual host to handle the domains www.example1.com and example1.com. In such a scenario, when the user types in abc.example1.com or an IP address the web server will not be able to serve the relevant content (be it 404 or some other promotional page).

How to do it...

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;
}
}

How it works...

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.

 

Using wildcards in virtual hosts

Imagine a situation where you need to create an application that needs to serve dynamic pages on subdomains! In that case, you will need to set up a virtual host in Nginx that can utilize wildcards. Nginx has been made ground up to handle such a scenario. So let's take our favorite example of http://www.example1.com. Let's say you are building an application that needs to handle the various subdomains such as a.example1.com, b.example1.com, and so on. The following configuration would let the application behind handle all these various subdomains.

How to do it...

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 / {
........
}
}

How it works...

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.

Summary

In this article we learnt the basics of Nginx configuration and implementation. We also saw how to compile Nginx on your machine and also how to create virtual hosts.


Further resources on this subject:


Nginx 1 Web Server Implementation Cookbook Over 100 recipes to master using the Nginx HTTP server and reverse proxy
Published: May 2011
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:

About the Author :


Dipankar Sarkar

Dipankar Sarkar is a web and mobile entrepreneur. He has a Bachelor’s degree in Computer Science and Engineering from Indian Institute of Technology, Delhi. He is a firm believer in the Open source movement and has participated in the Google Summer of Code, 2005-06 and 2006-07. He has conducted technical workshops for Windows mobile and Python at various technical meetups. He recently took part in the Startup Leadership Program, Delhi Chapter.

He has worked with Slideshare LLC, one of the world’s largest online presentation hosting and sharing services as an early engineering employee. He has since then worked with Mpower Mobile LLC, a mobile payment startup and Clickable LLC, a leading search engine marketing startup. He was a co-founder at Kwippy, which was one of the top micro-blogging sites. He is currently working in the social TV space and has co-founded Jaja.

He has previously authored “Nginx web server implementation cookbook” and this is his second book on Nginx. This book “Mastering Nginx” is a more structured approach to how one can learn and master Nginx, with practical examples and strategies.

Books From Packt


Nginx HTTP Server
Nginx HTTP Server

Squid Proxy Server 3.1: Beginner's Guide
Squid Proxy Server 3.1: Beginner's Guide

Plone 3.3 Site Administration
Plone 3.3 Site Administration

Hacking Vim 7.2
Hacking Vim 7.2

Cacti 0.8 Beginner's Guide
Cacti 0.8 Beginner's Guide

FreeSWITCH 1.0.6
FreeSWITCH 1.0.6

OpenVPN 2 Cookbook
OpenVPN 2 Cookbook

Tcl 8.5 Network Programming
Tcl 8.5 Network Programming


No votes yet

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
1
C
3
u
r
L
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software