install NGINX Open Source

This article explains how to install NGINX Open Source.

Choosing Between a Stable or a Mainline Version
Choosing Between a Pre-built Package or Compiling From the Sources
Compiling and Installing From the Sources
Installing a Pre-Built Package

Choosing Between a Stable or a Mainline Version

NGINX Open Source is available in two versions:

The mainline version. This version includes the latest features and bugfixes and is always up-to-date. It is reliable, but it may include some experimental modules, and it may also have some number of new bugs.
The stable version. This version doesn’t have new features, but includes critical bug fixes that are always backported to the mainline version. The stable version is recommended for production servers.

Choosing Between a Pre-built Package or Compiling From the Sources

Both NGINX Open Source mainline and stable versions can be installed in two ways:

from a pre-built package. This is a quick and easy way to install NGINX Open Source. The package includes almost all NGINX official modules and is available for most popular operating systems.
compiled from the sources. This way is more flexible: you can add particular modules including 3rd party modules or apply latest security patches.

Compiling and Installing From the Sources

Compiling NGINX from the sources provides you with more flexibility: you can add particular NGINX modules or 3rd party modules and apply latest security patches.

Installing NGINX Dependencies

Prior to compiling NGINX from the sources, it is necessary to install its dependencies:

the PCRE library – required by NGINX Core and Rewrite modules and provides support for regular expressions:

$ wget ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-8.39.tar.gz

$ tar -zxf pcre-8.39.tar.gz

$ cd pcre-8.39

$ ./configure

$ make

$ sudo make install

the zlib library – required by NGINX Gzip module for headers compression:

$ wget http://zlib.net/zlib-1.2.8.tar.gz

$ tar -zxf zlib-1.2.8.tar.gz

$ cd zlib-1.2.8

$ ./configure

$ make

$ sudo make install

the OpenSSL library – required by NGINX SSL modules to support the HTTPS protocol:

$ wget http://www.openssl.org/source/openssl-1.0.2f.tar.gz

$ tar -zxf openssl-1.0.2f.tar.gz

$ cd openssl-1.0.2f

$ ./configure darwin64-x86_64-cc --prefix=/usr

$ make

$ sudo make install

Downloading the Sources

NGINX provides source files for both stable and mainline versions. The source files can be downloaded from the NGINX Open Source download page at http://www.nginx.org/en/download.html.

To download and unpack source files for the latest mainline version, type-in the commands:

$ wget http://nginx.org/download/nginx-1.11.7.tar.gz

$ tar zxf nginx-1.11.7.tar.gz

$ cd nginx-1.11.7

To download and unpack source files for the latest stable version, type-in the commands:

$ wget http://nginx.org/download/nginx-1.10.2.tar.gz

$ tar zxf nginx-1.10.2.tar.gz

$ cd nginx-1.10.2

Configuring the Build Options

Configure options are specified with the ./configure script that sets up various NGINX parameters including paths to source and configuration files, compiler options, connection processing methods and the list of modules. The script ends up with creation of the Makefile required to compile the code and install NGINX.

Example of the configure script:

$ ./configure

--sbin-path=/usr/local/nginx/nginx

--conf-path=/usr/local/nginx/nginx.conf

--pid-path=/usr/local/nginx/nginx.pid

--with-pcre=../pcre-8.39

--with-zlib=../zlib-1.2.8

--with-http_ssl_module

--with-stream

--with-mail=dynamic

--add-module=/usr/build/nginx-rtmp-module

--add-dynamic-module=/usr/build/3party_module

Configuring NGINX Paths

The configure script allows you to set paths to NIGNX binary and configuration files, and to dependent libraries such as PCRE or SSL in order to link them statically to NGINX binary.

--prefix=path
defines a directory that will keep NGINX files. The directory will be also used for all relative paths set by the ./configure script (excluding paths to libraries) and for the path to the nginx.conf configuration file.
By default the path is set to /usr/local/nginx.
--sbin-path=path
sets the name of NGINX executable file. This name is used only during installation.
By default the file is named to prefix/sbin/nginx.
--conf-path=path
sets the name of the NGINX configuration file.
By default the file is named prefix/conf/nginx.conf.
Note that regardless of this option you can always start NGINX with a different configuration file by specifying it with the -c option in command-line.
--pid-path=path
sets the name of the nginx.pid file that stores the process ID of the main process. After installation, the path to the file name can always be changed in the nginx.conf configuration file using the pid directive.
By default the file is named prefix/logs/nginx.pid .
--error-log-path=path
sets the name of the primary error, warnings, and diagnostic file. After installation, the file name can always be changed in the nginx.conf configuration file using the error_log directive.
By default the file is named prefix/logs/error.log.
--http-log-path=path
sets the name of the primary request log file of the HTTP server. After installation, the file name can always be changed in the nginx.conf configuration file using the access_log directive.
By default the file is named prefix/logs/access.log.
--user=name
sets the name of an unprivileged user whose credentials will be used by NGINX worker processes. After installation, the name can be changed in the nginx.conf configuration file using the user directive.
The default user name is nobody.
--group=name
sets the name of a group whose credentials will be used by NGINX worker processes. After installation, the name can always be changed in the nginx.conf configuration file using the user directive.
By default, a group name is set to the name of an unprivileged user.
--with-pcre=path
sets the path to the sources of the PCRE library. The library is required for regular expressions support in the location directive and for the ngx_http_rewrite_module module.
--with-pcre-jit
builds the PCRE library with “just-in-time compilation” support (the pcre_jit directive).
--with-zlib=path
sets the path to the sources of the zlib library. The library is required for the ngx_http_gzip_module module.

Configuring NGINX GCC Options

In the configure script you can also specify compiler-related options.

--with-cc-opt=parameters
sets additional parameters that will be added to the CFLAGS variable.
When using the system PCRE library under FreeBSD, --with-cc-opt="-I /usr/local/include" must be specified.
If the number of files supported by select() needs to be increased it can also be specified here such as this: --with-cc-opt="-D FD_SETSIZE=2048".
--with-ld-opt=parameters
sets additional parameters that will be used during linking. When using the system PCRE library under FreeBSD, --with-ld-opt="-L /usr/local/lib" must be specified.

Specifying NGINX Connection Processing Methods

In the configure script you can redefine an event-based polling method. See Connection Processing Methods for details.

--with-select_module, --without-select_module
enables or disables building a module that allows NGINX to work with the select() method. This module is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, or /dev/poll.
--with-poll_module, --without-poll_module
enables or disables building a module that allows NGINX to work with the poll() method. This module is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, or /dev/poll.

NGINX Modules

NGINX consists of modules. The set of modules as well as other build options are configured with the ./configure script.

Some modules are built by default – they do not require to be specified in the configure script. However, any default module can be excluded from the NGINX binary with the --without- configure option in the configure script.

Modules not included by default as well as third-party modules must be explicitly specified in the configure script together with other build options. Such modules can be linked to NGINX binary either statically and will be loaded each time NGINX starts; or dynamically and will be loaded only if they are specified in the NGINX configuration file.

Modules Built by Default

If you do not need a module built by default, you can disable it by including it to the configure script with the --without- prefix :

$ ./configure --sbin-path=/usr/local/nginx/nginx --conf-path=/usr/local/nginx/nginx.conf --pid-path=/usr/local/nginx/nginx.pid --with-http_ssl_module --with-stream --with-pcre=../pcre-8.39 --with-zlib=../zlib-1.2.8 --without-http_empty_gif_module

Module Name	Description
http_charset_module	Adds the specified charset to the “Content-Type” response header field, can convert data from one charset to another.
http_gzip_module	Compresses responses using the gzip method, helping to reduce the size of transmitted data by half or more.
http_ssi_module	Processes SSI (Server Side Includes) commands in responses passing through it.
http_userid_module	Sets cookies suitable for client identification.
http_access_module	Limits access to certain client addresses.
http_auth_basic_module	Limits access to resources by validating the user name and password using the HTTP Basic Authentication protocol.
http_autoindex_module	Processes requests ending with the slash character (‘/’) and produces a directory listing.
http_geo_module	Creates variables with values depending on the client IP address.
http_map_module	Creates variables whose values depend on values of other variables.
http_split_clients_module	Creates variables suitable for A/B testing, also known as split testing.
http_referer_module	Blocks access to a site for requests with invalid values in the Referer header field.
http_rewrite_module	Changes the request URI using regular expressions and return redirects; conditionally selects configurations. Requires the PCRE library.
http_proxy_module	Passes requests to another server.
http_fastcgi_module	Passes requests to a FastCGI server
http_uwsgi_module	Passes requests to a uwsgi server.
http_scgi_module	Passes requests to an SCGI server.
http_memcached_module	Obtains responses from a memcached server.
http_limit_conn_module	Limits the number of connections per the defined key, in particular, the number of connections from a single IP address.
http_limit_req_module	Limits the request processing rate per a defined key, in particular, the processing rate of requests coming from a single IP address.
http_empty_gif_module	Emits single-pixel transparent GIF.
http_browser_module	Creates variables whose values depend on the value of the “User-Agent” request header field.
http_upstream_hash_module	Enables the hash load balancing method.
http_upstream_ip_hash_module	Enables the IP hash load balancing method.
http_upstream_least_conn_module	Enables the least_conn load balancing method.
http_upstream_keepalive_module	Enables keepalive connections.
http_upstream_zone_module	Enables the shared memory zone.

Modules Not Built by Default

Some NGINX modules are not built by default. You will need to enable them manually by adding to the ./configure command. The mail, stream, geoip, image_filter, perl and xslt modules can be compiled as dynamic. See Dynamic Modules for details.

Example of the ./configure command that includes modules:

$ ./configure --sbin-path=/usr/local/nginx/nginx --conf-path=/usr/local/nginx/nginx.conf --pid-path=/usr/local/nginx/nginx.pid --with-pcre=../pcre-8.39 --with-zlib=../zlib-1.2.8 --with-http_ssl_module --with-stream --with-mail

--with-threads
Enables NGINX to use thread pools.
See Thread Pools in NGINX Boost Performance 9x! blog post for details.
--with-file-aio
Enables asynchronous I/O.
--with-ipv6
Enables IPv6 support.
--with-http_ssl_module
Provides support for HTTPS. Requires an SSL library such as OpenSSL.
See the ngx_http_ssl_module reference for the list of directives.
--with-http_v2_module
Provides support for HTTP/2.
See the ngx_http_v2_module reference for the list of directives and the “HTTP/2 Module in NGINX” blog post for details.
--with-http_realip_module
Changes the client address to the one sent in the specified header field.
See the ngx_http_realip_module reference for the list of directives.
--with-http_addition_module
Adds text before and after a response.
See the ngx_http_addition_module reference for the list of directives.
--with-http_xslt_module or --with-http_xslt_module=dynamic
Transforms XML responses using one or more XSLT stylesheets. The module requires the Libxml2 and XSLT libraries.
See the ngx_http_xslt_module reference for the list of directives.
The module can also be compiled as dynamic.
--with-http_image_filter_module or --with-http_image_filter_module=dynamic
Transforms images in JPEG, GIF, and PNG formats. The module requires the LibGD library.
See ngx_http_image_filter_module reference for the list of directives.
The module can also be compiled as dynamic.
--with-http_geoip_module or --with-http_geoip_module=dynamic
Allows creating variables whose values depend on the client IP address. The module uses MaxMind GeoIP databases.
See the ngx_http_geoip_module reference for the list of directives.
The module can also be compiled as dynamic.
--with-http_sub_module
Modifies a response by replacing one specified string by another.
See the ngx_http_sub_module reference for the list of directives.
--with-http_dav_module
Intended for file management automation via the WebDAV protocol.
See the ngx_http_dav_module reference for the list of directives.
--with-http_flv_module
Provides pseudo-streaming server-side support for Flash Video (FLV) files.
See the ngx http_flv_module reference for the list of directives.
--with-mp4_module
Provides pseudo-streaming server-side support for MP4 files.
See the ngx_http_mp4_module reference for the list of directives.
--with-http_gunzip_module
Decompresses responses with Content-Encoding: gzip for clients that do not support zip encoding method.
See the ngx_http_gunzip_module for the list of directives.
--with-http_gzip_static_module
Allows sending precompressed files with the *.gz filename extension instead of regular files.
See the ngx_http_gzip_static_module for the list of directives.
--with-http_auth_request_module
Implements client authorization based on the result of a subrequest.
See the http_auth_request_module for the list of directives.
--with-http_random_index_module
Processes requests ending with the slash character (‘/’) and picks a random file in a directory to serve as an index file.
See the ngx_http_random_index_module for the list of directives.
--with-http_secure_link_module
Used to check authenticity of requested links, protect resources from unauthorized access, and limit link lifetime.
See the ngx_http_secure_link_module for the list of directives.
--with-http_slice_module
Allows splitting a request into subrequests, each subrequest returns a certain range of response. Provides more effective caching of large files.
See the ngx_http_slice_module reference for the list of directives.
--with-http_degradation_module
Allows returning an error when a memory size exceeds the defined value.
--with-http_stub_status_module
Provides access to basic status information.
See the ngx_http_stub_status_module reference for the list of directives.
Note that NGINX Plus customers do not require this module as they are already provided with extended status metrics and interactive dashboard.
--with-http_perl_module or --with-http_perl_module=dynamic
Used to implement location and variable handlers in Perl and insert Perl calls into SSI. Requires the PERL library.
See the ngx_http_perl_module reference for the list of directives.
The module can also be compiled as dynamic.
--with-mail or --with-mail=dynamic
Enables mail proxy functionality.
See the ngx_mail_core_module reference for the list of directives.
The module can also be compiled as dynamic.
--with-mail_ssl_module
Provides support for a mail proxy server to work with the SSL/TLS protocol. Requires an SSL library such as OpenSSL.
See the ngx_mail_ssl_module reference for the list of directives.
--with-stream or --with-stream=dynamic
Enables the TCP proxy functionality.
See the ngx_stream_core_module reference for the list of directives.
The module can also be compiled as dynamic.
--with-stream_ssl_module
Provides support for a stream proxy server to work with the SSL/TLS protocol. Requires an SSL library such as OpenSSL.
See the ngx_stream_ssl_module reference for the list of directives.
--with-google_perftools_module
Allows using Google Performance tools library.
--with-cpp_test_module
--with-debug
Enables the debugging log.

Third Party Modules

You can extend NGINX functionality by compiling NGINX Open Source with your own module or a third-party module. Some third-party modules are listed in the https://nginx.com/resources/wiki/modules/ page. Use third-party modules at your own risk as their stability is not guaranteed.

Statically Linked Modules

Most modules which are built into NGINX Open Source are statically linked: they are built into NGINX Open Source at compile time and are linked to the NGINX binary statically. These modules can be disabled only after NGINX recompilation.

To compile NGINX Open Source with a statically linked third-party module, in the configure script specify the --add-module= option and type-in the path to the module:

$  ./configure ... --add-module=/usr/build/nginx-rtmp-module

Dynamically Linked Modules

NGINX modules can also be compiled as a shared object (*.so file) and then dynamically loaded into NGINX Open Source at runtime. This provides more flexibility, as the module can be loaded or unloaded at any time with the load_module directive specified in the NGINX configuration file. Note that such a module must support dynamic linking.

To compile NGINX Open Source with a dynamically loaded third-party module, in the configure script specify the --add-dynamic-module= configure option and provide the path to the module:

$  ./configure ... --add-dynamic-module=/path/to/module

The resulting *.so files with dynamic modules can be found after compilation in the prefix/modules/ directory, where the prefix is a directory that keep server files, for example, /usr/local/nginx/modules. To load a dynamic module, use the load_module directive after NGINX installation.

See Introducing Dynamic Modules in NGINX 1.9.11 and Extending NGINX for more information.

Completing the Installation

Compile and install the build:
```
$ make

$ sudo make install
```
After the installation is finished, run NGINX Open Source:
```
$ sudo nginx
```

Installing a Pre-Built Package

Installing NGINX Open Source from a package is much easier and faster comparing to building NGINX from the sources, though it lacks flexibility. Pre-built packages are available for Red Hat, CentOS, Debian, Ubuntu and SLES operating systems.

Modules Included in a Pre-Built Package

See Configure Arguments on nginx.org for the list of modules included in each pre-built package.

Installing Red Hat/CentOS Packages

NGINX provides packages for Red Hat/CentOS 5, 5.x, 6, 6.x, 7 and 7.x. The package can be installed from:

a default Red Hat or CentOS repository. This is the quickest way, but generally the provided package is outdated. For example, CentOS 7.0 by default offers nginx/1.6.2 released in September, 2014.
from NGINX repo. You will have to set up the yum repository once, but the provided package will always be up-to-date.

Installing NGINX package From a Default Red Hat/CentOS Repository

Install the EPEL repository:
```
$ sudo yum install epel-release
```
Update the repository and install NGINX Open Source:
```
$ sudo yum update
```

Verify the installation:

$ sudo nginx -v

nginx version: nginx/1.6.3

Installing From NGINX Repository

Set up the yum repository for RHEL or CentOS by creating a file nginx.repo in /etc/yum.repos.d, for example, using vi:
```
$ sudo vi /etc/yum.repos.d/nginx.repo
```
Add the lines to the file:
```
[nginx]

name=nginx repo

baseurl=http://nginx.org/packages/mainline/OS/OSRELEASE/$basearch/

gpgcheck=0

enabled=1
```
where:
For example, to get the latest mainline package for CentOS 7.0, insert:
```
[nginx]

name=nginx repo

baseurl=http://nginx.org/packages/mainline/centos/7/$basearch/

gpgcheck=0

enabled=1
```
Save the changes and quit vi: press ESC and type-in :wq
Update the repository and install NGINX Open Source:
```
$ sudo yum update
```
Run NGINX Open Source:
```
$ sudo nginx
```

Verify that NGINX Open Source is up and running:

$ curl -I 127.0.0.1

HTTP/1.1 200 OK

Server: nginx/1.11.7

Installing Debian Packages

NGINX provides packages for Debian 7.x (“wheezy”) and 8.x (“jessie”). The package can be installed from:

a default Debian repository. This is the quickest way, but generally the provided package is outdated. For example, Debian 8.2 by default offers nginx/1.6.2 released in September, 2014.
from NGINX repo. You will have to set up the apt-get repository once, but the provided package will always be up-to-date.

Installing NGINX package From a Default Debian Repository

Update Debian repository information:
```
$ sudo apt-get update
```
Install the package:
```
$ sudo apt-get install nginx
```

Verify the installation:

$ sudo nginx -v

nginx version: nginx/1.6.2

Installing From NGINX Repository

Download the key used to sign NGINX packages and repository to the apt program keyring and add it:
```
$ sudo wget http://nginx.org/keys/nginx_signing.key

$ sudo apt-key add nginx_signing.key
```
Add the “sources” from which NGINX Open Source packages can be obtained: open the /etc/apt/sources.list file in any text editor, for example, vi:
```
$ sudo vi /etc/apt/sources.list
```
Add the lines to the file:
```
deb http://nginx.org/packages/mainline/debian/ codename nginx

deb-src http://nginx.org/packages/mainline/debian/ codename nginx
```
where:
- codename is a codename of a Debian release:
  
  Version Codename Supported Platforms
  
  7.x wheezy x86_64, i386
  
  8.x jessie x86_64, i386
- “/mainline” points to the latest mainline verson. Delete to get the latest stable version
For example, to get the latest mainline package for Debian 8.2 (“jessie”), insert:
```
deb http://nginx.org/packages/mainline/debian/ jessie nginx

deb-src http://nginx.org/packages/mainline/debian/ jessie nginx
```
Save the changes and quit vi: press ESC and type-in :wq

Run the commands:

$ sudo apt-get remove nginx-common

$ sudo apt-get update

$ sudo apt-get install nginx

Run NGINX Open Source:
```
$ sudo nginx
```

Verify that NGINX Open Source is up and running:

$ curl -I 127.0.0.1

HTTP/1.1 200 OK

Server: nginx/1.11.7

Installing Ubuntu Packages

NGINX provides packages for Ubuntu 12.04 (“precise”), 14.04 (“trusty”), 15.10 (“wily”) and 16.04 (“xenial”). The package can be installed from:

a default Ubuntu repository. This is the quickest way, but generally the provided package is outdated. For example, Ubuntu 14.04 by default offers nginx/1.4.6 released in March, 2014.
NGINX repo. You will have to set up the apt-get repository once, but the provided package will always be up-to-date.

Installing NGINX package From a Default Ubuntu Repository

Update Ubuntu repository information:
```
$ sudo apt-get update
```
Install the package:
```
$ sudo apt-get install nginx
```
Verify the installation:
```
nginx version: nginx/1.4.6 (Ubuntu)
```

Installing From NGINX Repository

Download the key used to sign NGINX packages and repository to the apt program keyring and add it:
```
$ sudo wget http://nginx.org/keys/nginx_signing.key

$ sudo apt-key add nginx_signing.key
```
Add the “sources” from which NGINX Open Source packages can be obtained: open the /etc/apt/sources.list file in any text editor, for example, vi:
```
$ sudo vi /etc/apt/sources.list
```
Add the lines to the file:
```
deb http://nginx.org/packages/mainline/ubuntu/ codename nginx

deb-src http://nginx.org/packages/mainline/ubuntu/ codename nginx
```
where:
- codename is a codename of an Ubuntu release:
  
  Version Codename Supported Platforms
  
  12.04 precise x86_64, i386
  
  14.04 trusty x86_64, i386, aarch64/arm64
  
  15.10 wily x86_64, i386
  
  16.04 xenial x86_64, i386
- “/mainline” points to the latest mainline verson. Delete to get the latest stable version
For example, to get the latest mainline package for Ubuntu 14.04 (“trusty”), insert:
```
deb http://nginx.org/packages/mainline/ubuntu/ trusty nginx

deb-src http://nginx.org/packages/mainline/ubuntu/ trusty nginx
```
Save the changes and quit vi: press ESC and type-in :wq

Run the commands:

$ sudo apt-get remove nginx-common

$ sudo apt-get update

$ sudo apt-get install nginx

Run NGINX Open Source:
```
$ sudo nginx
```

Verify that NGINX Open Source is up and running:

$ curl -I 127.0.0.1

HTTP/1.1 200 OK

Server: nginx/1.11.7

Installing SUSE Packages

NGINX provides packages for SUSE Linux Enterprise Server 12.

To download and install the latest stable version, run the commands:

$ zypper addrepo -G -t yum -c 'http://nginx.org/packages/sles/12' nginx

$ zypper install nginx

To download and install the latest mainline version, run the commands:

$ zypper addrepo -G -t yum -c 'http://nginx.org/packages/mainline/sles/12' nginx

$ zypper install nginx

Version	Codename	Supported Platforms
7.x	wheezy	x86_64, i386
8.x	jessie	x86_64, i386

Table of Contents

Choosing Between a Stable or a Mainline Version

Choosing Between a Pre-built Package or Compiling From the Sources

Compiling and Installing From the Sources

Installing NGINX Dependencies

Downloading the Sources

Configuring the Build Options

Configuring NGINX Paths

Configuring NGINX GCC Options

Specifying NGINX Connection Processing Methods

NGINX Modules

Modules Built by Default

Modules Not Built by Default

Third Party Modules

Statically Linked Modules

Dynamically Linked Modules

Completing the Installation

Installing a Pre-Built Package

Modules Included in a Pre-Built Package

Installing Red Hat/CentOS Packages

Installing NGINX package From a Default Red Hat/CentOS Repository

Installing From NGINX Repository

Installing Debian Packages

Installing NGINX package From a Default Debian Repository

Installing From NGINX Repository

Installing Ubuntu Packages

Installing NGINX package From a Default Ubuntu Repository

Installing From NGINX Repository

Installing SUSE Packages