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:

Create the /etc/ssl/nginx directory:

$ sudo mkdir /etc/ssl/nginx
$ cd /etc/ssl/nginx

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/

Install the required ca-certificates dependency:
```
$ sudo yum install ca-certificates
```

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

Install the nginx-plus package. Any older NGINX Plus package is automatically replaced.
```
$ sudo yum install nginx-plus
```
To enable the nginx service start at boot, run the command:
```
$ sudo systemctl enable nginx.service
```

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”)
Ubuntu 18.10 (“Cosmic”)

To install NGINX Plus on Debian or Ubuntu:

Create the /etc/ssl/nginx directory:

$ sudo mkdir /etc/ssl/nginx
$ cd /etc/ssl/nginx

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/

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

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

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

Update the repository information:
```
$ sudo apt-get update
```
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 11.2+ (x86_64)
FreeBSD 12.0+

To install NGINX Plus on FreeBSD:

Create the /etc/ssl/nginx directory:

$ sudo mkdir -p /etc/ssl/nginx
$ cd /etc/ssl/nginx

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/

Install the prerequisite ca_root_nss package:
```
$ sudo pkg install ca_root_nss
```

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

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" }

Install the nginx-plus package. Any older NGINX Plus package is automatically replaced. If you have older NGINX Plus package installed, it is recommended backing up the configuration and log files (see “Upgrading NGINX Plus” for details).
```
$ 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, 15 (x86_64)

To install NGINX Plus on SLES:

Create the /etc/ssl/nginx directory:

$ sudo mkdir /etc/ssl/nginx
$ cd /etc/ssl/nginx

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

Install the required ca-certificates dependency:
```
$ zypper install ca-certificates
```

Add the nginx-plus repo.

For SLES 12:

$ zypper addrepo -G -t yum -c 'https://plus-pkgs.nginx.com/sles/12?ssl_clientcert=/etc/ssl/nginx/nginx-repo-bundle.crt&ssl_verify=peer' nginx-plus

For SLES 15:

$ zypper addrepo -G -t yum -c 'https://plus-pkgs.nginx.com/sles/15?ssl_clientcert=/etc/ssl/nginx/nginx-repo-bundle.crt&ssl_verify=peer' nginx-plus

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:

NGINX-authored dynamic modules – Modules written and maintained by NGINX, Inc. Install these modules directly from the NGINX, Inc. modules repository:
NGINX-certified community dynamic modules – Popular third‑party modules that NGINX tests and distributes, and for which NGINX provides installation and basic configuration support. Install these modules directly from the NGINX, Inc. modules repository:
Community dynamic modules – Modules written and distributed by third‑party members of the NGINX community. Download the source code from the author’s repository and compile it against the NGINX Open Source version corresponding to your NGINX Plus version. For a list, see the NGINX Wiki.

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.

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
```
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 -
```
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
```
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
```
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:

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;
```
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:

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

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.7 (nginx-plus-r17)

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.

Your Cookie Settings

Have a 🍪? :)

NGINX Documentation

Installing NGINX Plus

Table of Contents

Prerequisites

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

Installing NGINX Plus on Debian and Ubuntu

Installing NGINX Plus on FreeBSD

Installing NGINX Plus on SUSE Linux Enterprise Server

Installing Dynamically Loadable Modules

Installing Dynamic Modules from the NGINX, Inc. Repository

Installing NGINX Community Modules

Enabling Dynamic Modules

Upgrading NGINX Plus

Upgrading NGINX Plus Modules

Installing NGINX and NGINX Plus

Installing NGINX Open Source

Need help from NGINX directly?

Navigation

NGINX Documentation

Installing NGINX Plus

Table of Contents

Prerequisites

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

Installing NGINX Plus on Debian and Ubuntu

Installing NGINX Plus on FreeBSD

Installing NGINX Plus on SUSE Linux Enterprise Server

Installing Dynamically Loadable Modules

Installing Dynamic Modules from the NGINX, Inc. Repository

Installing NGINX Community Modules

Enabling Dynamic Modules

Upgrading NGINX Plus

Upgrading NGINX Plus Modules

Installing NGINX and NGINX Plus

Installing NGINX Open Source

Navigation

Need help from NGINX directly?