NGINX was first conceived to be an HTTP server. It was created to solve the C10K problem, described by Daniel Kegel on http://www.kegel.com/c10k.html, in designing a web server to handle 10,000 simultaneous connections. NGINX can do this through its event-based connection-handling mechanism and will use the OS-appropriate event mechanism in order to achieve this goal.
Before we begin exploring how to configure NGINX, we will first install it. This chapter details how to install NGINX and how to get the correct modules installed and configured. NGINX is modular by design and there is a rich community of third-party module developers who have added functionality to the core NGINX server by creating modules that can be compiled into the server and installed along with it.
In this chapter, we will cover the following topics:
Installing NGINX using a package manager
Installing NGINX from source
Configuring for a web or mail service
Configuring SSL support
Enabling various modules
Finding and installing third-party modules
Adding support for Lua
Putting it all together
Chances are that your operating system of choice already provides nginx as a package. Installing it is as simple as using your package manager's commands:
Linux (deb-based)
sudo apt-get install nginxLinux (rpm-based)
sudo yum install nginxFreeBSD
sudo pkg_install -r nginx
Note
The sudo command is representative of what you need to execute on your operating system to achieve superuser (root) privileges. If your operating system supports
role-based access control (RBAC), then you would use a different command, such as pfexec, to achieve the same goal.
These commands will install NGINX into standard locations, specific to your operating system. This is the preferred installation method if you need to use your operating system's packages.
The NGINX core team also provides binaries of the stable version, available from http://nginx.org/en/download.html. Users of distributions without an nginx package (such as CentOS) can use the following instructions to install pre-tested and pre-compiled binaries.
Add the NGINX repository to your yum configuration by creating the following file:
sudo vi /etc/yum.repos.d/nginx.repo [nginx] name=nginx repo baseurl=http://nginx.org/packages/centos/7/$basearch/ gpgcheck=0 enabled=1
Then install nginx by executing the following command:
sudo yum install nginx
Alternative instructions for installing an nginx-release package are available at the preceding URL.
Let's install NGINX on Debian using the following steps:
Install the NGINX signing key by downloading it from http://nginx.org/keys/nginx_signing.key and adding it to the apt keyring:
sudo apt-key add nginx_signing.keyAppend the nginx.org repository to the end of
/etc/apt/sources.list:vi /etc/apt/sources.list deb http://nginx.org/packages/debian/ jessie nginx deb-src http://nginx.org/packages/debian/ jessie nginx
Then install
nginxby executing the following command:sudo apt-get update sudo apt-get install nginx
If your operating system does not include nginx in its list of available packages, the version is too old for what you would like to do, the packages at nginx.org don't serve your needs, you would like to use the development release of NGINX, or if you want to enable/disable specific modules, then compiling NGINX from source is the only other option.
NGINX downloads are available for two separate branches of NGINX code—mainline and stable. The mainline branch is the one in which active development is taking place. Here is where new features will be found and integrated before finding their way into the stable branch. When a mainline version is released, it has undergone the same QA and a similar set of functional tests as the stable branch, so either branch may be used on production systems. The major difference between the two branches lies in the support of third-party modules. The internal API may change in the mainline release, whereas it stays the same on the stable branch, so backward compatibility for third-party modules is only available for stable releases.
In order to compile NGINX from source, certain requirements need to be met on your system. Besides a compiler, you also need the OpenSSL and Perl Compatible Regular Expressions (PCRE) libraries and development headers if you want to enable SSL support and be able to use the rewrite module, respectively. The rewrite module is enabled by default, so if you don't have PCRE libraries and headers, you'll need to disable the rewrite module during the configuration phase. Depending on your system, these requirements may already be met in the default installation. If not, you will need to both locate the appropriate package and install it, or download the source, unpack it, and point NGINX's configure script to this location.
NGINX will attempt to build a dependent library statically if you include a --with-<library>=<path> option to configure. You might do this if you want to ensure that NGINX is not dependent on any other part of the system and/or would like to squeeze that extra bit of performance out of your nginx binary. If you are using features of external libraries that are only available from a certain version onwards (for example, the next protocol negotiation TLS extension available from OpenSSL Version 1.0.1), then you have to specify the path to the unpacked sources of that particular version.
There are other, optional, packages that you can provide support for, if you like. These include MD5 and SHA-1 hashing algorithm support, zlib compression, and libatomic library support. The hashing algorithms are used in many places in NGINX, for example, to compute the hash of a URI to determine a cache key. The zlib compression library is used for delivering gzipped content. If the atomic_ops library is available, NGINX will use its atomic memory update operations to implement high-performance memory-locking code.
NGINX can be downloaded from http://nginx.org/en/download.html. Here you will find the source of either branch in .tar.gz, or .zip format. Unpack the archive into a temporary directory as follows:
$ mkdir $HOME/build $ cd $HOME/build && tar xzf nginx-<version-number>.tar.gz
Configure it using the following command:
$ cd $HOME/build/nginx-<version-number> && ./configure
And compile it as follows:
$ make && sudo make install
When compiling your own nginx binary, you are much more free to include only what you need. Can you already say under which user NGINX should run? Do you want to specify the default log file locations so that they don't need to be explicitly set in the configuration? The following table of configure options will help you design your own binary. These are options that are valid for NGINX, independent of which module is activated.
You are also able to compile with optimizations that you may not get in a packaged installation. This is where the following options can be especially useful:
NGINX is unique among high-performing web servers in that it was also designed to be a mail proxy server. Depending on your goals in building NGINX, you can configure it for web acceleration, a web server, a mail proxy, or all three. It may be beneficial to have one package that you can install on any server in your infrastructure and be able to set NGINX's role through configuration, or it may serve your needs better to have a slimmed-down binary to use in high-performance environments where every extra KB counts.
The following table specifies configuration options that are unique to the mail module.
For a typical mail proxy, I would recommend configuring NGINX as follows:
$ ./configure --with-mail --with-mail_ssl_module --with-openssl=${BUILD_DIR}/openssl-1.0.1p
SSL/TLS is needed nowadays on almost every mail installation and not having it enabled on a mail proxy robs users of expected functionality. I've recommended compiling OpenSSL statically so that there are no dependencies on the operating system's OpenSSL library. This does mean, though, that you will have to be vigilant and ensure that your statically-compiled OpenSSL is kept up-to-date and rebuild your binary when necessary. The BUILD_DIR variable referenced in the preceding command would of course have to be set beforehand.
The following table shows what configuration options are available to the http module, from activating the Perl module to specifying the location of temporary directories.
NGINX uses the OpenSSL Project for TLS/SSL protocols. More information about this Open Source toolkit can be found at https://www.openssl.org. Support for SSL can be had from either the OS or directly from a separate copy of the toolkit. If you use either --with-http_ssl_module or --with-mail_ssl_module without --with-ssl, you're using the OpenSSL library that is installed on the machine where you executed the configure command. If you'd like to compile against a specific version of OpenSSL, download the distribution, unpack it in a directory, and then specify the path to that directory as the argument to --with-openssl. Use the --with-openssl-opt option to specify additional build options for OpenSSL itself.
For example, to build NGINX with an OpenSSL that has optimized elliptic curves, you would use a command such as the following:
$ ./configure --with-http_ssl_module --with-openssl=${BUILD_DIR}/openssl-1.0.1p --with-openssl-opt=enable-ec_nistp_64_gcc_128
Besides the http and mail modules, there are a number of other modules included in the NGINX distribution. These modules are not activated by default, but may be enabled by setting the appropriate configuration option:
--with-<module-name>_module
As you can see, these are all modules that build upon the http module, providing extra functionality. Enabling the modules at compile time should not affect runtime performance at all. Using the modules later in the configuration is where performance may be impacted.
I would therefore recommend the following configure options for a web accelerator/proxy:
$ ./configure --with-http_ssl_module --with-http_realip_module --with-http_geoip_module --with-http_stub_status_module --with-openssl=${BUILD_DIR}/openssl-1.0.1p
And the following for a web server:
$ ./configure --with-http_stub_status_module
The difference lies in where NGINX will be faced with clients. The web acceleration role takes care of terminating SSL requests as well as dealing with proxied clients and making decisions based on where a client came from. The web server role only needs to provide default file serving capability.
I would recommend always enabling the stub_status module, as it provides a means of gathering metrics on how your NGINX is performing.
There are also a number of http modules that are normally activated, but may be disabled by setting the appropriate configuration option --without-<module-name>_module. If you have no use for these modules in your configuration, you can safely disable them.
As with many open source projects, there is an active developer community surrounding NGINX. Thanks to NGINX's modular nature, this community is able to develop and publish modules to provide additional functionality. They cover a wide range of applications, so it pays to take a look at what is available before embarking on developing your own module.
The procedure for installing a third-party module is fairly straightforward:
Locate the module you would like to use (either search on https://github.com or see http://wiki.nginx.org/3rdPartyModules).
Download the module.
Unpack the source.
Read the
READMEfile, if included. See if there are any dependencies that you will need to install.Configure NGINX to use the module as follows:
./configure --add-module=<path>
This procedure will give you an nginx binary with the additional functionality of that module.
Keep in mind that many third-party modules are of an experimental nature. Test using a module first before rolling it out on production systems and remember that the mainline releases of NGINX may have API changes that can cause problems with third-party modules.
Special mention should be made here of the ngx_lua third-party module. The ngx_lua module serves to enable Lua instead of Perl as a configuration time embedded scripting language. The great advantage this module has over the perl module is its non-blocking nature and tight integration with other third-party modules. The installation instructions are fully described at https://github.com/openresty/lua-nginx-module#installation. We will be using this module as an example of installing a third-party module in the next section.
Now that you have gotten a glimpse at what all the various configuration options are for, you can design a binary that precisely fits your needs. The following example specifies the prefix, user, group, paths, disables some modules, enables some others, and includes a couple of third-party modules:
$ export BUILD_DIR=`pwd` $ export NGINX_INSTALLDIR=/opt/nginx $ export VAR_DIR=/home/www/tmp $ export LUAJIT_LIB=/opt/luajit/lib $ export LUAJIT_INC=/opt/luajit/include/luajit-2.0 $ ./configure \ --prefix=${NGINX_INSTALLDIR} \ --user=www \ --group=www \ --http-client-body-temp-path=${VAR_DIR}/client_body_temp \ --http-proxy-temp-path=${VA R_DIR}/proxy_temp \ --http-fastcgi-temp-path=${VAR_DIR}/fastcgi_temp \ --without-http_uwsgi_module \ --without-http_scgi_module \ --without-http_browser_module \ --with-openssl=${BUILD_DIR}/../openssl-1.0.1p \ --with-pcre=${BUILD_DIR}/../pcre-8.32 \ --with-http_ssl_module \ --with-http_realip_module \ --with-http_sub_module \ --with-http_flv_module \ --with-http_gzip_static_module \ --with-http_gunzip_module \ --with-http_secure_link_module \ --with-http_stub_status_module \ --add-module=${BUILD_DIR}/ngx_devel_kit-0.2.17 \ --add-module=${BUILD_DIR}/ngx_lua-0.7.9
Following a lot of output showing what configure was able to find on your system, a summary is printed out as follows:
Configuration summary + using PCRE library: /home/builder/build/pcre-8.32 + using OpenSSL library: /home/builder/build/openssl-1.0.1p + md5: using OpenSSL library + sha1: using OpenSSL library + using system zlib library nginx path prefix: "/opt/nginx" nginx binary file: "/opt/nginx/sbin/nginx" nginx configuration prefix: "/opt/nginx/conf" nginx configuration file: "/opt/nginx/conf/nginx.conf" nginx pid file: "/opt/nginx/logs/nginx.pid" nginx error log file: "/opt/nginx/logs/error.log" nginx http access log file: "/opt/nginx/logs/access.log" nginx http client request body temporary files: "/home/www/tmp/ client_body_temp" nginx http proxy temporary files: "/home/www/tmp/proxy_temp" nginx http fastcgi temporary files: "/home/www/tmp/fastcgi_temp"
As you can see, configure found all the items we were looking for, and acknowledged our preferences for certain paths. Now you can build your nginx and install it, as mentioned at the beginning of the chapter.
This chapter has introduced you to the various modules available for NGINX. By compiling your own binary, you are able to tailor what functionality your nginx will provide. Building and installing software will not be new to you, so not a lot of time was spent on creating a build environment or making sure that all dependencies were present. An NGINX installation should be one that fits your needs, so feel free to enable or disable modules as you see fit.
Next up, we will present an overview of basic NGINX configuration, to get a feel for how to configure NGINX in general.
