NGINX Cookbook: Over 70 recipes for real-world configuration, deployment, and performance

Different Linux distributions have varying package managers, so we'll briefly cover the installation procedures for the more commonly used ones. If the distribution you use isn't covered here, refer to the official NGINX documentation for further guidance.

[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/mainline/OS/OSRELEASE/$basearch/
gpgcheck=0
enabled=1

yum update
yum install nginx

wget http://nginx.org/keys/nginx_signing.key
apt-key add nginx_signing.key

deb http://nginx.org/packages/mainline/debian/ codename nginx
deb-src http://nginx.org/packages/mainline/debian/ codename nginx

deb http://nginx.org/packages/mainline/ubuntu/ codename nginx
deb-src http://nginx.org/packages/mainline/ubuntu/ codename nginx

apt-get update
apt-get install nginx

Compiling from scratch

Although having the precompiled packages is nice, not all of the modules are available out of the box. NGINX requires you to compile these into the NGINX installation and it's not a simple module like Apache.

You can simply build from source without any of the packaging tools for CentOS or Debian, however, it makes upgrades and compatibility more difficult. By default, user compiled programs will default to /usr/local, which means that any documentation which refers to the package defaults (/usr/etc) will be incorrect.

My preference is to base the build on the official package sources, rather than the plain source code. There aren't many extra steps involved, but it makes the ongoing management much easier. If you're looking for vanilla build instructions (without packages), these are easily available on the web.

Note

These examples require you to have the mainline repositories already installed.

Debian/Ubuntu

On Ubuntu/Debian, install the required build tools:

apt-get install devscripts

This will install quite a few packages on your system, so if you're trying to keep your production environment lean, then I'd recommend that you use a separate build box to complete this.

We can now install the build prerequisites for NGINX:

apt-get build-dep nginx

Once you have the required build dependencies, we can now get a copy of the source code. Again, rather than the plain TAR file, we're going to get the packaged variant so that we can easily build them. Here's how we do it:

mkdir ~/nginxbuild
cd ~/nginxbuild
apt-get source nginx

You should now have a directory with the original TAR file, the Debian description, and any Debian specific patches. The apt-get source command will automatically extract and apply patches, as required, into a source directory.

To build without any changes, enter the directory and create the packages:

cd nginx-1.9.10/
fakeroot debian/rules binary

Compiling the code may take a while, depending on how many processors your workstation or server has. Once it has compiled, you should see two binaries in the parent (nginxbuild) directory. The resulting files should be:

• nginx-dbg_1.9.10-1~jessie_amd64.deb
• nginx_1.9.10-1~jessie_amd64.deb

You can now install NGINX via the newly compiled package:

sudo dpkg -i nginx_1.9.10-1~jessie_amd64.deb

CentOS/RHEL

Like the Debian build process, first we'll need to install the package build tools and the additional Extra Packages For Enterprise Linux (EPEL) repository:

sudo yum install yum-utils epel-release mock

Next, update /etc/yum.repos.d/nginx.repo and add the additional source repository:

[nginx-source]
name=nginx source repo
baseurl=http://nginx.org/packages/mainline/centos/7/SRPMS/
gpgcheck=0 
enabled=1 

In this example, we'll be using a CentOS 7-based release. Refer to the Packages – RHEL/CentOS section for how to modify it for other CentOS versions.

With the updated repository, we then create a directory for the build, and download the Source RPM (SRPM):

mkdir ~/nginxbuild
cd ~/nginxbuild
yumdownloader --source nginx

Next, download the required packages to complete the build:

yum-builddep nginx

Once all of the development packages have been downloaded, we can now extract the files from the SRPM:

rpm2cpio nginx-1.9.10-1.el7.ngx.src.rpm | cpio -idmv

Note

Note that the name of your directory may vary based on the version of NGINX you have installed. For instance, here it is nginx-1.9.10 as I have installed NGINX 1.9.10.

You should see an output of the source files similar to this:

If we want to update the configuration and apply a patch or change one of the defaults, then this can simply be done by editing the files.

We can now rebuild these files from source using mock, which is a tool for building packages. The advantage of mock is that all of the development dependencies are contained within a chrooted environment, so it doesn't clutter your main installation. This chrooted environment can be cleaned and removed without any impact on the host system, which is great if you want repeatable builds.

To build, we run the following command:

mock --buildsrpm --spec ~/nginxbuild/nginx.spec --sources ~/nginxbuild

This generates the SRPMs, and they will be located in the /var/lib/mock/epel-7-x86_64/result directory, along with the associated log files. Now that we have a rebuilt SRPM, we can now compile it. Again, we're going to use mock so that everything is neatly contained:

mock --no-clean --rebuild var/lib/mock/epel-7-x86_64/result/nginx-1.9.11-1.el7.ngx.src.rpm

Depending on your processing power, this may take five minutes or more to complete. Once the build is complete, you should see the resultant binary RPM as well as a debug RPM in the /var/lib/mock/epel-7-x86_64 directory. Here's an example:

-rw-rw-r-- 1 demo mock 159K Feb 10 20:59 build.log
-rw-r--r-- 1 demo mock 889K Feb 10 20:57 nginx-1.9.11-1.el7.ngx.src.rpm
-rw-r--r-- 1 demo mock 803K Feb 10 20:59 nginx-1.9.11-1.el7.ngx.x86_64.rpm
-rw-r--r-- 1 demo mock 3.1M Feb 10 20:59 nginx-debuginfo-1.9.11-1.el7.ngx.x86_64.rpm
-rw-rw-r-- 1 demo mock 45K Feb 10 20:59 root.log
-rw-rw-r-- 1 demo mock 1000 Feb 10 20:59 state.log

Now that we have the new binary file, we can install it via yum:

sudo yum install /var/lib/mock/epel-7-x86_64/result/nginx-1.9.11-1. ngx.x86_64.rpm

Note

It's preferable to use yum over rpm to install the packages, as it can also install any dependencies.

You should now have a fully installed NGINX installation, which you compiled from source.

Testing

Regardless of your installation method, once you have NGINX up and running, you should be able to browse to it via the IP address and/or Fully Qualified Domain Name (FQDN) and see something very similar to what is shown here:

Default NGINX page

To start, stop, and restart NGINX (if installed using official binaries), you can use the standard Linux init systems. There's a very slight variance between the different OS versions, so it's important to ensure you're using the correct command for the correct variant.

Note

As Ubuntu switched to systemd as the default init system from 15.04, make sure you double check the version you're using.

Here's a quick reference table of the available commands:

Some modifications to NGINX will require a full restart, whereas others only need the configuration reloaded. In most instances where a configuration file has been modified, a reload is all which is required. NGINX will fork a new set of worker processes, allowing existing workers to complete and cleanly exit so that there is no downtime.

We can check the NGINX configuration files after changes are made to ensure the syntax is correct. To do this, we run the following:

/usr/sbin/nginx -t

You should see the following if everything is correct:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If you have any errors, double check your configuration for syntax errors on the lines indicated.

By default, NGINX will have two main configuration files. The first is /etc/nginx/nginx.conf, which contains the main server configuration. The second is /etc/nginx/default.conf, which defines a basic site out of the box for you.

Before you make any changes, be 100 percent sure that you understand the implications. Out of the box, NGINX is a highly performant web server which already gives great performance. The age-old programmer's saying that premature optimization is the root of all evil continually rings true here. Simply increasing some figures may lead to increased memory usage, decreased stability, and decreased performance. In Chapter 11, Performance Tuning, we'll go through some of the more advanced areas to tweak, but make sure to hit limits before attempting this.

Here's the default configuration:

user  nginx;
worker_processes 1; 
 
error_log  /var/log/nginx/error.log warn; 
pid        /var/run/nginx.pid; 
 
events { 
    worker_connections  1024; 
} 
 
http { 
    include       /etc/nginx/mime.types; 
    default_type  application/octet-stream; 
 
    log_format  main  '$remote_addr - $remote_user [$time_local] 
     "$request" ' 
    '$status $body_bytes_sent "$http_referer" ' 
    '"$http_user_agent" "$http_x_forwarded_for"'; 
 
    access_log  /var/log/nginx/access.log  main; 
 
    sendfile        on; 
    #tcp_nopush     on; 
 
    keepalive_timeout  65; 
 
    #gzip  on; 
 
    include /etc/nginx/conf.d/*.conf; 
} 

The configuration files have two main components in them—simple directives and block directives. Simple directives are one-line items which are simple name and value, followed by a semicolon (;). A block directive has a set of brackets and allows configuration items to be set within a specific context. This makes the configuration files easier to follow, especially as they get more complex.

Here are a few of the key configuration items. Firstly, user nginx defines the user in which NGINX will run as. This is important to note if you have a server-side script which requires the ability to write files and a user will also require permission to read the files.

Secondly, worker_processes sets the number of worker processes that NGINX will start. While a default of 1 doesn't sound very high, the event-driven nature means that this certainly won't be a limitation initially. The optimal number of processes depends on many factors, but an easy starting reference is to go by the number of CPU cores your server has.

Next, worker_connections is the maximum amount of simultaneous connections that a worker process can open. In the default configuration, this is set to 1024 concurrent connections.

Lastly, the include /etc/nginx/conf.d/*.conf; line tells NGINX to load all of the .conf files as if they were all part of the main nginx.conf file. This allows you to separate the configuration for different sites.

However, even though 1.9.11 added the dynamic modules, none of the standard modules are dynamic by default. To make them into dynamic modules, you'll need to update the configure options. For example, to make the mail module dynamic, update --with-mail to --with-mail=dynamic.

The main nginx.conf configuration file will then need the following:

load_module "modules/ngx_mail_module.so";

There are a number of third-party modules for NGINX, some of which we'll be using later in this book and can be found at https://www.nginx.com/resources/wiki/modules/.

Edit the file and add the following:

      server {
          listen 80;
          server_name server.yourdomain.com; 
          access_log /var/log/nginx/log/host.access.log combined;

          location / {
              root /var/www/html;
              index index.html; 
          }
      }

      mkdir -p /var/www/vhosts

      chmod -R o+r /var/www/vhosts
chown -R nginx:nginx /var/www/vhosts

Let's go through this setup file to understand each directive:

We can enable the basic NGINX stub_status page to give some rudimentary statistics and service status. To enable, edit your site config and add the following:

location = /nginx_status { 
    stub_status on; 
    access_log   off; 
    allow <YOURIPADDRESS>; 
    deny all; 
} 

To prevent information leakage about your system, we have added the allow command. This should be your IP address. This is followed by the deny all command to prevent anyone else from loading the URL. We've also turned off access logs for this URL to save space.

After reloading your configuration (hint: systemctl reload nginx for systemd-based OS), you can now load the new URL /nginx_status in your browser.

You should see something like the following:

Let's take apart the details line-by-line:

To install ngxtop, you'll first need to install the Python package manager, pip. On a Debian/Ubuntu-based system, you'll need to run the following:

apt-get install python-pip

For a Red Hat- / CentOS-based system, the EPEL repository is required first. To install, run the following:

yum install epel-release
yum install python-pip

Once you have pip installed, you can now install ngxtop:

pip install ngxtop

This will download the required files and install ngxtop for you. It's now ready to use.

The ngxtop utility can be simply called from the command line, and it will attempt to read the log file location from the configuration. However, if you're running virtual hosts, it may not read the access log location correctly. The easiest way in this scenario is to manually specify the log location.

Consider the following example:

ngxtop -l /var/log/nginx/access.log

This will display a console-based view of what URLs are being accessed. Here's a basic example:

This will refresh every second, giving you near instantaneous information about what URLs NGINX is serving, but that's not all. The ngxtop utility is quite configurable and there are a number of different ways it can display information.

We can filter only the 404 pages with the following:

ngxtop -l /var/log/nginx/access.log --filter 'status == 404'

Only those URLs which had a 404 are now going to be displayed within ngxtop. Here's an example output:

There are quite a number of other options easy to tailor to your scenario, especially if you know what you're hunting for.

To know more about ngxtop, refer tohttps://github.com/lebinh/ngxtop.