About this book

Companies can solve significant scaling issues thanks to switching their web platforms to Nginx. A popular web server for building web infrastructure, Nginx transparently and effectively enables the growth of the largest sites on the Internet today, on top of being free and open source.

This book is a practical reference providing you with everything you need to know about Nginx module extensions. You will learn how to write powerful and flexible configuration files and your own modules, as well as gaining knowledge about Nginx’s modular architecture, available modules, and their intricate details.

Nginx Module Extension starts by teaching you to compile the Nginx source on multiple platforms. Then you will learn the synopsis, directives, and practical examples of the core, optional, and third party Nginx modules before familiarizing yourself with Nginx internals, enabling you to write custom modules.

You will learn about the flexibility of the Nginx configuration and how to enable and disable various options while building from the source. You will learn to customize the Main and Events module to fine-tune the web server performance, and you will also learn about standard and optional HTTP modules like GeoIP, Gzip, Access Control, and using SSL, along with an exploration of PostgreSQL, MySQL, and Memcached modules. Finally you will learn internals like module chaining and will see sample code and a line-by-line walkthrough demonstrating how to write your own module.

Publication date:
December 2013


Chapter 1. Installing Nginx Core and Modules from Source

This chapter serves as a quick reference to downloading and installing Nginx using binary and source distribution and compilation options related to different modules and add-ons.

If you are reading this book, you are already familiar with Nginx (pronounced as engine-x). Therefore, we will not spend too much time discussing the basics. However, you will need a working copy of Nginx before proceeding to advanced topics.


Installing binary distribution

Most UNIX and Linux distributions have Nginx included in their package manager repositories. Use package manager commands on your platform to install it. For example, use apt-get on Ubuntu or Debian, and emerge on Gentoo. For Red Hat, Fedora, or CentOS, see the instructions that follow.

You can find binary installation instructions for different platforms such as Red Hat and Ubuntu on the Nginx installation wiki at http://wiki.nginx.org/Install. However, we will briefly describe the process here, quoting from the wiki.

Red Hat, Fedora, and CentOS

To add the Nginx yum repository, create a file named /etc/yum.repos.d/nginx.repo and paste one of the following configurations:

  • For CentOS:

    name=nginx repo
  • For RHEL:

    name=nginx repo

CentOS, RHEL, and Scientific Linux, each populate the $releasever variable differently. Therefore, depending on your OS version, replace $releasever with 5 (for 5.x) or 6 (for 6.x). Therefore, baseurl for 6.x would look like baseurl=http://nginx.org/packages/rhel/6/$basearch/.

Official Debian/Ubuntu packages

Append the following lines to the /etc/apt/sources.list file, and replace the codename with the one appropriate for the release that you are using, for example, Ubuntu 13.10 is codenamed saucy:

  • For Ubuntu 12.10:

    deb http://nginx.org/packages/ubuntu/ saucy nginx
    deb-src http://nginx.org/packages/ubuntu/ saucy nginx

    Please note that when you will run the apt-get update after adding the repository, you will get a GPG error of not being able to verify keys. If this happens and you find it hard to ignore it, do the following:

    wget http://nginx.org/packages/keys/nginx_signing.key
    cat nginx_signing.key | sudo apt-key add -
  • For Debian 6:

    deb http://nginx.org/packages/debian/ squeeze nginx
    deb-src http://nginx.org/packages/debian/ squeeze nginx
  • For Ubuntu PPA: This PPA is maintained by volunteers and is not distributed by nginx.org. It has some additional compiled-in modules, and it may be more fitting for your environment. You can get the latest stable version of Nginx from Nginx PPA on Launchpad: You will require root privileges to execute the following commands.

    • For Ubuntu 10.04 and newer:

      sudo -s
      nginx=stable # use nginx=development for latest development version
      add-apt-repository ppa:nginx/$nginx
      apt-get update 
      apt-get install nginx

      If you get an error about add-apt-repository not existing, you will want to install python-software-properties. For other Debian/Ubuntu based distributions, you can try the lucid variant of the PPA that is the most likely to work on older package sets.

      sudo -s
      nginx=stable # use nginx=development for latest developmentversion
      echo "deb http://ppa.launchpad.net/nginx/$nginx/ubuntu lucidmain" > /etc/apt/sources.list.d/nginx-$nginx-lucid.list
      apt-key adv --keyserver keyserver.ubuntu.com --recv-keysC300EE8C
      apt-get update
      apt-get install nginx


Update the BSD ports tree using the following command:

# portsnap fetch update

Install the web server using the following commands:

# cd /usr/ports/www/nginx
# make install clean

Type the following command to turn the Nginx server on:

echo 'nginx_enable="YES"' >> /etc/rc.conf

To start Nginx, enter:

# /usr/local/etc/rc.d/nginx start


OpenBSD, as of Version 5.1, includes Nginx as part of the base system. This means Nginx comes pre-installed along with all the library dependencies. The version is not always the latest and greatest one. However, this allows you to start migrating Apache applications over to Nginx. In the future, it is expected that the default httpd will be Nginx instead of Apache.

Official Win32 binaries

As of Version 0.8.50 of Nginx, the official Windows binary is now available.

The Windows version is provided as binary-only due to the current build process, which uses WineTools at the moment. You will not be able to compile a Windows version from source. Once you download the Windows ZIP file, perform the following steps:

  1. Installation:

    cd c:\
    unzip nginx-1.2.3.zip
    ren nginx-1.2.3 nginx
    cd nginx
    start nginx
  2. Control:

    nginx -s [ stop | quit | reopen | reload ]

For problems, look in the c:\nginx\logs\error.log file or in EventLog.


Installing source distribution

Nginx binary packages are outdated and usually have an older version. If the binaries on your platform are not the latest and up-to-date, you can download the source from http://nginx.org/en/download.html. At the time of writing this chapter, Version 1.4.3 is the stable downloadable version.

You can also checkout or clone the latest source.

Read-only Subversion repositories:

code: svn://svn.nginx.org/nginx

Read-only Mercurial repositories:

site: http://hg.nginx.org/nginx.org

After you have downloaded the source archive, un-tar it and use the following standard build commands to build a standard binary:

sudo make install

This places the Nginx binary under user/local. However, you can override this path through configure options.

Nginx library dependencies

If you want to build Nginx from source, the following libraries are needed at the minimum:

  • GCC

  • Autotools (automake and autoconf)

  • PCRE (Perl Compatible Regular Expressions)

  • zlib

  • OpenSSL

You also have the option to disable the dependency on PCRE, zlib, and OpenSSL by disabling the compilation of rewrite, gzip, and ssl modules. These modules are enabled by default.

Configuring options

Compile-time options are provided through configure. You can also find documentation related to the configure-time options online at http://wiki.nginx.org/InstallOptions.

The configure command defines various aspects of the system including the methods that Nginx is allowed to use for connection processing. At the end, it creates a makefile. You can use ./configure --help to see a full list of options supported by the configure command.

The following section is extracted from the Nginx online wiki.

Files and permissions

  • --prefix=path: It is set to the /usr/local/nginx directory by default. The path specified here is the root folder for keeping the server files. This includes the executable files, server log files, configuration files, and html documentation.

  • --sbin-path=path: The default Nginx executable name is /sbin/nginx. You can change the name using this configure option.

  • --conf-path=path: The default for this option is prefix/conf/nginx.conf. This is the default path for the Nginx configuration file. This file, as you will learn later, is used to configure everything about the Nginx server. The path also contains a number of other configuration files such as a sample fastcgi configuration file and character-set maps. You can always change this path later on in the configuration file.

  • --pid-path=path: This option allows you to change the name of the pid file. The pid files are used by various utilities (including start/stop scripts) to determine if the server is running. Normally, it is a plain text file with the server process ID in it. By default, the file is named prefix/logs/nginx.pid.

  • --error-log-path=path: This option allows you to specify the location of the error log. By default, the file is named prefix/logs/error.log. You can set this value to stderr. It will redirect all the error messages to the standard error on your system. Normally, this will be your console or the screen.

  • --http-log-path=path: This sets the name of the log file where all HTTP requests are logged. By default, the file is named prefix/logs/access.log. Like other options, this can be changed anytime by providing the access_log directive in the configuration file.

  • --user=USER: This sets the username that will be used to run the Nginx worker processes. You should make sure that this is an unprivileged or non-root user. The default user name is nobody. You can change it later through the user directive in the configuration file.

  • --group=name: This sets the name of the group used to run the worker processes. The default group name is nobody. You can change this through the user directive in the configuration file.

The Event loop

One of the reasons for Nginx being so fast and stable is its ability to use event-based functions. Input/Output. The event-based coding ensures maximum performance within a single core by allowing it to be non-blocking. However, event-based code needs the underlying platform support such as kqueue (FreeBSD, NetBSD, OpenBSD, and OSX), epoll (Linux), and /dev/poll (Solaris, HPUX).In cases where these methods are not available, Nginx can work with more traditional select() and poll() methods as well. The following options affect this behavior:

  • --with-select_module

  • --without-select_module

These enable or disable building of a module that allows the server to work with the select() method. This module is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, rtsig, or /dev/poll.

  • --with-poll_module

  • --without-poll_module

These enable or disable the building of a module that allows the server to work with the poll() method. This module is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, rtsig, or /dev/poll.

Optional modules

The optional modules are as follows:

  • --without-http_gzip_module: This option allows you to disable over-the-wire compression. This can be quite useful if you are sending or receiving large text documents over HTTP. However, if you don't want to build this compression into Nginx binary, or you don't have access to the zlib library that is required to enable this support, you can disable it using this option.

  • --without-http_rewrite_module: This option allows you to disable the HTTP rewrite module. The HTTP rewrite module allows you to redirect HTTP requests by modifying URIs that match a given pattern. You need the PCRE library to enable this module.

  • --without-http_proxy_module: This disables ngx_http_proxy_module. The proxy module allows you to pass the HTTP request to another server.

  • --with-http_ssl_module: This enables the SSL support in the server. This is not enabled by default and you need OpenSSL in order to build SSL support in the Nginx binary.

  • --with-pcre=path: If you have downloaded the PCRE source on your machine, you can provide its path through this parameter. Nginx will automatically build this library before building the Nginx server. Please make sure that the version of PCRE source is 4.4 or higher.

  • --with-pcre-jit: This builds the PCRE library with the "just-in-time compilation" support. This is significantly to improve the pattern matching or rewriting speed by converting the regular expressions into machine code.

  • --with-zlib=path: If you have already downloaded the zlib library source, you can provide its path here. Nginx will build the zlib library before building the server binary. Please make sure that the source version is 1.1.3 or higher.

Compilation controls

The compilation controls are as follows:

  • --with-cc-opt=parameters: Additional options for the CFLAGS variable

  • --with-ld-opt=parameters: Additional parameters for the linker (LD_LIBRAY_PATH) that you should provide --with-ld-opt="-L /usr/local/lib when building on FreeBSD


Example of parameters usage (all of this needs to be typed in one line):



When using the system PCRE library under FreeBSD, the following options should be specified:

  • --with-ld-opt="-L /usr/local/lib" \

  • --with-cc-opt="-I /usr/local/include"

If the number of files supported by select() needs to be increased, it can also be specified like this:

  • --with-cc-opt="-D FD_SETSIZE=2048"

The Custom module

One of the great strengths of Nginx is its modular design. You are able to hook in third-party modules or modules that you write yourself.

--add-module=path compiles the module located at path into Nginx binary. You can find a list of third-party modules available for Nginx at http://wiki.nginx.org/3rdPartyModules.


--with-debug enables debug logging. This option is already enabled in the Windows binary. Once you compile Nginx with this option, you then have to set the debug level with the error_log directive in the configuration file, and so on:

error_log /path/to/log debug

In addition to debug logging, you can also attach a debugger to a running version of Nginx. If you intend to do so, enable the debugging symbols in the Nginx binary. Compile with -g or -ggdb and recommended compiler optimization level of O0 or O2 (this makes the debugger output easier to understand). The optimization level O3 auto-vectorizes the code and introduces certain other optimizations that make debugging harder. Set the CFLAGS environment variable as follows and run configure:

CFLAGS="-g -O0" ./configure ...

Installing on other platforms

Let us install Nginx on other platforms such as the following:

  • Gentoo: To get the latest version of Nginx, add a platform mask in your portage configuration file /etc/portage/package.keywords

    www-servers/nginx ~x86 (or ~amd64, etc)
  • X86/ 64 builds for Solaris are available on http://joyent.com/blog/ok-nginx-is-cool

  • MacOSX: Install Xcode or Xcode command-line tools to get all the required compilers and libraries

  • A detailed account of how to resolve dependencies like PCRE and others is described in detail for Solaris 10 u5 http://wiki.nginx.org/Installing_on_Solaris_10_u5

Verifying your Nginx installation

Following are the steps to verify that Nginx has been installed:

  1. Once you have successfully compiled and built Nginx, verify it by running the nginx -V command.

  2. As a root user, run the Nginx server using prefix/ nginx/sbin/nginx.

  3. You will see the nginx.pid file once the server is running. The location of this file depends on the option that you provided while running the configure script. On Ubuntu, the default location is /var/run/nginx.pid.

You can reload the Nginx configuration once you edit the nginx.conf file. To do this, send SIGNUP to the main process. The PID of this process is in the nginx.pid file. The following command will reload the configuration on Ubuntu:

kill -HUP `cat var/run/nginx.pid


In this chapter, we learned how to download binary and source releases of Nginx and install binary releases. We have also learned how to compile and install Nginx from source, how to override installation paths and other properties using configure options, how to compile Nginx with debugging symbols, and finally, how to verify the installation.

In the next chapter, we will learn more about configuration of core Nginx modules.

About the Author

  • Usama Dar

    Usama Dar is a seasoned software developer and architect. During his 14 years' career, he has worked extensively with PostgreSQL and other database technologies. He worked on PostgreSQL internals extensively while he was working for EnterpriseDB. Currently, he lives in Munich where he works for Huawei's European Research Center. He designs the next generation of high-performance database systems based on open source technologies, such as PostgreSQL, which are used under high workloads and strict performance requirements.

    Browse publications by this author

Latest Reviews

(1 reviews total)
Book Title
Access this book and the full library for FREE
Access now