NGINX Documentation

Installing NGINX Plus

This article explains how to install NGINX Plus on Amazon Linux, CentOS, Debian, FreeBSD, Oracle Linux, Red Hat Enterprise Linux (RHEL), SUSE Linux Enterprise Server (SLES), and Ubuntu.

Prerequisites

  • An NGINX Plus subscription (purchased or trial)
  • A supported operating system
  • root privilege
  • Your credentials to the NGINX Plus Customer Portal, provided by email from NGINX, Inc.
  • Your NGINX Plus certificate and public key (nginx-repo.crt and nginx-repo.key files), provided by email from NGINX, Inc.

Installing NGINX Plus on Amazon Linux, CentOS, Oracle Linux, and RHEL

NGINX Plus can be installed on the following versions of Amazon Linux CentOS/Oracle Linux/RHEL:

  • Amazon Linux 2016.09+ (x86_64)
  • Amazon Linux 2 LTS (x86_64)
  • CentOS/Oracle Linux/ Red Hat Enterprise Linux 6.5+ and 7.0+

To install NGINX Plus on Amazon Linux, CentOS, Oracle Linux, and RHEL:

  1. Create the /etc/ssl/nginx directory:

    $ sudo mkdir /etc/ssl/nginx
    $ cd /etc/ssl/nginx
    
  2. Log in to NGINX Plus Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Copy the files to the /etc/ssl/nginx/ directory:

    $ sudo cp nginx-repo.crt /etc/ssl/nginx/
    $ sudo cp nginx-repo.key /etc/ssl/nginx/
    
  4. Install the required ca-certificates dependency:

    $ sudo yum install ca-certificates
    
  5. Download the nginx-plus-repo file and copy it to the /etc/yum.repos.d/ directory. Each version of Amazon Linux, CentOS, Oracle Linux, or RHEL has its own repo file.

    • For Amazon Linux:

      $ sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-amazon.repo
      
    • For Amazon Linux 2:

      $ sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-amazon2.repo
      
    • For version 6 of CentOS, Oracle Linux, or RHEL:

      $ sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-6.repo
      
    • For version 7.0-7.3 of CentOS, Oracle Linux, or RHEL:

      $ sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.repo
      
    • For version 7.4+ of CentOS, Oracle Linux, or RHEL:

      $ sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo
      
  6. Install the nginx-plus package. Any older NGINX Plus package is automatically replaced.

    $ sudo yum install nginx-plus
    

Installing NGINX Plus on Debian and Ubuntu

NGINX Plus can be installed on the following versions of Debian or Ubuntu:

  • Debian 8 (“Jessie”)
  • Debian 9 (“Stretch”)
  • Ubuntu 14.04 LTS (“Trusty”) (i386, x86_64, aarch64)
  • Ubuntu 16.04 LTS (“Xenial”) (i386, x86_64, ppc64le, aarch64)
  • Ubuntu 18.04 (“Bionic”)

To install NGINX Plus on Debian or Ubuntu:

  1. Create the /etc/ssl/nginx directory:

    $ sudo mkdir /etc/ssl/nginx
    $ cd /etc/ssl/nginx
    
  2. Log in to NGINX Plus Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Copy the files to the /etc/ssl/nginx/ directory:

    $ sudo cp nginx-repo.crt /etc/ssl/nginx/
    $ sudo cp nginx-repo.key /etc/ssl/nginx/
    
  4. Download the NGINX signing key from nginx.org and add it:

    $ sudo wget https://nginx.org/keys/nginx_signing.key
    $ sudo apt-key add nginx_signing.key
    
  5. Install the apt-utils package and the NGINX Plus repository.

    • For Debian:

      $ sudo apt-get install apt-transport-https lsb-release ca-certificates
      $ printf "deb https://plus-pkgs.nginx.com/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list
      
    • For Ubuntu:

      $ sudo apt-get install apt-transport-https lsb-release ca-certificates
      $ printf "deb https://plus-pkgs.nginx.com/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list
      
  6. Download the 90nginx file to /etc/apt/apt.conf.d:

    $ sudo wget -q -O /etc/apt/apt.conf.d/90nginx https://cs.nginx.com/static/files/90nginx
    
  7. Update the repository information:

    $ sudo apt-get update
    
  8. Install the nginx-plus package. Any older NGINX Plus package is automatically replaced.

    $ sudo apt-get install -y nginx-plus
    

Installing NGINX Plus on FreeBSD

NGINX Plus can be installed on the following versions of FreeBSD:

  • FreeBSD 10.4 (x86_64)
  • FreeBSD 11.1+ (x86_64)

To install NGINX Plus on FreeBSD:

  1. Create the /etc/ssl/nginx directory:

    $ sudo mkdir /etc/ssl/nginx
    $ cd /etc/ssl/nginx
    
  2. Log in to NGINX Plus Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Copy the files to the /etc/ssl/nginx/ directory:

    $ sudo cp nginx-repo.crt /etc/ssl/nginx/
    $ sudo cp nginx-repo.key /etc/ssl/nginx/
    
  4. Install the prerequisite ca_root_nss package:

    $ sudo pkg install ca_root_nss
    
  5. Copy the nginx-plus.conf file to the /etc/pkg/ directory:

    $ sudo fetch -O /etc/pkg/nginx-plus.conf http://cs.nginx.com/static/files/nginx-plus.conf
    
  6. Add the following lines to the /usr/local/etc/pkg.conf file:

    PKG_ENV: { SSL_NO_VERIFY_PEER: "1",
    SSL_CLIENT_CERT_FILE: "/etc/ssl/nginx/nginx-repo.crt",
    SSL_CLIENT_KEY_FILE: "/etc/ssl/nginx/nginx-repo.key" }
    
  7. Install the nginx-plus package. Any older NGINX Plus package is automatically replaced.

    $ sudo pkg install nginx-plus
    

Installing NGINX Plus on SUSE Linux Enterprise Server

NGINX Plus can be installed on the following versions of SUSE Linux Enterprise Server:

  • SUSE Linux Enterprise Server 12, 12 SP1 (x86_64)

To install NGINX Plus on SLES:

  1. Create the /etc/ssl/nginx directory:

    $ sudo mkdir /etc/ssl/nginx
    $ cd /etc/ssl/nginx
    
  2. Log in to NGINX Plus Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Create a file bundle of the certificate and key:

    $ cat /etc/ssl/nginx/nginx-repo.crt /etc/ssl/nginx/nginx-repo.key > /etc/ssl/nginx/nginx-repo-bundle.crt
    
  4. Install the required ca-certificates dependency:

    $ zypper install ca-certificates
    
  5. Add the nginx-plus repo:

    $ zypper addrepo -G -t yum -c 'https://plus-pkgs.nginx.com/sles/12?ssl_clientcert=/etc/ssl/nginx/nginx-repo-bundle.crt&ssl_verify=host' nginx-plus
    
  6. Install the nginx-plus package. Any older NGINX Plus package is automatically replaced.

    $ zypper install nginx-plus
    

Installing Dynamically Loadable Modules

NGINX Plus functionality can be extended with dynamically loadable modules that are not included in the prebuilt packages:

Installing Dynamic Modules from the NGINX, Inc. Repository

NGINX‑authored and NGINX‑certified dynamic modules can be installed directly from the modules repository. To install the modules:

  • For Amazon Linux, CentOS, Oracle Linux, and RHEL:

    $ yum install <MODULE-NAME>
    
  • For Debian and Ubuntu:

    $ apt-get install <MODULE-NAME>
    
  • For FreeBSD:

    $ pkg install <MODULE-NAME>
    
  • For SLES:

    $ zypper install <MODULE-NAME>
    

Note that some modules are not available for certain OS versions because of OS limitations. For details as well as descriptions of the modules, see the NGINX Plus Technical Specifications.

After installing the module, you need to enable it in the NGINX Plus configuration file. See Enabling Dynamic Modules for details.

Installing NGINX Community Modules

For a community dynamic module to work with NGINX Plus, it must be compiled alongside the corresponding open source NGINX version.

  1. Prepare the build environment.

    We strongly recommend that you compile dynamic modules on a separate system we will refer to as the “build environment”. Doing so minimizes the risk and complexity of the system you plan to upgrade NGINX Plus on (we will refer to this as the “production environment”). The build environment must meet the following requirements:

    • The same operating system as the production environment
    • The same NGINX version as the production environment
    • Compiler and make utilities
    • PCRE library (development files)
    • Zlib compression libraries (development files)

    To ensure your build environment has these prerequisites installed, run the appropriate command.

    • For Debian and Ubuntu:

      $ sudo apt-get install gcc make libpcre3-dev zlib1g-dev
      
    • For CentOS, Oracle Linux, and RHEL:

      $ sudo yum install gcc make pcre-devel zlib-devel
      
  2. Obtain open source NGINX.

    • Identify the open source NGINX version that corresponds to your version of NGINX Plus. See NGINX Plus Releases.

    • Download the sources for the appropriate open source NGINX version, in this case 1.13.10:

      $ wget -qO - https://nginx.org/download/nginx-1.13.10.tar.gz | tar zxfv -
      
  3. Obtain the source for the dynamic module.

    The source code for the dynamic module can be placed in any directory in the build environment. As an example, here we’re copying the NGINX “Hello World” module from GitHub:

    $ git clone https://github.com/perusio/nginx-hello-world-module.git
    
  4. Compile the dynamic module.

    First establish binary compatibility by running the configure script with the ‑‑with‑compat option. Then compile the module with make modules.

    $ cd nginx-1.13.10/
    $ ./configure --with-compat --add-dynamic-module=../<MODULE-SOURCES>
    $ make modules
    

    The .so file generated by the build process is placed in the objs subdirectory

    $ ls objs/*.so
    objs/ngx_http_hello_world.so
    
  5. Make a copy of the module file and include the open source NGINX version in the filename. This makes it simpler to manage multiple versions of a dynamic module in the production environment.

    $ cp objs/ngx_http_hello_world.so ./ngx_http_hello_world_1.13.10.so
    

Enabling Dynamic Modules

Dynamic modules are located in the /etc/nginx/modules directory, which is created automatically at NGINX Plus installation.

To enable a dynamic module:

  1. In the main (top-level) context in /etc/nginx/nginx.conf, add a load_module directive for each dynamically loadable module you installed.

    load_module modules/<MODULE-NAME>.so;
    
  2. Check the new configuration for syntactic validity and reload NGINX Plus.

    $ nginx -t && nginx -s reload
    

Upgrading NGINX Plus

To upgrade your NGINX Plus installation to the newest version:

  1. If your system has previous NGINX or NGINX Plus packages on it, back up the configuration and log files.

    • For Linux distributions:

      $ sudo cp -a /etc/nginx /etc/nginx-plus-backup
      $ sudo cp -a /var/log/nginx /var/log/nginx-plus-backup
      
    • For FreeBSD:

      $ sudo cp -a /usr/local/etc/nginx /usr/local/etc/nginx-plus-backup
      $ sudo cp -a /var/log/nginx /var/log/nginx-plus-backup
      
  2. Upgrade to the new NGINX Plus package.

    • For Amazon Linux, CentOS, Oracle Linux, and RHEL:

      $ sudo yum upgrade nginx-plus
      

      Note: Before upgrading to version 6.6 of CentOS, Oracle Linux, or RHEL, see this advisory.

    • For Debian and Ubuntu:

      $ sudo apt-get update
      $ sudo apt-get install nginx-plus
      
    • For FreeBSD:

      $ sudo pkg upgrade nginx-plus
      

To verify that the new NGINX Plus version is running, run:

$ nginx -v
nginx version: nginx/1.15.2 (nginx-plus-r16)

Upgrading NGINX Plus Modules

The upgrade procedure depends on how the module was supplied and installed.

  • NGINX‑authored and NGINX‑certified community dynamic modules are updated automatically together with NGINX Plus.

    Note: For FreeBSD, each NGINX‑authored and NGINX‑certified module must be updated separately using FreeBSD package management tool.

  • Community dynamic modules must be recompiled against the corresponding open source NGINX version. See Installing NGINX Community Modules.