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.
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.
CentOS, RHEL, and Scientific Linux, each populate the
$releasever variable differently. Therefore, depending on your OS version, replace
5 (for 5.x) or
6 (for 6.x). Therefore,
baseurl for 6.x would look like
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:
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
# portsnap fetch update
# 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.
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:
cd c:\ unzip nginx-1.2.3.zip ren nginx-1.2.3 nginx cd nginx start nginx
nginx -s [ stop | quit | reopen | reload ]
For problems, look in the
c:\nginx\logs\error.log file or in
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:
Read-only Mercurial repositories:
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
Autotools (automake and autoconf)
PCRE (Perl Compatible Regular Expressions)
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.
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.
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
The following section is extracted from the Nginx online wiki.
--prefix=path: It is set to the
/usr/local/nginxdirectory 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.
--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
fastcgiconfiguration 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
--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_logdirective 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
userdirective in the configuration file.
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
poll() methods as well. The following options affect this behavior:
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
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
--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.
--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.
./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
When using the system PCRE library under FreeBSD, the following options should be specified:
--with-ld-opt="-L /usr/local/lib" \
If the number of files supported by
select() needs to be increased, it can also be specified like this:
--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
-ggdb and recommended compiler optimization level of
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
CFLAGS="-g -O0" ./configure ...
www-servers/nginx ~x86 (or ~amd64, etc)
X86/ 64 builds for Solaris are available on http://joyent.com/blog/ok-nginx-is-cool
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
As a root user, run the Nginx server using
You will see the
nginx.pidfile 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
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.