There are usually three steps when building an application from source—the configuration, the compilation, and the installation. The configuration step allows you to select a number of options that will not be editable after the program is built, as it has a direct impact on the project binaries. Consequently, it is a very important stage that you need to follow carefully if you want to avoid surprises later, such as the lack of a specific module or files being located in a random folder.
The process consists of appending certain switches to the configure
script that comes with the source code. We will discover the three types of switches that you can activate; but let us first study the easiest way to proceed.
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:
[[email protected] nginx-1.2.9]# ./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, please make sure to 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:
[[email protected] nginx-1.2.9]# make
The make
command will compile the application. This step should not cause any errors as long as the configuration went fine:
[[email protected] nginx-1.2.9]# 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 to miss 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. Please 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, release 1.2.9
. 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:
[[email protected] nginx-1.2.9]# ./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. Yet, even though they are present on your system, there may be occasions where the configuration script cannot 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 are grouped together.
Modules, which will be detailed in Chapter 3, HTTP Configuration, and further, 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. Please note that an exhaustive and more detailed list of modules can be found in Appendix B, Module Reference.
The following switches allow you to disable modules that are enabled by default:
Modules enabled by default |
Description |
---|---|
Disables the Charset module for re-encoding web pages. | |
Disables the Gzip compression module. | |
Disables the Server Side Include module. | |
Disables the User ID module providing user identification via cookies. | |
Disables the Access module allowing access configuration for IP address ranges. | |
Disables the Basic Authentication module. | |
Disables the Automatic Index module. | |
Disables the Geo module allowing you to define variables depending on IP address ranges. | |
Disables the Map module that allows you to declare map blocks. | |
Disables the Referer control module. | |
Disables the Rewrite module. | |
Disables the Proxy module for transferring requests to other servers. | |
|
Disables the FastCGI, uWSGI, or SCGI modules for interacting with respectively FastCGI, uWSGI, or SCGI processes. |
Disables the Memcached module for interacting with the memcache daemon. | |
Disables the Limit Connections module for restricting resource usage according to defined zones. | |
Disables the Limit Requests module allowing you to limit the amount of requests per user. | |
Disables the Empty Gif module for serving a blank GIF image from memory. | |
Disables the Browser module for interpreting the User Agent string. | |
Disables the Upstream module for configuring load-balanced architectures. | |
Disables the Least Connections feature |
The following switches allow you to enable modules that are disabled by default:
Modules disabled by default |
Description |
---|---|
Enables the SSL module for serving pages using HTTPS. | |
Enables the Real IP module for reading the real IP address from the request header data. | |
Enables the Addition module which lets you append or prepend data to the response body. | |
Enables the XSLT module for applying XSL transformations to XML documents. Note: You will need to install the | |
Enables the Image Filter module that lets you apply modification to images. Note: You will need to install the | |
Enables the GeoIP module for achieving geographic localization using MaxMind's GeoIP binary database. Note: You will need to install the | |
Enables the Substitution module for replacing text in web pages. | |
Enables the WebDAV module (Distributed Authoring and Versioning via Web). | |
Enables the FLV module for special handling of | |
Enables the MP4 module for special handling of | |
Enables the Gzip Static module for sending pre-compressed files. | |
Enables the Random Index module for picking a random file as the directory index. | |
Enables the Secure Link module to check the presence of a keyword in the URL. | |
Enables the Stub Status module, which generates a server statistics and information page. | |
Enables the Google Performance Tools module. | |
Enables the Degradation module that controls the behavior of your server depending on current resource usage. | |
Enables the Perl module allowing you to insert Perl code directly into your Nginx configuration files, and to make Perl calls from SSI. |
Other options are available in the configuration script, for example, regarding the mail server proxy feature or event management.
Other options | |
---|---|
Disables the HTTP server. | |
Disables HTTP caching features. | |
Adds a third-party module to the compile process by specifying its path. This switch can be repeated indefinitely if you wish to compile multiple modules. | |
Enables support for Asynchronous IO disk operations. |
Here are a few examples of configuration commands that may be used for various cases. In these examples, the path switches were omitted as they are specific to each system and leaving the default values may simply function correctly.
Note
Be aware that these configurations do not include additional third-party modules. Please refer to Chapter 5, PHP and Python with Nginx, for more information about installing add-ons.
During the configuration, you should take particular care over the --prefix
switch. Many of the future configuration directives (that we will approach in further chapters) will be based on the path you select at this point. While it is not a definitive problem since absolute paths can still be employed, you should know that the prefix cannot be changed once the binaries have been compiled.
There is also another issue that you may run into if you plan to keep up with the times and update Nginx as new versions are released. The default prefix (if you do not override the setting by using the --prefix
switch) is /usr/local/nginx
. This is a path that does not include the version number. Consequently, when you upgrade Nginx, if you do not specify a different prefix, the new install files will override the previous ones, which among other problems, could potentially erase your currently running binaries.
It is thus recommended to use a different prefix for each version you will be using:
./configure --prefix=/usr/local/nginx-1.2.9
Additionally, to make future changes simpler, you may create a symbolic link /usr/local/nginx
pointing to /usr/local/nginx-1.2.9
. Once you upgrade, you can update the link to make it point to /usr/local/nginx-newer.version
. This will allow the init
script to always make use of the latest installed version of Nginx.
The first example describes a situation where the most important features and modules for serving HTTP and HTTPS content are enabled, and the mail-related options are disabled:
./configure --user=www-data --group=www-data --with-http_ssl_module --with-http_realip_module
As you can see, the command is rather simple and most switches were left out. The reason being is that the default configuration is rather efficient and most of the important modules are enabled. You will only need to include the http_ssl
module for serving HTTPS content, and optionally, the "real IP" module for retrieving your visitors' IP addresses in case you are running Nginx as backend server.
The next situation: the entire package. All modules are enabled and it is up to you whether you want to use them or not at runtime:
./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
This configuration opens up a wide range of possible configuration options. Chapters 3, HTTP Configuration, to Chapter 6, Apache and Nginx Together, provide more detailed information on module configuration.
With this setup, all optional modules are enabled, thus requiring additional libraries to be installed—libgeoip
for the Geo IP module, libgd
for the Image Filter module, libxml2
, and libxslt
for the XSLT module. You may install those prerequisites using your system package manager such as running yum install libxml2
or apt-get install libxml2
.
This last build configuration is somewhat special as it is dedicated to enabling mail server proxy features—a darker and less documented side of Nginx. The related features and modules are all enabled:
./configure --user=www-data --group=www-data --with-mail --with-mail_ssl_module
If you wish to completely disable the HTTP serving features and only dedicate Nginx to mail proxying, you may add the --without-http
switch.
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 where the process failed.
There are basically four main prerequisites: GCC, PCRE, zlib, and OpenSSL. The last three are libraries that must be installed in two packages: the library itself and its development sources. Make sure you have installed both for each of them. Please refer to the prerequisites section at the beginning of this chapter. Note that other prerequisites, such as LibXML2 or LibXSLT, might be required for enabling extra modules (for example, in the case of the HTTP XSLT module).
If you are positive that all of the prerequisites were installed correctly, perhaps the issue comes from the fact that the configure
script is unable to locate the prerequisite files. In that case, make sure that you include the switches related to file paths, as described earlier.
For example, the following switch allows you to specify the location of the OpenSSL library files:
./configure [...] --with-openssl=/usr/lib64
The OpenSSL library file will be looked for in the specified folder.
Always remember to check the obvious; everyone makes even the simplest of mistakes sooner or later. Make sure the directory you placed the Nginx files in has read and write permissions for the user running the configuration and compilation scripts. Also ensure that all paths specified in the configure
script switches are existing, valid paths.
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:
[[email protected] nginx-1.2.9]$ make
A successful build should result in a final message appearing: make[1]: leaving directory
followed by the project source path.
Again, problems might occur at compile time. Most of these problems can originate in missing prerequisites or invalid paths specified. If this occurs, run the configure
script again and triple-check the switches and all of the prerequisite options. It may also occur that you downloaded a too recent version of the prerequisites that might 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:
[[email protected] nginx-1.2.9]# make install
The make install
command executes the install
section of the makefile
. 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 for storing 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 some exceptional error, such as a lack of storage space or memory.