Installing NGINX Open Source Subscription

Install and upgrade NGINX Open Source Subscription with step-by-step instructions for the base package and dynamic modules on all supported Linux distributions.

This article explains how to install NGINX Open Source Subscription on Alpine Linux, CentOS, Debian, Red Hat Enterprise Linux (RHEL), SUSE Linux Enterprise Server (SLES), Ubuntu, AlmaLinux, Rocky Linux, and Amazon Linux. For a detailed list of supported operating system versions and architectures, see the Technical Specifications.

Prerequisites

An NGINX Open Source Subscription subscription
A supported operating system
root privilege
Credentials to the MyF5 Customer Portal, provided by email from F5, Inc.
Your NGINX Open Source Subscription certificate and public key (nginx-repo.crt and nginx-repo.key files) or your JWT token downloaded from the MyF5 Customer Portal.

Installing NGINX Open Source Subscription on CentOS/RHEL 7.4+

If you already have old NGINX Open Source Subscription packages installed, please see Upgrading NGINX Open Source Subscription.

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 required ca-certificates dependency:

$ sudo yum install ca-certificates

Add NGINX Open Source Subscription repository by downloading and modifying the repo file to /etc/yum.repos.d:

$ sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo

Modify the repo file:

[nginx-oss]
name=nginx-oss repo
baseurl=https://pkgs.nginx.com/open-source/centos/7/$basearch/
sslclientcert=/etc/ssl/nginx/nginx-repo.crt
sslclientkey=/etc/ssl/nginx/nginx-repo.key
gpgcheck=0
enabled=1

Install the nginx-oss package. Any older NGINX Open Source Subscription package is automatically replaced.

$ sudo yum install nginx-oss

To enable the nginx service start at boot, run the command:

$ sudo systemctl enable nginx.service

Check the nginx binary version to ensure that you have NGINX Open Source Subscription installed correctly:

$ nginx -v

Installing NGINX Open Source Subscription on CentOS/RHEL/Oracle/AlmaLinux/Rocky 8.0+

If you already have old NGINX Open Source Subscription packages installed, please see Upgrading NGINX Open Source Subscription.

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 required ca-certificates dependency:

$ sudo dnf install ca-certificates

Add NGINX Open Source Subscription repository by downloading and modifying the repo file to /etc/dnf.repos.d:

$ sudo wget -P /etc/dnf.repos.d https://cs.nginx.com/static/files/nginx-plus-8.repo

Modify the repo file:

[nginx-oss]
name=nginx-oss repo
baseurl=https://pkgs.nginx.com/open-source/centos/8/$basearch/
sslclientcert=/etc/ssl/nginx/nginx-repo.crt
sslclientkey=/etc/ssl/nginx/nginx-repo.key
gpgcheck=0
enabled=1

Install the nginx-oss package. Any older NGINX Open Source Subscription package is automatically replaced.

$ sudo dnf install nginx-oss

To enable the nginx service start at boot, run the command:

$ sudo systemctl enable nginx.service

Check the nginx binary version to ensure that you have NGINX Open Source Subscription installed correctly:

$ nginx -v

Installing NGINX Open Source Subscription on RHEL/Oracle/AlmaLinux/Rocky 9

If you already have old NGINX Open Source Subscription packages installed, please see Upgrading NGINX Open Source Subscription.

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 required ca-certificates dependency:

$ sudo dnf install ca-certificates

Add NGINX Open Source Subscription repository by downloading and modifying the file to /etc/dnf.repos.d:

$ sudo wget -P /etc/dnf.repos.d https://cs.nginx.com/static/files/plus-9.repo

Modify the repo file:

[nginx-oss]
name=nginx-oss repo
baseurl=https://pkgs.nginx.com/open-source/centos/9/$basearch/
sslclientcert=/etc/ssl/nginx/nginx-repo.crt
sslclientkey=/etc/ssl/nginx/nginx-repo.key
gpgcheck=0
enabled=1

Install the nginx-oss package. Any older NGINX Open Source Subscription package is automatically replaced.

$ sudo dnf install nginx-oss

To enable the nginx service start at boot, run the command:

$ sudo systemctl enable nginx.service

Check the nginx binary version to ensure that you have NGINX Open Source Subscription installed correctly:

$ nginx -v

Installing NGINX Open Source Subscription on Debian

If you already have old NGINX Open Source Subscription packages installed, please see Upgrading NGINX Open Source Subscription.

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 and add NGINX signing key and App Protect security updates signing key:

Install the prerequisites packages:

$ sudo apt-get install apt-transport-https lsb-release ca-certificates

Add the NGINX Open Source Subscription repository:

$ printf "deb https://pkgs.nginx.com/open-source/debian `lsb_release -cs` nginx-oss\n" | sudo tee /etc/apt/sources.list.d/nginx-oss.list

Download the nginx-oss apt configuration to /etc/apt/apt.conf.d:

$ sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update the repository information:

$ sudo apt-get update

Install the nginx-oss package. Any older NGINX Open Source Subscription package is automatically replaced.

$ sudo apt-get install -y nginx-oss

Check the nginx binary version to ensure that you have NGINX Open Source Subscription installed correctly:

$ nginx -v

Installing NGINX Open Source Subscription on Ubuntu

If you already have old NGINX Open Source Subscription packages installed, please see Upgrading NGINX Open Source Subscription.

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 prerequisites packages:

$ sudo apt-get install apt-transport-https lsb-release ca-certificates

Add the NGINX Open Source Subscription repository:

$ printf "deb https://pkgs.nginx.com/open-source/ubuntu `lsb_release -cs` nginx-oss\n" | sudo tee /etc/apt/sources.list.d/nginx-oss.list

Download the nginx-oss apt configuration to /etc/apt/apt.conf.d:

$ sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update the repository information:

$ sudo apt-get update

Install the nginx-oss package. Any older NGINX Open Source Subscription package is automatically replaced.

$ sudo apt-get install -y nginx-oss

Check the nginx binary version to ensure that you have NGINX Open Source Subscription installed correctly:

$ nginx -v

Installing NGINX Open Source Subscription on SUSE Linux Enterprise Server

If you already have old NGINX Open Source Subscription packages installed, please see Upgrading NGINX Open Source Subscription.

To install NGINX Open Source Subscription on SLES:

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/

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-oss repo.

For SLES 12:

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

For SLES 15:

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

Install the nginx-oss package. Any older NGINX Open Source Subscription package is automatically replaced.

$ zypper install nginx-oss

Installing NGINX Open Source Subscription on Alpine Linux

To install NGINX Open Source Subscription on Alpine Linux:

If you already have old NGINX Open Source Subscription packages installed, please see Upgrading NGINX Open Source Subscription.

Upload nginx-repo.key to /etc/apk/cert.key and nginx-repo.crt to /etc/apk/cert.pem. Please make sure that files do not contain other certificates and keys: Alpine Linux does not support mixing client certificates for different repositories.

Download the NGINX signing public key to /etc/apk/keys:

$ sudo wget -O /etc/apk/keys/nginx_signing.rsa.pub https://cs.nginx.com/static/keys/nginx_signing.rsa.pub

Add NGINX repository to /etc/apk/repositories file:

$ printf "https://pkgs.nginx.com/open-source/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | sudo tee -a /etc/apk/repositories

It is recommended to remove all community-supported NGINX packages. Please note all NGINX modules will be removed too.

$ sudo apk del -r nginx

Install the NGINX Open Source Subscription package:

$ sudo apk add nginx-oss

Check the nginx binary version to ensure that you have NGINX Open Source Subscription installed correctly:

$ nginx -v

Installing NGINX Open Source Subscription on Amazon Linux 2

If you already have old NGINX Open Source Subscription packages installed, please see Upgrading NGINX Open Source Subscription.

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 required ca-certificates dependency:

$ sudo yum install ca-certificates

Add NGINX Open Source Subscription repository by downloading and modifying the repo file to /etc/yum.repos.d:

$ sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-amazon2.repo

Modify the repo file:

[nginx-oss]
name=nginx-oss repo
baseurl=https://pkgs.nginx.com/open-source/amzn2/$releasever/$basearch/
sslclientcert=/etc/ssl/nginx/nginx-repo.crt
sslclientkey=/etc/ssl/nginx/nginx-repo.key
gpgcheck=0
enabled=1

Install the nginx-oss package. Any older NGINX Open Source Subscription package is automatically replaced.

$ sudo yum install nginx-oss

Check the nginx binary version to ensure that you have NGINX Open Source Subscription installed correctly:

$ nginx -v

Installing NGINX Open Source Subscription on Amazon Linux 2023

If you already have old NGINX Open Source Subscription packages installed, please see Upgrading NGINX Open Source Subscription.

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 required ca-certificates dependency:

$ sudo dnf install ca-certificates

Add Open Source Subscription repository by downloading and modifying the repo file to /etc/dnf.repos.d:

$ sudo wget -P /etc/dnf.repos.d https://cs.nginx.com/static/files/plus-amazonlinux2023.repo

Modify the repo file:

[nginx-oss]
name=nginx-oss repo
baseurl=https://pkgs.nginx.com/open-source/amzn/2023/$basearch/
sslclientcert=/etc/ssl/nginx/nginx-repo.crt
sslclientkey=/etc/ssl/nginx/nginx-repo.key
gpgcheck=0
enabled=1

Install the nginx-oss package. Any older NGINX Open Source Subscription package is automatically replaced.

$ sudo dnf install nginx-oss

Check the nginx binary version to ensure that you have NGINX Open Source Subscription installed correctly:

$ nginx -v

Installing Dynamic Modules from Official Repository

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

For CentOS and RHEL:

$ yum install <module-name>

For Debian and Ubuntu:

$ apt-get install <module-name>

For SLES:

$ zypper install <module-name>

For Alpine Linux:

$ sudo apk add <module-name>

Note that some modules are not available for certain OS versions because of OS limitations. The list of available dynamic modules is included in the Technical Specifications.

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

Installing NGINX Community Modules

For a community dynamic module to work with NGINX Open Source Subscription, it must be compiled alongside the corresponding NGINX Open Source 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 Open Source Subscription 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/RHEL:

$ sudo yum install gcc make pcre-devel zlib-devel

Obtain NGINX Open Source.

Identify the NGINX Open Source version that corresponds to your version of NGINX Open Source Subscription. See NGINX Open Source Subscription Releases.
Download the sources for the appropriate NGINX Open Source mainline version, in this case 1.27.1:

$ wget -qO - https://nginx.org/download/nginx-1.27.1.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.27.1
$ ./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 NGINX Open Source 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.27.1.so

Enabling Dynamic Modules

Dynamic modules are located in the /etc/nginx/modules directory, which is created automatically at NGINX Open Source Subscription 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/ngx_http_hello_world_1.27.1.so;

Check the new configuration for syntactic validity and reload NGINX Open Source Subscription.

$ nginx -t && nginx -s reload

Upgrading NGINX Open Source Subscription

To upgrade your NGINX Open Source Subscription installation to the newest version:

If your system has previous NGINX or NGINX Open Source Subscription packages on it, back up the configuration and log files.

$ sudo cp -a /etc/nginx /etc/nginx-oss-backup
$ sudo cp -a /var/log/nginx /var/log/nginx-oss-backup

Upgrade to the new NGINX Open Source Subscription package.

For CentOS and RHEL:

$ sudo yum upgrade nginx-oss

For Debian and Ubuntu:

$ sudo apt-get update
$ sudo apt-get install nginx-oss

To verify that the new NGINX Open Source Subscription version is upgraded, run:

$ nginx -v
nginx version: nginx/1.27.1 (nginx-oss-r7 p1)

Upgrading NGINX Open Source Subscription Modules

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

NGINX‑authored dynamic modules are updated automatically together with NGINX Open Source Subscription.
Community dynamic modules must be recompiled against the corresponding NGINX Open Source version. See Installing NGINX Community Modules.

Notice

By downloading or otherwise accessing the NGINX Open Source Subscription product, you acknowledge and agree as follows:

the NGINX Open Source Subscription product consists of open-source software which is subject to the license terms referenced or bundled within the applicable software package.
if, and to the extent, F5 provides any patches or updates to the NGINX Open Source Subscription product which include F5 proprietary software, such proprietary software is subject to F5’s End User License Agreement located at https://www.f5.com/pdf/customer-support/end-user-license-agreement.pdf. and
any F5 support and maintenance provided in relation to the NGINX Open Source Subscription product is provided in accordance with, and subject to, the terms of F5’s support and maintenance terms located at: https://www.f5.com/services/support/support-offerings/support-policies.