NGINX Cookbook

Chapter 1. Basics

1.0 Introduction

To get started with NGINX Open Source or NGINX Plus, you first need to install it on a system and learn some basics. In this chapter, you will learn how to install NGINX, where the main configuration files are, and commands for administration. You will also learn how to verify your installation and make requests to the default server.

1.1 Installing on Debian/Ubuntu

Problem

You need to install NGINX Open Source on a Debian or Ubuntu machine.

Solution

Create a file named /etc/apt/sources.list.d/nginx.list that contains the following contents:

deb http://nginx.org/packages/mainline/OS/ CODENAME nginx
deb-src http://nginx.org/packages/mainline/OS/ CODENAME nginx

Alter the file, replacing OS at the end of the URL with ubuntu or debian, depending on your distribution. Replace CODENAME with the code name for your distribution; jessie or stretch for Debian, or trusty, xenial, artful, or bionic for Ubuntu. Then, run the following commands:

wget http://nginx.org/keys/nginx_signing.key
apt-key add nginx_signing.key
apt-get update
apt-get install -y nginx
/etc/init.d/nginx start

Discussion

The file you just created instructs the advanced package tool (APT) package management system to utilize the Official NGINX package repository. Modifying the file to provide the correct endpoint and code name for your distribution ensures that the APT utility receives the correct .deb packages for your system. The following commands download the NGINX GPG package signing key and import it into APT. Providing APT the signing key enables the APT system to validate packages from the repository. The apt-get update command instructs the APT system to refresh its package listings from its known repositories. After the package list is refreshed, you can install NGINX Open Source from the Official NGINX repository. After you install it, the final command starts NGINX.

1.2 Installing on RedHat/CentOS

Problem

You need to install NGINX Open Source on RedHat or CentOS.

Solution

Create a file named /etc/yum.repos.d/nginx.repo that contains the following contents:

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

Alter the file, replacing OS at the end of the URL with rhel or centos, depending on your distribution. Replace OSRELEASE with 6 or 7 for version 6.x or 7.x, respectively. Then, run the following commands:

yum -y install nginx
systemctl enable nginx
systemctl start nginx
firewall-cmd --permanent --zone=public --add-port=80/tcp
firewall-cmd --reload

Discussion

The file you just created for this solution instructs the YUM package management system to utilize the Official NGINX Open Source package repository. The commands that follow install NGINX Open Source from the Official repository, instruct systemd to enable NGINX at boot time, and tell it to start it now. The firewall commands open port 80 for the TCP protocol, which is the default port for HTTP. The last command reloads the firewall to commit the changes.

1.3 Installing NGINX Plus

Problem

You need to install NGINX Plus.

Solution

Visit http://cs.nginx.com/repo_setup. From the drop-down menu, select the OS you’re installing and then follow the instructions. The instructions are similar to the installation of the open source solutions; however, you need to install a certificate in order to authenticate to the NGINX Plus repository.

Discussion

NGINX keeps this repository installation guide up to date with instructions on installing the NGINX Plus. Depending on your OS and version, these instructions vary slightly, but there is one commonality. You must obtain a certificate and key from the NGINX portal, and provide them to your system, in order to authenticate to the NGINX Plus repository.

1.4 Verifying Your Installation

Problem

You want to validate the NGINX installation and check the version.

Solution

You can verify that NGINX is installed and check its version by using the following command:

$ nginx -v
nginx version: nginx/1.15.3

As this example shows, the response displays the version.

You can confirm that NGINX is running by using the following command:

$ ps -ef | grep nginx
root      1738     1  0 19:54 ?  00:00:00 nginx: master process
nginx     1739  1738  0 19:54 ?  00:00:00 nginx: worker process

The ps command lists running processes. By piping it to grep, you can search for specific words in the output. This example uses grep to search for nginx. The result shows two running processes, a master and worker. If NGINX is running, you will always see a master and one or more worker processes. Note the master process is running as root, as NGINX needs elevated privileges in order to function properly. For instructions on starting NGINX, refer to the next section. To see how to start NGINX as a daemon, use the init.d or systemd methodologies.

To verify that NGINX is returning requests correctly, use your browser to make a request to your machine or use curl. When making the request, use the machine’s IP address or hostname. If installed locally you can use localhost as follows:

curl localhost

You will see the NGINX Welcome default HTML site.

Discussion

The nginx command allows you to interact with the NGINX binary to check the version, list installed modules, test configurations, and send signals to the master process. NGINX must be running in order for it to serve requests. The ps command is a surefire way to determine whether NGINX is running either as a daemon or in the foreground. The configuration provided by default with NGINX runs a static-site HTTP server on port 80. You can test this default site by making an HTTP request to the machine at localhost as well as the host’s IP and hostname.

1.5 Key Files, Directories, and Commands

Problem

You need to understand the important NGINX directories and commands.

Solution

NGINX files and directories

/etc/nginx/

The /etc/nginx/ directory is the default configuration root for the NGINX server. Within this directory you will find configuration files that instruct NGINX on how to behave.

/etc/nginx/nginx.conf

The /etc/nginx/nginx.conf file is the default configuration entry point used by the NGINX service. This configuration file sets up global settings for things like worker process, tuning, logging, loading dynamic modules, and references to other NGINX configuration files. In a default configuration, the /etc/nginx/nginx.conf file includes the top-level http block, or context, which includes all configuration files in the directory described next.

/etc/nginx/conf.d/

The /etc/nginx/conf.d/ directory contains the default HTTP server configuration file. Files in this directory ending in .conf are included in the top-level http block from within the /etc/nginx/nginx.conf file. It’s best practice to utilize include statements and organize your configuration in this way to keep your configuration files concise. In some package repositories, this folder is named sites-enabled, and configuration files are linked from a folder named site-available; this convention is deprecated.

/var/log/nginx/

The /var/log/nginx/ directory is the default log location for NGINX. Within this directory you will find an access.log file and an error.log file. The access log contains an entry for each request NGINX serves. The error logfile contains error events and debug information if the debug module is enabled.

NGINX commands

nginx -h

Shows the NGINX help menu.

nginx -v

Shows the NGINX version.

nginx -V

Shows the NGINX version, build information, and configuration arguments, which shows the modules built into the NGINX binary.

nginx -t

Tests the NGINX configuration.

nginx -T

Tests the NGINX configuration and prints the validated configuration to the screen. This command is useful when seeking support.

nginx -s signal

The -s flag sends a signal to the NGINX master process. You can send signals such as stop, quit, reload, and reopen. The stop signal discontinues the NGINX process immediately. The quit signal stops the NGINX process after it finishes processing inflight requests. The reload signal reloads the configuration. The reopen signal instructs NGINX to reopen logfiles.

Discussion

With an understanding of these key files, directories, and commands, you’re in a good position to start working with NGINX. With this knowledge, you can alter the default configuration files and test your changes by using the nginx -t command. If your test is successful, you also know how to instruct NGINX to reload its configuration using the nginx -s reload command.

1.6 Serving Static Content

Problem

You need to serve static content with NGINX.

Solution

Overwrite the default HTTP server configuration located in /etc/nginx/conf.d/default.conf with the following NGINX configuration example:

server {
    listen 80 default_server; 
    server_name www.example.com; 

    location / {
        root /usr/share/nginx/html;
        # alias /usr/share/nginx/html;
        index index.html index.htm;
    }
}

Discussion

This configuration serves static files over HTTP on port 80 from the directory /usr/share/nginx/html/. The first line in this configuration defines a new server block. This defines a new context for NGINX to listen for. Line two instructs NGINX to listen on port 80, and the default_server parameter instructs NGINX to use this server as the default context for port 80. The listen directive can also take a range of ports. The server_name directive defines the hostname or names of which requests should be directed to this server. If the configuration had not defined this context as the default_server, NGINX would direct requests to this server only if the HTTP host header matched the value provided to the server_name directive. With the default_server context set, you can omit the server_name directive if you do not yet have a domain name to use.

The location block defines a configuration based on the path in the URL. The path, or portion of the URL after the domain, is referred to as the uniform resource identifier (URI). NGINX will best match the URI requested to a location block. The example uses / to match all requests. The root directive shows NGINX where to look for static files when serving content for the given context. The URI of the request is appended to the root directive’s value when looking for the requested file. If we had provided a URI prefix to the location directive, this would be included in the appended path, unless we used the alias directive rather than root. The location directive is able to match a wide range of expressions. Visit the link in the Also See section for more information. Lastly, the index directive provides NGINX with a default file, or list of files to check, in the event that no further path is provided in the URI.

Also See

NGINX HTTP Location Directive Documentation

1.7 Graceful Reload

Problem

You need to reload your configuration without dropping packets.

Solution

Use the reload method of NGINX to achieve a graceful reload of the configuration without stopping the server:

nginx -s reload

This example reloads the NGINX system using the NGINX binary to send a signal to the master process.

Discussion

Reloading the NGINX configuration without stopping the server provides the ability to change configurations on the fly without dropping any packets. In a high-uptime, dynamic environment, you will need to change your load-balancing configuration at some point. NGINX allows you to do this while keeping the load balancer online. This feature enables countless possibilities, such as rerunning configuration management in a live environment, or building an application- and cluster-aware module to dynamically configure and reload NGINX to meet the needs of the environment.