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.
To add the Nginx yum repository, create a file named /etc/yum.repos.d/nginx.repo and paste one of the following configurations:
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/.
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:
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.
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:
Installation:
cd c:\ unzip nginx-1.2.3.zip ren nginx-1.2.3 nginx cd nginx start nginx
Control:
nginx -s [ stop | quit | reopen | reload ]
For problems, look in the c:\nginx\logs\error.log file or in EventLog.
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.
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.
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.
--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.--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 isprefix/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 samplefastcgiconfiguration 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 namedprefix/logs/nginx.pid.--error-log-path=path: This option allows you to specify the location of the error log. By default, the file is namedprefix/logs/error.log. You can set this value tostderr. 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 namedprefix/logs/access.log. Like other options, this can be changed anytime by providing theaccess_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 isnobody. You can change it later through theuserdirective in the configuration file.--group=name: This sets the name of the group used to run the worker processes. The default group name isnobody. You can change this through theuserdirective 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 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.
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 disablesngx_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.
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"
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 ...
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.keywordswww-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
Following are the steps to verify that Nginx has been installed:
Once you have successfully compiled and built Nginx, verify it by running the
nginx -Vcommand.As a root user, run the Nginx server using
prefix/ nginx/sbin/nginx.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/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.
