Book Image

Nginx Module Extension

By : Usama Dar
Book Image

Nginx Module Extension

By: Usama Dar

Overview of this book

<p>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.</p> <p>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.</p> <p>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.</p> <p>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.</p>
Table of Contents (12 chapters)

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:

./configure
make
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

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

   ./configure
       --sbin-path=/usr/local/nginx/nginx
       --conf-path=/usr/local/nginx/nginx.conf
       --pid-path=/usr/local/nginx/nginx.pid
       --with-http_ssl_module
       --with-pcre=../pcre-4.4
       --with-zlib=../zlib-1.1.3

Tip

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.

Debugging

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