Although Nginx is a relatively new and growing project, there are already a good number of resources available on the World Wide Web (WWW) along with an active community of administrators and developers.

The official website, http://nginx.org, currently serves as official documentation reference and provides links to download the latest version of the application source code and binaries. A wiki is also available at http://wiki.nginx.org, which offers a wide selection of additional resources, such as installation guides for various operating systems, tutorials related to the different modules of Nginx, and more.

There are several ways to get help in case you should need it. If you have a specific question, you may want to try posting on the Nginx forum: http://forum.nginx.org. An active community of users will answer your questions in no time. Additionally, the Nginx mailing list, which is relayed on the Nginx forum, will also prove to be an excellent resource for any question you may have. If you need direct assistance, there is always a group of regulars helping each other out on the IRC channel #Nginx on irc.freenode.net.

Another interesting source of information is the blogosphere. A simple query on your favorite search engine should return a good number of blog articles documenting Nginx, its configuration, and its modules.

Personal websites and blogs documenting Nginx

It's now time to head over to the official website and get started with downloading the source code to compile and install Nginx. Before you do so, let's take a quick look at a summary of the available versions and features that come with them.

Igor Sysoev, a talented Russian developer and server administrator, initiated the project back in 2002. Between the first release in 2004 and the current version, the market share of Nginx has been growing steadily. It now serves nearly 15 percent of websites on the Internet, according to a October 2015 http://netcraft.com survey. The features are plenty and render the application both powerful and flexible at the same time.

There are currently three version branches of the project:

A recurring question regarding mainline versions is, are they stable enough to be used on production servers? Cliff Wells, original founder and maintainer of the http://www.nginx.org wiki, believes so: I generally use and recommend the latest development version. It's only bitten me once! Early adopters rarely report critical problems. It is up to you to select the version you will be using on your server, knowing that the instructions given in this book should be valid regardless of the release, as the Nginx developers have decided to maintain overall backward compatibility in new versions. You can find more information on version changes, new additions, and bug fixes in the dedicated change log page on the official website.

As of the stable version 1.8.0, Nginx offers an impressive variety of features, which, contrary to what the title of this book indicates, are not all related to serving HTTP content. Here is a list of the main features of the web branch, quoted from the official website http://www.nginx.org:

Nginx can also be used as a mail proxy server, although this aspect is not closely documented in the book:

Nginx is compatible with most computer architectures and operating systems, including Windows, Linux, Mac OS, FreeBSD, and Solaris. The application runs well on 32- and 64-bit architectures.

Once you have made your choice about which version you will be using, head over to http://www.nginx.org and find the URL of the file you wish to download. Position yourself in your home directory, which will contain the source code to be compiled, and download the file using wget:

[alex@example.com ~]$ mkdir src && cd src
[alex@example.com src]$ wget http://nginx.org/download/nginx-1.8.0.tar.gz

We will be using version 1.8.0, the latest stable version as of April, 2015. Once downloaded, extract the archive contents in the current folder:

[alex@example.com src]$ tar zxf nginx-1.8.0.tar.gz

You have successfully downloaded and extracted Nginx. Now, the next step will be to configure the compilation process in order to obtain a binary that perfectly fits your operating system.

If, for some reason, you do not want to bother with the configuration step, such as for testing purposes or simply because you will be recompiling the application in the future, you may simply use the configure command with no switches. Execute the following three commands to build and install a working version of Nginx, starting with the configure command:

[alex@example.com nginx-1.8.0]# ./configure

Running this command should initiate a long procedure of verifications to ensure that your system contains all of the necessary components. If the configuration process fails, check the prerequisites section again, as it is the most common cause of errors. For information about why the command failed, you may also refer to the objs/autoconf.err file, which provides a more detailed report. The make command will compile the application. This step should not cause any errors as long as the configuration went fine.

[alex@example.com nginx-1.8.0]# make
[root@example.com nginx-1.8.0]# make install

This last step will copy the compiled files as well as other resources to the installation directory, by default, /usr/local/nginx. You may need to be logged in as root to perform this operation, depending on permissions granted to the /usr/local directory.

Again, if you build the application without configuring it, you take the risk of missing out on a lot of features, such as the optional modules and others that we are about to discover.

When running the configure command, you are offered the possibility to enable some switches that let you specify the directory or file paths for a variety of elements. Note that the options offered by the configuration switches may change according to the version you downloaded. The options listed below are valid with the stable version, as of release 1.8.0. If you use another version, run the ./configure --help command to list the available switches for your setup.

Using a switch typically consists of appending some text to the command line, for instance, using the --conf-path switch:

[alex@example.com nginx-1.8.0]# ./configure --conf-path=/etc/nginx/nginx.conf

Here is an exhaustive list of the configuration switches for configuring paths:

Prerequisites come in the form of libraries and binaries. You should, by now, have them all installed on your system. However, even though they are present on your system, there may be occasions where the configuration script is unable to locate them. The reasons might be diverse, for example, if they were installed in non-standard directories.

In order to solve such problems, you are given the option to specify the path of prerequisites using the following switches (miscellaneous prerequisite-related options have been grouped together):

Modules, which will be detailed in Chapter 4, Module Configuration, need to be selected before compiling the application. Some are enabled by default and some need to be enabled manually, as you will see in the following table.

Other options are available in the configuration script, for example, regarding the mail server proxy feature or event management. These have been enlisted as follows:

Here are a few examples of configuration commands that may be used for various cases. In these examples, the path switches have been omitted, as they are specific to each system and leaving the default values may simply function correctly.

./configure --prefix=/usr/local/nginx-1.8.0

./configure --user=www-data --group=www-data --with-http_ssl_module --with-http_realip_module

./configure --user=www-data --group=www-data --with-http_ssl_module --with-http_realip_module --with-http_addition_module --with-http_xslt_module --with-http_image_filter_module --with-http_geoip_module --with-http_sub_module --with-http_dav_module --with-http_flv_module --with-http_mp4_module --with-http_gzip_static_module --with-http_random_index_module --with-http_secure_link_module --with-http_stub_status_module --with-http_perl_module --with-http_degradation_module --with-http_spdy_module --with-http_gunzip_module --with-http_auth_request_module

./configure --user=www-data --group=www-data --with-mail --with-mail_ssl_module

In some cases, the configure command may fail—after a long list of checks, you may receive a few error messages on your terminal. In most (if not all) cases, these errors are related to missing prerequisites or unspecified paths.

In such cases, proceed with the following verifications carefully to make sure you have all it takes to compile the application, and optionally, consult the objs/autoconf.err file for more details about the compilation problem. This file is generated during the configure process and will tell you exactly which part of the process failed.

./configure [...] --with-openssl=/usr/lib64

The configuration process is of utmost importance—it generates a makefile for the application depending on the selected switches and performs a long list of requirement checks on your system. Once the configure script is successfully executed, you can proceed with compiling Nginx.

Compiling the project equates to executing the make command in the project source directory:

[alex@example.com nginx-1.8.0]$ make

A successful build should result in the appearance of a final message: make[1]: leaving directory. This should be followed by the project source path.

Again, problems might occur at compile time. Most of these problems can originate in missing prerequisites or the specification of invalid paths. If this occurs, run the configure command again and triple-check the switches and all of the prerequisite options. It may also so happen that you downloaded an overly recent version of the prerequisites, which may not be backwards compatible. In such cases, the best option is to visit the official website of the missing component and download an older version.

If the compilation process was successful, you are ready for the next step: installing the application. The following command must be executed with root privileges:

[root@example.com nginx-1.8.0]# make install

The make install command executes the install section of the make file. In other words, it performs a few simple operations, such as copying binaries and configuration files to the specified install folder. It also creates directories to store log and HTML files if these do not already exist. The make install step is not generally a source of problems, unless your system encounters an exceptional error, such as a lack of storage space or memory.

The next step is obviously run Nginx for the first time. However, before doing so, it's important to understand the nature of this application. There are two types of computer applications—those that require immediate user input, thus running in the foreground, and those that do not, thus running in the background. Nginx is of the latter type, often referred to as daemon. Daemon names usually come with a trailing "d" and a couple of examples can be mentioned here—httpd, the HTTP server daemon, is the name given to Apache under several Linux distributions; named, the name server daemon; or crond the task scheduler—although, as you will notice, this is not the case for Nginx. When started from the command line, a daemon immediately returns the prompt, and in most cases, does not even bother outputting data to the terminal.

Consequently, when starting Nginx, you will not see any text appear on the screen, and the prompt will return immediately. While this might seem startling, it is, on the contrary, a good sign. It means the daemon was started correctly and the configuration did not contain any errors.

It is of utmost importance to understand the process architecture of Nginx, and particularly the user and groups under which its various processes run. A very common source of trouble when setting up Nginx is invalid file access permissions—due to a user or group misconfiguration, you often end up getting 403 Forbidden HTTP errors because Nginx cannot access the requested files.

There are two levels of processes with possibly different permission sets:

The Nginx binary accepts command-line arguments to perform various operations, among which is controlling the background processes. To get the full list of commands, you may invoke the help screen using the following commands:

[alex@example.com ~]$ cd /usr/local/nginx/sbin
[alex@example.com sbin]$ ./nginx -h

The next few sections will describe the purpose of these switches. Some allow you to control the daemon and some let you perform various operations on the application configuration.

You can start Nginx by running the Nginx binary without any switches. If the daemon is already running, a message will show up indicating that a socket is already listening on the specified port:

[emerg]: bind() to 0.0.0.0:80 failed (98: Address already in use) […] [emerg]: still could not bind().

Beyond this point, you may control the daemon by stopping it, restarting it, or simply reloading its configuration. Controlling is done by sending signals to the process using the nginx -s command.

Note that when starting the daemon, stopping it, or performing any of the preceding operations, the configuration file is first parsed and verified. If the configuration is invalid, whatever command you have submitted will fail, even when trying to stop the daemon. In other words, in some cases you will not be able to even stop Nginx if the configuration file is invalid.

An alternate way to terminate the process, in desperate cases only, is to use the kill or killall commands with root privileges:

[root@example.com ~]# killall nginx

As you can imagine, testing the validity of your configuration will become crucial if you constantly tweak your server setup . The slightest mistake in any of the configuration files can result in a loss of control over the service—you will then be unable to stop it via regular init control commands, and obviously, it will refuse to start again.

Consequently, the following command will be useful to you in many occasions; it allows you to check the syntax, validity, and integrity of your configuration:

[alex@example.com ~]$ /usr/local/nginx/sbin/nginx –t

The –t switch stands for test configuration. Nginx will parse the configuration anew and let you know whether it is valid or not. A valid configuration file does not necessarily mean Nginx will start, though, as there might be additional problems such as socket issues, invalid paths, or incorrect access permissions.

Obviously, manipulating your configuration files while your server is in production is a dangerous thing to do and should be avoided when possible. The best practice, in this case, is to place your new configuration into a separate temporary file and run the test on that file. Nginx makes it possible by offering the –c switch:

[alex@example.com sbin]$ ./nginx –t –c /home/alex/test.conf

This command will parse /home/alex/test.conf and make sure it is a valid Nginx configuration file. When you are done, after making sure that your new file is valid, proceed to replacing your current configuration file and reload the server configuration:

[alex@example.com sbin]$ cp -i /home/alex/test.conf /usr/local/nginx/conf/nginx.conf
cp: erase 'nginx.conf' ? yes
[alex@example.com sbin]$ ./nginx –s reload

Another switch that might come in handy in many situations is –V. Not only does it tell you the current Nginx build version, but more importantly, it also reminds you about the arguments that you used during the configuration step—in other words, the command switches that you passed to the configure script before compilation.

[alex@example.com sbin]$ ./nginx -V
nginx version: nginx/1.8.0 (Ubuntu)
built by gcc 4.8.4 (Ubuntu 4.8.4-2ubuntu1~14.04)
TLS SNI support enabled
configure arguments: --with-http_ssl_module

In this case, Nginx was configured with the --with-http_ssl_module switch only.

Why is this so important? Well, if you ever try to use a module that was not included with the configure script during the precompilation process, the directive enabling the module will result in a configuration error. Your first reaction will be to wonder where the syntax error comes from. Your second reaction will be to wonder if you even built the module in the first place! Running nginx –V will answer this question.

Additionally, the –g option lets you specify additional configuration directives in case they were not included in the configuration file:

[alex@example.com sbin]$ ./nginx –g "timer_resolution 200ms";

Most Linux-based operating systems to date use a System-V style init daemon. In other words, their startup process is managed by a daemon called init, which functions in a way that is inherited from the old System V Unix-based operating system.

This daemon functions on the principle of runlevels, which represent the state of the computer. Here is a table representing the various runlevels and their signification:

You can manually initiate a runlevel transition: use the telinit 0 command to shut down your computer or telinit 6 to reboot it.

For each runlevel transition, a set of services are executed. This is the key concept to understand here: when your computer is stopped, its runlevel is 0. When you turn it on, there will be a transition from runlevel 0 to the default computer startup runlevel. The default startup runlevel is defined by your own system configuration (in the /etc/inittab file), and the default value depends on the distribution you are using. Debian and Ubuntu use runlevel 2, Red Hat and Fedora use runlevel 3 or 5, CentOS and Gentoo use runlevel 3, and so on—the list is long.

So, in summary, when you start your computer running CentOS, it operates a transition from runlevel 0 to runlevel 3. That transition consists of starting all services that are scheduled for runlevel 3. The question that remains is how to schedule a service to be started at a specific runlevel.

For each runlevel, there is a directory containing scripts to be executed. If you enter these directories (rc0.d, rc1.d, to rc6.d), you will not find actual files, but rather symbolic links referring to scripts located in the init.d directory. Service startup scripts will indeed be placed in init.d, and links will be created by tools placing them in the proper directories.

An init script, also known as a service startup script or even sysv script, is a shell script respecting a certain standard. The script controls a daemon application by responding to commands such as start, stop, and others, which are triggered at two levels. First, when the computer starts, if the service is scheduled to be started for the system runlevel, the init daemon will run the script with the start argument. The other possibility for you is to manually execute the script by calling it from the shell:

[root@example.com ~]# service httpd start

Or if your system does not come with the service command:

[root@example.com ~]# /etc/init.d/httpd start

The script must accept at least the start, stop, restart, force-reload, and status commands, as they will be used by the system to respectively start up, shut down, restart, forcefully reload the service, or inquire its status. However, to enlarge your field of action as a system administrator, it is often interesting to provide further options, such as a reload argument to reload the service configuration or a try-restart argument to stop and start the service again.

Note that since service httpd start and /etc/init.d/httpd start essentially do the same thing, with the exception that the second command will work on all operating systems, we will make no further mention of the service command and will exclusively use the /etc/init.d/ method.

We will thus create a shell script to start and stop our Nginx daemon and also to restart and reload it. The purpose here is not to discuss Linux shell script programming, so we will merely provide the source code of an existing init script, along with some comments to help you understand it.

Due to differences in the format of the init scripts from one distribution to another, we will discover two separate scripts here. The first one is meant for Debian-based distributions such as Debian, Ubuntu, Knoppix, and so forth.

First, create a file called nginx with the text editor of your choice, and save it in the /etc/init.d/ directory (on some systems, /etc/init.d/ is actually a symbolic link to /etc/rc.d/init.d/). In the file you just created, insert the script provided in the code bundle supplied with this book. Make sure that you change the paths to make them correspond to your actual setup.

You will need root permissions to save the script into the init.d directory.

Due to the system tools, shell programming functions, and specific formatting that it requires, the preceding script is only compatible with Debian-based distributions. If your server is operated by a Red Hat–based distribution such as CentOS, Fedora, and many more, you will need an entirely different script.

Placing the file in the init.d directory does not complete our work. There are additional steps that will be required to enable the service. First, make the script executable. So far, it is only a piece of text that the system refuses to run. Granting executable permissions on the script is done with the chmod command:

[root@example.com ~]# chmod +x /etc/init.d/nginx

Note that if you created the file as the root user, you will need to be logged in as root to change the file permissions.

At this point, you should already be able to start the service using service nginx start or /etc/init.d/nginx start, as well as stopping, restarting, or reloading the service.

The last step here will be to make it so the script is automatically started at the proper runlevels. Unfortunately, doing this entirely depends on what operating system you are using. We will cover the two most popular families—Debian, Ubuntu, or other Debian-based distributions and Red Hat/Fedora/CentOS, or other Red Hat–derived systems.

[root@example.com ~]# update-rc.d -f nginx defaults

Red Hat–based distributions

For the Red Hat–based systems family, the command differs, but you get an additional tool to manage system startup. Adding the service can be done via the following command:

[root@example.com ~]# chkconfig nginx on

Once that is done, you can then verify the runlevels for the service:

[root@example.com ~]# chkconfig --list nginx
Nginx  0:off   1:off   2:on    3:off   4:on    5:on    6:off

Another tool will be useful to you to manage system services, namely, ntsysv. It lists all services scheduled to be executed on system startup and allows you to enable or disable them at will.

Note

The tool ntsysv requires root privileges to be executed.

Note that prior to using ntsysv, you must first run the chkconfig nginx on command, otherwise Nginx will not appear in the list of services.

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed to you directly.