This article explains how to install NGINX Open Source.

Table of Contents

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.40.tar.gz
    $ tar -zxf pcre-8.40.tar.gz
    $ cd pcre-8.40
    $ ./configure
    $ make
    $ sudo make install
  • the zlib library – required by NGINX Gzip module for headers compression:
    $ wget http://zlib.net/zlib-1.2.11.tar.gz
    $ tar -zxf zlib-1.2.11.tar.gz
    $ cd zlib-1.2.11
    $ ./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.9.tar.gz
$ tar zxf nginx-1.11.9.tar.gz
$ cd nginx-1.11.9

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

$ wget http://nginx.org/download/nginx-1.10.3.tar.gz
$ tar zxf nginx-1.10.3.tar.gz
$ cd nginx-1.10.3

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.40
--with-zlib=../zlib-1.2.11
--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.40 --with-zlib=../zlib-1.2.11 --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.40 --with-zlib=../zlib-1.2.11 --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

  1. Install the EPEL repository:
    $ sudo yum install epel-release
  2. Update the repository and install NGINX Open Source:
    $ sudo yum update
  3. Verify the installation:
    $ sudo nginx -v
    nginx version: nginx/1.6.3

Installing From NGINX Repository

  1. 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
  2. Add the lines to the file:
    [nginx]
    name=nginx repo
    baseurl=http://nginx.org/packages/mainline/OS/OSRELEASE/$basearch/
    gpgcheck=0
    enabled=1
    where:

      • OS” is either rhel or centos
      • OSRELEASE” is the release number: 5, 5.x, 6, 6.x, 7, 7.x
      • /mainline” points to the latest mainline verson. Delete to get the latest stable version

    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
  3. Save the changes and quit vi: press ESC and type-in :wq
  4. Update the repository and install NGINX Open Source:
    $ sudo yum update
  5. Run NGINX Open Source:
    $ sudo nginx
  6. Verify that NGINX Open Source is up and running:
    $ curl -I 127.0.0.1
    HTTP/1.1 200 OK
    Server: nginx/1.11.9

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

  1. Update Debian repository information:
    $ sudo apt-get update
  2. Install the package:
    $ sudo apt-get install nginx
  3. Verify the installation:
    $ sudo nginx -v
    nginx version: nginx/1.6.2

Installing From NGINX Repository

  1. 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
  2. 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
  3. 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
  4. Save the changes and quit vi: press ESC and type-in :wq
  5. Run the commands:
    $ sudo apt-get remove nginx-common
    $ sudo apt-get update
    $ sudo apt-get install nginx
  6. Run NGINX Open Source:
    $ sudo nginx
  7. Verify that NGINX Open Source is up and running:
    $ curl -I 127.0.0.1
    HTTP/1.1 200 OK
    Server: nginx/1.11.9

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

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

Installing From NGINX Repository

  1. 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
  2. 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
  3. 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
  4. Save the changes and quit vi: press ESC and type-in :wq
  5. Run the commands:
    $ sudo apt-get remove nginx-common
    $ sudo apt-get update
    $ sudo apt-get install nginx
  6. Run NGINX Open Source:
    $ sudo nginx
  7. Verify that NGINX Open Source is up and running:
    $ curl -I 127.0.0.1
    HTTP/1.1 200 OK
    Server: nginx/1.11.9

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