Installing NGINX Plus

This article explains how to install NGINX Plus on different operating systems, upgrade existing NGINX Plus installation, install and enable dynamic modules, install in rootless mode or when offline.

Prerequisites

Prerequisites

• An NGINX Plus subscription (purchased or trial)
• Credentials to theMyF5 Customer Portal, provided by email from F5, Inc.
• Asupported operating system
• root privilege

Install NGINX Plus on Amazon Linux 2023

Install NGINX Plus on Amazon Linux 2023

1. Check if your operating system and architecture are supported. For a complete list of supported platforms and architectures, see theTechnical Specifications.

2. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

3. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

4. Install theca-certificates dependency:

   shell

   Copy

   sudo dnf updatesudo dnf install ca-certificates

   sudo dnf updatesudo dnf install ca-certificates

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

   Copy

   sudo mkdir -p /etc/ssl/nginx

   sudo mkdir -p /etc/ssl/nginx

6. Copy the downloaded.crt and.key files to the/etc/ssl/nginx/ directory and make sure they are namednginx-repo.crt andnginx-repo.key:

   shell

   Copy

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

7. Add the NGINX Plus repository to your Amazon Linux 2023 instance. Download theplus-amazonlinux2023.repo file to/etc/yum.repos.d:

   Copy

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

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

8. Install thenginx-plus package. Any older NGINX Plus package is automatically replaced.

   Copy

   sudo dnf install nginx-plus

   sudo dnf install nginx-plus

9. Copy the downloaded JWT file to the/etc/nginx/ directory and make sure it is namedlicense.jwt:

   Copy

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

10. Check thenginx version to verify that NGINX Plus is installed correctly:

    Copy

    nginx -v

    nginx -v

11. Make sure license reporting to F5 licensing endpoint is configured. By default, no configuration is required. However, it becomes necessary when NGINX Plus is installed in a disconnected environment, uses NGINX Instance Manager for usage reporting, or uses a custom path for the license file. Configuration can be done in themgmt {} block of the NGINX Plus configuration file (/etc/nginx/nginx.conf). For more information, seeAbout Subscription Licenses.

12. If you are usingNGINX Instance Manager in your infrastructure, install and enableNGINX Agent. SeeInstall and Configure NGINX Agent for details.

Install NGINX Plus on Amazon Linux 2

Install NGINX Plus on Amazon Linux 2

1. Check if your operating system and architecture are supported. For a complete list of supported platforms and architectures, see theTechnical Specifications.

2. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

3. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

4. Install theca-certificates dependency:

   shell

   Copy

   sudo yum updatesudo yum install ca-certificates

   sudo yum updatesudo yum install ca-certificates

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

   Copy

   sudo mkdir -p /etc/ssl/nginx

   sudo mkdir -p /etc/ssl/nginx

6. Copy the downloaded.crt and.key files to the/etc/ssl/nginx/ directory and make sure they are namednginx-repo.crt andnginx-repo.key:

   shell

   Copy

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

7. Add the NGINX Plus repository to your Amazon Linux 2 instance. Download thenginx-plus-amazon2.repo file to/etc/yum.repos.d:

   Copy

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

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

8. Install thenginx-plus package. Any older NGINX Plus package is automatically replaced.

   Copy

   sudo yum install nginx-plus

   sudo yum install nginx-plus

9. Copy the downloaded JWT file to the/etc/nginx/ directory and make sure it is namedlicense.jwt:

   Copy

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

10. Check thenginx version to verify that NGINX Plus is installed correctly:

    Copy

    nginx -v

    nginx -v

11. Make sure license reporting to F5 licensing endpoint is configured. By default, no configuration is required. However, it becomes necessary when NGINX Plus is installed in a disconnected environment, uses NGINX Instance Manager for usage reporting, or uses a custom path for the license file. Configuration can be done in themgmt {} block of the NGINX Plus configuration file (/etc/nginx/nginx.conf). For more information, seeAbout Subscription Licenses.

12. If you are usingNGINX Instance Manager in your infrastructure, install and enableNGINX Agent. SeeInstall and Configure NGINX Agent for details.

Install NGINX Plus on RHEL 8.1+, Oracle Linux 8.1+, AlmaLinux 8, Rocky Linux 8

Install NGINX Plus on RHEL 8.1+, Oracle Linux 8.1+, AlmaLinux 8, Rocky Linux 8

1. Check if your operating system and architecture are supported. For a complete list of supported platforms and architectures, see theTechnical Specifications.

2. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

3. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

4. Install theca-certificates dependency:

   shell

   Copy

   sudo dnf updatesudo dnf install ca-certificates

   sudo dnf updatesudo dnf install ca-certificates

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

   Copy

   sudo mkdir -p /etc/ssl/nginx

   sudo mkdir -p /etc/ssl/nginx

6. Copy the downloaded.crt and.key files to the/etc/ssl/nginx/ directory and make sure they are namednginx-repo.crt andnginx-repo.key:

   shell

   Copy

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

7. Add the NGINX Plus repository by downloading thenginx-plus-8.repo file to/etc/yum.repos.d:

   Copy

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

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

   Learn how to pin NGINX Plus to a specific version

   Tip: Pin NGINX Plus to a specific version

   To pin NGINX Plus to a specific version (for example, R33):

   1. Edit the/etc/yum.repos.d/nginx-plus-8.repo file.

   2. Update the repository base URL to the desired version:

      Copy

      baseurl=https://pkgs.nginx.com/plus/R33/centos/8/$basearch/

      baseurl=https://pkgs.nginx.com/plus/R33/centos/8/$basearch/

   3. Save the changes and exit.

   4. Update the repository information:

      Copy

      sudo dnf update

      sudo dnf update

   To pin NGINX Plus to a specific version (for example, R33):

   1. Edit the/etc/yum.repos.d/nginx-plus-8.repo file.

   2. Update the repository base URL to the desired version:

      Copy

      baseurl=https://pkgs.nginx.com/plus/R33/centos/8/$basearch/

      baseurl=https://pkgs.nginx.com/plus/R33/centos/8/$basearch/

   3. Save the changes and exit.

   4. Update the repository information:

      Copy

      sudo dnf update

      sudo dnf update

8. Install thenginx-plus package. Any older NGINX Plus package is automatically replaced.

   Copy

   sudo dnf install nginx-plus

   sudo dnf install nginx-plus

9. Copy the downloaded JWT file to the/etc/nginx/ directory and make sure it is namedlicense.jwt:

   Copy

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

10. To enable the NGINX service to start at boot, run the following command:

    Copy

    sudo systemctlenable nginx.service

    sudo systemctlenable nginx.service

11. Check thenginx version to verify that NGINX Plus is installed correctly:

    Copy

    nginx -v

    nginx -v

12. Make sure license reporting to F5 licensing endpoint is configured. By default, no configuration is required. However, it becomes necessary when NGINX Plus is installed in a disconnected environment, uses NGINX Instance Manager for usage reporting, or uses a custom path for the license file. Configuration can be done in themgmt {} block of the NGINX Plus configuration file (/etc/nginx/nginx.conf). For more information, seeAbout Subscription Licenses.

13. If you are usingNGINX Instance Manager in your infrastructure, install and enableNGINX Agent. SeeInstall and Configure NGINX Agent for details.

Install NGINX Plus on RHEL 9.0+, Oracle Linux 9, AlmaLinux 9, Rocky Linux 9

Install NGINX Plus on RHEL 9.0+, Oracle Linux 9, AlmaLinux 9, Rocky Linux 9

1. Check if your operating system and architecture are supported. For a complete list of supported platforms and architectures, see theTechnical Specifications.

2. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

3. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

4. Install theca-certificates dependency:

   shell

   Copy

   sudo dnf updatesudo dnf install ca-certificates

   sudo dnf updatesudo dnf install ca-certificates

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

   Copy

   sudo mkdir -p /etc/ssl/nginx

   sudo mkdir -p /etc/ssl/nginx

6. Copy the downloaded.crt and.key files to the/etc/ssl/nginx/ directory and make sure they are namednginx-repo.crt andnginx-repo.key:

   shell

   Copy

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

7. Add the NGINX Plus repository by downloading theplus-9.repo file to/etc/yum.repos.d:

   Copy

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

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

   Learn how to pin NGINX Plus to a specific version

   Tip: Pin NGINX Plus to a specific version

   To pin NGINX Plus to a specific version (for example, R33):

   1. Edit the/etc/yum.repos.d/plus-9.repo file.

   2. Update the repository base URL to the desired version:

      Copy

      baseurl=https://pkgs.nginx.com/plus/R33/centos/9/$basearch/

      baseurl=https://pkgs.nginx.com/plus/R33/centos/9/$basearch/

   3. Save the changes and exit.

   4. Update the repository information:

      Copy

      sudo dnf update

      sudo dnf update

   To pin NGINX Plus to a specific version (for example, R33):

   1. Edit the/etc/yum.repos.d/plus-9.repo file.

   2. Update the repository base URL to the desired version:

      Copy

      baseurl=https://pkgs.nginx.com/plus/R33/centos/9/$basearch/

      baseurl=https://pkgs.nginx.com/plus/R33/centos/9/$basearch/

   3. Save the changes and exit.

   4. Update the repository information:

      Copy

      sudo dnf update

      sudo dnf update

8. Install thenginx-plus package. Any older NGINX Plus package is automatically replaced.

   Copy

   sudo dnf install nginx-plus

   sudo dnf install nginx-plus

9. Copy the downloaded JWT file to the/etc/nginx/ directory and make sure it is namedlicense.jwt:

   Copy

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

10. To enable the NGINX service to start at boot, run the following command:

    Copy

    sudo systemctlenable nginx.service

    sudo systemctlenable nginx.service

11. Check thenginx version to verify that NGINX Plus is installed correctly:

    Copy

    nginx -v

    nginx -v

12. Make sure license reporting to F5 licensing endpoint is configured. By default, no configuration is required. However, it becomes necessary when NGINX Plus is installed in a disconnected environment, uses NGINX Instance Manager for usage reporting, or uses a custom path for the license file. Configuration can be done in themgmt {} block of the NGINX Plus configuration file (/etc/nginx/nginx.conf). For more information, seeAbout Subscription Licenses.

13. If you are usingNGINX Instance Manager in your infrastructure, install and enableNGINX Agent. SeeInstall and Configure NGINX Agent for details.

Install NGINX Plus on Debian or Ubuntu

Install NGINX Plus on Debian or Ubuntu

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

1. Check if your operating system and architecture are supported. For a complete list of supported platforms and architectures, see theTechnical Specifications.

2. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

3. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

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

   Copy

   sudo mkdir -p /etc/ssl/nginx

   sudo mkdir -p /etc/ssl/nginx

5. Copy the downloaded.crt and.key files to the/etc/ssl/nginx/ directory and make sure they are namednginx-repo.crt andnginx-repo.key:

   shell

   Copy

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

6. Install the prerequisites packages:

   • For Debian:

     shell

     Copy

     sudo apt update&&\sudo apt install apt-transport-https\                 lsb-release\                 ca-certificates\                 wget\                 gnupg2\                 debian-archive-keyring

     sudo apt update&&\sudo apt install apt-transport-https\                 lsb-release\                 ca-certificates\                 wget\                 gnupg2\                 debian-archive-keyring

   • For Ubuntu:

     shell

     Copy

     sudo apt update&&\sudo apt install apt-transport-https\                 lsb-release\                 ca-certificates\                 wget\                 gnupg2\                 ubuntu-keyring

     sudo apt update&&\sudo apt install apt-transport-https\                 lsb-release\                 ca-certificates\                 wget\                 gnupg2\                 ubuntu-keyring

7. Download and add NGINX signing key:

   shell

   Copy

   wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key\| gpg --dearmor\| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

   wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key\| gpg --dearmor\| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

8. Add the NGINX Plus repository:

   • For Debian:

     shell

     Copy

     printf"deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \https://pkgs.nginx.com/plus/debian `lsb_release -cs` nginx-plus\n"\| sudo tee /etc/apt/sources.list.d/nginx-plus.list

     printf"deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \https://pkgs.nginx.com/plus/debian `lsb_release -cs` nginx-plus\n"\| sudo tee /etc/apt/sources.list.d/nginx-plus.list

   • For Ubuntu:

     shell

     Copy

     printf"deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n"\| sudo tee /etc/apt/sources.list.d/nginx-plus.list

     printf"deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n"\| sudo tee /etc/apt/sources.list.d/nginx-plus.list

   Learn how to pin NGINX Plus to a specific version

   Tip: Pin NGINX Plus to a specific version

   To pin NGINX Plus to a specific version (for example, R33):

   1. Edit the/etc/apt/sources.list.d/nginx-plus.list file.

   2. Update the repository base URL to the desired version:

      • For Ubuntu:

        Copy

        https://pkgs.nginx.com/plus/R33/ubuntu

        https://pkgs.nginx.com/plus/R33/ubuntu

      • For Debian:

        Copy

        https://pkgs.nginx.com/plus/R33/debian

        https://pkgs.nginx.com/plus/R33/debian

   3. Save the changes and exit.

   4. Update the repository information:

      Copy

      sudo apt update

      sudo apt update

   To pin NGINX Plus to a specific version (for example, R33):

   1. Edit the/etc/apt/sources.list.d/nginx-plus.list file.

   2. Update the repository base URL to the desired version:

      • For Ubuntu:

        Copy

        https://pkgs.nginx.com/plus/R33/ubuntu

        https://pkgs.nginx.com/plus/R33/ubuntu

      • For Debian:

        Copy

        https://pkgs.nginx.com/plus/R33/debian

        https://pkgs.nginx.com/plus/R33/debian

   3. Save the changes and exit.

   4. Update the repository information:

      Copy

      sudo apt update

      sudo apt update

9. Download thenginx-plus apt configuration to/etc/apt/apt.conf.d:

   Copy

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

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

10. Update the repository information:

    Copy

    sudo apt update

    sudo apt update

11. Install thenginx-plus package. Any older NGINX Plus package is automatically replaced.

    Copy

    sudo apt install -y nginx-plus

    sudo apt install -y nginx-plus

12. Copy the downloaded JWT file to the/etc/nginx/ directory and make sure it is namedlicense.jwt:

    Copy

    sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

    sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

13. Check thenginx version to verify that NGINX Plus is installed correctly:

    Copy

    nginx -v

    nginx -v

14. Make sure license reporting to F5 licensing endpoint is configured. By default, no configuration is required. However, it becomes necessary when NGINX Plus is installed in a disconnected environment, uses NGINX Instance Manager for usage reporting, or uses a custom path for the license file. Configuration can be done in themgmt {} block of the NGINX Plus configuration file (/etc/nginx/nginx.conf). For more information, seeAbout Subscription Licenses.

15. If you are usingNGINX Instance Manager in your infrastructure, install and enableNGINX Agent. SeeInstall and Configure NGINX Agent for details.

Install NGINX Plus on FreeBSD

Install NGINX Plus on FreeBSD

1. Check if your operating system and architecture are supported. For a complete list of supported platforms and architectures, see theTechnical Specifications.

2. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

3. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

4. Install the prerequisiteca_root_nss package:

   shell

   Copy

   sudo pkg updatesudo pkg install ca_root_nss

   sudo pkg updatesudo pkg install ca_root_nss

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

   Copy

   sudo mkdir -p /etc/ssl/nginx

   sudo mkdir -p /etc/ssl/nginx

6. Copy the downloaded.crt and.key files to the/etc/ssl/nginx/ directory and make sure they are namednginx-repo.crt andnginx-repo.key:

   shell

   Copy

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

7. Copy thenginx-plus.conf file to the/etc/pkg/ directory:

   Copy

   sudo fetch -o /etc/pkg/nginx-plus.conf http://cs.nginx.com/static/files/nginx-plus.conf

   sudo fetch -o /etc/pkg/nginx-plus.conf http://cs.nginx.com/static/files/nginx-plus.conf

8. Add the following lines to the/usr/local/etc/pkg.conf file:

   Copy

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

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

9. Install thenginx-plus package. Any older NGINX Plus package is automatically replaced. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

   Copy

   sudo pkg install nginx-plus

   sudo pkg install nginx-plus

10. Copy the downloaded JWT file to the/usr/local/etc/nginx directory and make sure it is namedlicense.jwt:

    Copy

    sudo cp license.jwt /usr/local/etc/nginx

    sudo cp license.jwt /usr/local/etc/nginx

11. Check thenginx version to verify that NGINX Plus is installed correctly:

    Copy

    nginx -v

    nginx -v

12. Make sure license reporting to F5 licensing endpoint is configured. By default, no configuration is required. However, it becomes necessary when NGINX Plus is installed in a disconnected environment, uses NGINX Instance Manager for usage reporting, or uses a custom path for the license file. Configuration can be done in themgmt {} block of the NGINX Plus configuration file (/etc/nginx/nginx.conf). For more information, seeAbout Subscription Licenses.

13. If you are usingNGINX Instance Manager in your infrastructure, install and enableNGINX Agent. SeeInstall and Configure NGINX Agent for details.

Install NGINX Plus on SUSE Linux Enterprise Server

Install NGINX Plus on SUSE Linux Enterprise Server

1. Check if your operating system and architecture are supported. For a complete list of supported platforms and architectures, see theTechnical Specifications.

2. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

3. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

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

   Copy

   sudo mkdir -p /etc/ssl/nginx

   sudo mkdir -p /etc/ssl/nginx

5. Copy the downloaded.crt and.key files to the/etc/ssl/nginx/ directory and make sure they are namednginx-repo.crt andnginx-repo.key:

   shell

   Copy

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

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

   Copy

   cat /etc/ssl/nginx/nginx-repo.crt /etc/ssl/nginx/nginx-repo.key > /etc/ssl/nginx/nginx-repo-bundle.crt

   cat /etc/ssl/nginx/nginx-repo.crt /etc/ssl/nginx/nginx-repo.key > /etc/ssl/nginx/nginx-repo-bundle.crt

7. Install the requiredca-certificates dependency:

   shell

   Copy

   zypper refreshzypper install ca-certificates

   zypper refreshzypper install ca-certificates

8. Add thenginx-plus repo.

   For SLES 12:

   shell

   Copy

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

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

   For SLES 15:

   shell

   Copy

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

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

9. Install thenginx-plus package. Any older NGINX Plus package is automatically replaced.

   Copy

   zypper install nginx-plus

   zypper install nginx-plus

10. Copy the downloaded JWT file to the/etc/nginx/ directory and make sure it is namedlicense.jwt:

    Copy

    sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

    sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

11. Check thenginx version to verify that NGINX Plus is installed correctly:

    Copy

    nginx -v

    nginx -v

12. Make sure license reporting to F5 licensing endpoint is configured. By default, no configuration is required. However, it becomes necessary when NGINX Plus is installed in a disconnected environment, uses NGINX Instance Manager for usage reporting, or uses a custom path for the license file. Configuration can be done in themgmt {} block of the NGINX Plus configuration file (/etc/nginx/nginx.conf). For more information, seeAbout Subscription Licenses.

13. If you are usingNGINX Instance Manager in your infrastructure, install and enableNGINX Agent. SeeInstall and Configure NGINX Agent for details.

Install NGINX Plus on Alpine Linux

Install NGINX Plus on Alpine Linux

1. Check if your operating system and architecture are supported. For a complete list of supported platforms and architectures, see theTechnical Specifications.

2. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

3. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

4. Uploadnginx-repo.key to/etc/apk/cert.key andnginx-repo.crt to/etc/apk/cert.pem. Ensure these files contain only the specific key and certificate — Alpine Linux doesn’t support mixing client certificates for multiple repositories.

5. Put the NGINX signing public key in the/etc/apk/keys directory:

   Copy

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

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

6. Add the NGINX repository to the/etc/apk/repositories file:

   shell

   Copy

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

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

7. Remove all community-supported NGINX packages. Note that this will also remove all NGINX modules:

   Copy

   sudo apk del -r nginx

   sudo apk del -r nginx

8. Install the NGINX Plus package:

   Copy

   sudo apk add nginx-plus

   sudo apk add nginx-plus

9. Copy the downloaded JWT file to the/etc/nginx/ directory and make sure it is namedlicense.jwt:

   Copy

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

10. Check thenginx version to verify that NGINX Plus is installed correctly:

    Copy

    nginx -v

    nginx -v

11. Make sure license reporting to F5 licensing endpoint is configured. By default, no configuration is required. However, it becomes necessary when NGINX Plus is installed in a disconnected environment, uses NGINX Instance Manager for usage reporting, or uses a custom path for the license file. Configuration can be done in themgmt {} block of the NGINX Plus configuration file (/etc/nginx/nginx.conf). For more information, seeAbout Subscription Licenses.

12. If you are usingNGINX Instance Manager in your infrastructure, install and enableNGINX Agent. SeeInstall and Configure NGINX Agent for details.

Install Dynamically Loadable Modules

Install Dynamically Loadable Modules

NGINX Plus functionality can be extended with dynamically loadable modules. They can be added or updated independently of the core binary, enabling powerful capabilities such as advanced security, traffic shaping, telemetry, embedded scripting, geolocation, and many more.

Dynamic modules are shared object files (.so) that can be loaded at runtime using theload_module directive in the NGINX configuration.

Types of dynamic modules

Types of dynamic modules

NGINX-authored dynamic modules

NGINX-authored dynamic modules

NGINX-authored dynamic modules are developed and officially maintained by the F5 NGINX team. These modules are available as packaged binaries for various operating systems and can be installedfrom thenginx-plus repository.

NGINX-certified community dynamic modules

NGINX-certified community dynamic modules

NGINX-certified community dynamic modules are popular third‑party modules tested and distributed by F5 NGINX, with installation and basic configuration support provided. They are also distributed as precompiled packages for various operating systems and can be installedfrom thenginx-plus repository.

Install from official repository

Install from official repository

NGINX‑authored andNGINX‑certified community dynamic modules can be installed as packaged binaries directly from the officialnginx-plus repository.

To install a binary package, run the command in a terminal that corresponds to your operating system, replacing<MODULE-NAME> with the actual binary package name, for example,nginx-plus-module-njs.

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

  shell

  Copy

  sudo yum update&&\sudo yum install <MODULE-NAME>

  sudo yum update&&\sudo yum install <MODULE-NAME>

  The resulting.so file will be installed to:/usr/lib64/nginx/modules/

• For Amazon Linux 2023, AlmaLinux and Rocky Linux:

  shell

  Copy

  sudo dnf update&&\sudo dnf install <MODULE-NAME>

  sudo dnf update&&\sudo dnf install <MODULE-NAME>

  The resulting.so file will be installed to:/usr/lib64/nginx/modules/

• For Debian and Ubuntu:

  shell

  Copy

  sudo apt update&&\sudo apt install <MODULE-NAME>

  sudo apt update&&\sudo apt install <MODULE-NAME>

  The resulting.so file will be installed to:/usr/lib/nginx/modules

• For FreeBSD:

  shell

  Copy

  sudo pkg update&&\sudo pkg install <MODULE-NAME>

  sudo pkg update&&\sudo pkg install <MODULE-NAME>

  The resulting.so file will be installed to:/usr/local/etc/nginx/modules

• For SUSE Linux Enterprise:

  shell

  Copy

  sudo zypper refresh&&\sudo zypper install <MODULE-NAME>

  sudo zypper refresh&&\sudo zypper install <MODULE-NAME>

  The resulting.so file will be installed to:/usr/lib64/nginx/modules/

• For Alpine Linux:

  shell

  Copy

  sudo apk update&&\sudo apk add <MODULE-NAME>

  sudo apk update&&\sudo apk add <MODULE-NAME>

  The resulting.so file will be installed to:/usr/lib/nginx/modules

For detailed description and installation steps for each dynamic module, seeNGINX Plus Dynamic Modules.

Some modules may not be available on specific operating systems due to platform-level limitations. For detailed modules compatibility, see theDynamic Modules section of theNGINX Plus Technical Specifications.

After installing the module, you will need to:

• enable it with theload_module directive
• configure it according to the module’s documentation

Enabling Dynamic Modules

Enabling Dynamic Modules

To enable a dynamic module:

1. In a text editor, open the NGINX Plus configuration file:

   • /etc/nginx/nginx.conf for Linux
   • /usr/local/etc/nginx/nginx.conf for FreeBSD

2. On the top-level (or the “main” context, before anyhttp orstream blocks), specify the path to the.so file with theload_module directive. By default, the files are expected to be in the/modules directory. The path to the directory depends on your operating system:

   • /usr/lib64/nginx/modules/ for most Linux operating systems
   • /usr/lib/nginx/modules for Debian, Ubuntu, Alpine
   • /usr/local/etc/nginx/modules for FreeBSD

   If there are several dynamic modules, specify each module with a separateload_module directive:

   nginx

   Copy

   load_modulemodules/<MODULE-NAME-1>.so;load_modulemodules/<MODULE-NAME-2>.so;http{#...}stream{#...}

   load_modulemodules/<MODULE-NAME-1>.so;load_modulemodules/<MODULE-NAME-2>.so;http{#...}stream{#...}

3. Save the changes.

4. Check the new configuration for syntactic validity:

   Copy

   nginx -t

   nginx -t

5. Reload the NGINX Plus configuration:

   Copy

   nginx -s reload

   nginx -s reload

   After installing the module, you will need to configure the module in the NGINX Plus configuration file. Follow the usage and setup instructions provided in the module’s official documentation.

NGINX Certified Partner dynamic modules

NGINX Certified Partner dynamic modules

NGINX Certified Partner dynamic modules are partner-built extensions that enhance NGINX Plus with advanced features such as security, identity and access management, device detection, application delivery, and many more. These modules are verified throughNGINX’s certification process. Installation packages, documentation, and support are provided directly by the partners.

The complete list of Certified Partner Modules can be found on theF5.com Dynamic Modules page.

Community dynamic modules

Community dynamic modules

Community dynamic modules are open source extensions developed and distributed by third‑party contributors of the NGINX community.

These modules are not available in the official NGINX repository. To use them, you must download the source code from the module’s repository andcompile it against the NGINX Open Source version that matches your NGINX Plus version.

The lists of community modules can be found across different community-driven resources, for example,Awesome NGINX GitHub project.

Installing a community dynamic module

Installing a community dynamic module

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

1. Find out the NGINX Open Source version that matches your NGINX Plus version. In a terminal, run the command:

   Copy

   nginx -v

   nginx -v

   Expected output of the command:

   Copy

   nginx version: nginx/1.27.4(nginx-plus-r34)

   nginx version: nginx/1.27.4(nginx-plus-r34)

2. Prepare the build environment.

   We strongly recommend compiling dynamic modules on a separate system, referred to as the “build environment”. This approach minimizes the risk and complexity for the system where NGINX Plus will be upgraded, referred to as the “production environment”. The build environment should meet the following requirements:

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

   To verify that the required prerequisites are installed in your build environment, run the following commands:

   • For Debian and Ubuntu:

     shell

     Copy

     sudo apt update&&\sudo apt install gcc make libpcre3-dev zlib1g-dev

     sudo apt update&&\sudo apt install gcc make libpcre3-dev zlib1g-dev

   • For CentOS, Oracle Linux, and RHEL:

     shell

     Copy

     sudo yum update&&\sudo yum install gcc make pcre-devel zlib-devel

     sudo yum update&&\sudo yum install gcc make pcre-devel zlib-devel

3. Obtain NGINX Open Source.

   • Identify the NGINX Open Source version that corresponds to your version of NGINX Plus. SeeNGINX Plus Releases.

   • Download the sources for the appropriate NGINX Open Source mainline version, in this case 1.27.4:

     Copy

     wget -qO - https://nginx.org/download/nginx-1.27.4.tar.gz| tar zxfv -

     wget -qO - https://nginx.org/download/nginx-1.27.4.tar.gz| tar zxfv -

4. 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 theNGINX “Hello World” module from GitHub:

   Copy

   git clone https://github.com/perusio/nginx-hello-world-module.git

   git clone https://github.com/perusio/nginx-hello-world-module.git

5. Compile the dynamic module.

   First, establish binary compatibility by running theconfigure script with the‑‑with‑compat option. Then compile the module withmake modules.

   shell

   Copy

   cd nginx-1.27.4/&&\./configure --with-compat --add-dynamic-module=../<MODULE-SOURCES>&&\make modules

   cd nginx-1.27.4/&&\./configure --with-compat --add-dynamic-module=../<MODULE-SOURCES>&&\make modules

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

   Copy

   ls objs/*.so

   ls objs/*.so

   Expected command output:

   Copy

   objs/ngx_http_hello_world_module.so

   objs/ngx_http_hello_world_module.so

6. 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.

   Copy

   cp objs/ngx_http_hello_world_module.so ./ngx_http_hello_world_module_1.27.4.so

   cp objs/ngx_http_hello_world_module.so ./ngx_http_hello_world_module_1.27.4.so

7. Transfer the resulting.so file from your build environment to the production environment.

8. In your production environment, copy the resulting.so file to the dynamic modules directory. The path to the directory depends on your operating system:

   • /usr/lib64/nginx/modules/ for most Linux operating systems
   • /usr/lib/nginx/modules for Debian, Ubuntu, Alpine
   • /usr/local/etc/nginx/modules for FreeBSD
   Copy

   sudo cp ngx_http_hello_world_module_1.27.4.so /usr/local/nginx/modules/ngx_http_hello_world_module_1.27.4.so

   sudo cp ngx_http_hello_world_module_1.27.4.so /usr/local/nginx/modules/ngx_http_hello_world_module_1.27.4.so

After installing the module, you need to enable it in the NGINX Plus configuration file. For more information, seeEnabling Dynamic Modules.

NGINX Plus Unprivileged Installation

NGINX Plus Unprivileged Installation

In some environments, access to the root account is restricted for security reasons. On Linux systems, this limitation prevents the use of package managers to install NGINX Plus without root privileges.

As a workaround, in such environments NGINX Plus can be installed with a special script that modifies NGINX Plus configuration file to allow it to run from a non-root user. This script performs the following actions:

• Downloads the NGINX Plus packages

• Extracts the content of the archives into a user-defined directory of the packages

• Updates the paths in the NGINX configuration file to use relative paths in the specified directory

• Makes a backup copy of the configuration directory

• Provides an option to upgrade an existing unprivileged installation of NGINX Plus

Comparing to a standard installation of NGINX Plus, an unprivileged installation has certain limitations and restrictions:

• Root privileges are still required in order to listen on ports below1024.

• The script is not intended to replace your operating system’s package manager and does not allow for the installation of any software other than NGINX Plus and its modules. Modifications to the script for other installations are not covered by the support program.

• NGINX Plus will not start automatically, so, you must add a custominit script or asystemd unit file for each unprivileged installation on the host.

• all dependencies and libraries required by the NGINX Plus binary and its modules are not installed automatically and should be checked and installed manually.

The script can be run on the following operating systems:

• RedHat, CentOS
• Amazon Linux 2
• Amazon Linux 2023
• Debian, Ubuntu
• Alpine Linux
• AlmaLinux, Rocky Linux

Before starting the unprivileged installation, make sure you have all the prerequisites listed in thePrerequisites section (excludingroot privileges). For RPM-based distributions, verify that you haverpm2cpio installed.

To perform an unprivileged installation of NGINX Plus:

1. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

2. Ensure that the downloaded JWT license file is namedlicense.jwt.

3. Obtain the script:

   Copy

   wget https://raw.githubusercontent.com/nginxinc/nginx-plus-install-tools/main/ngxunprivinst.sh

   wget https://raw.githubusercontent.com/nginxinc/nginx-plus-install-tools/main/ngxunprivinst.sh

4. Make the script executable:

   Copy

   chmod +x ngxunprivinst.sh

   chmod +x ngxunprivinst.sh

5. Download NGINX Plus and its module packages for your operating system. The<cert_file> and<key_file> are your NGINX Plus certificate and a private key required to access the NGINX Plus repo:

   Copy

   ./ngxunprivinst.sh fetch -c <cert_file> -k <key_file>

   ./ngxunprivinst.sh fetch -c <cert_file> -k <key_file>

   If you need to install a particular version of NGINX Plus:

   • first, list all available NGINX Plus versions from the repository:

     Copy

     ./ngxunprivinst.sh list -c <cert_file> -k <key_file>

     ./ngxunprivinst.sh list -c <cert_file> -k <key_file>

   • then specify a particular NGINX Plus version with the-v parameter:

     Copy

     ./ngxunprivinst.sh fetch -c <cert_file> -k <key_file> -v <version>

     ./ngxunprivinst.sh fetch -c <cert_file> -k <key_file> -v <version>

6. Extract the downloaded packages to the program prefix<path> specified by the-p parameter and specify thelicense.jwt<license_file> with the-j parameter. The optional-y parameter allows overwriting an existing installation:

   Copy

   ./ngxunprivinst.sh install[-y] -p <path> -j <license_file> <file1.rpm> <file2.rpm>

   ./ngxunprivinst.sh install[-y] -p <path> -j <license_file> <file1.rpm> <file2.rpm>

7. When the installation procedure is finished, run NGINX Plus. The-p parameter sets a path to the directory that keeps nginx files. The-c parameter sets a path to an alternative NGINX configuration file. Please note NGINX Plus must listen on ports above1024:

   Copy

   <path>/usr/sbin/nginx -p <path>/etc/nginx -c <path>/etc/nginx/conf.d

   <path>/usr/sbin/nginx -p <path>/etc/nginx -c <path>/etc/nginx/conf.d

With this script, you can also upgrade an existing unprivileged installation of NGINX Plus in the provided<path>. The optional-y parameter performs a forced upgrade without any confirmation:

./ngxunprivinst.sh upgrade[-y] -p <path> <file1.rpm> <file2.rpm>

./ngxunprivinst.sh upgrade[-y] -p <path> <file1.rpm> <file2.rpm>

NGINX Plus Offline Installation

NGINX Plus Offline Installation

This section explains how to install NGINX Plus and itsdynamic modules on a server with limited or no Internet access.

To install NGINX Plus offline, you will need a machine connected to the Internet to get the NGINX Plus package, JWT license, SSL certificate and key. Then your can transfer these files to the target server for offline installation.

Step 1: Obtaining files on the machine connected to the Internet

Step 1: Obtaining files on the machine connected to the Internet

1. Download the SSL certificate, private key, and the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   • Log in toMyF5.
   • Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   • Find your NGINX products or services subscription, and select theSubscription ID for details.
   • Download thenginx-repo.crt andnginx-repo.key from the subscription page.
   • Download theJSON Web Token (JWT) from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

2. Transfer the files to the target server that doesn’t have online access and where NGINX Plus will be installed.

Step 2: Installing NGINX Plus on a server without Internet connectivity

Step 2: Installing NGINX Plus on a server without Internet connectivity

1. Back up your NGINX Plus configuration and log files if you have an older NGINX Plus package installed. For more information, seeUpgrading NGINX Plus.

2. Make sure you’ve downloaded the SSL certificate, private key, and the JWT file required for your NGINX Plus subscription. You can find these files in the MyF5 Customer Portal. For details on how to obtain these files, seeStep 1: Obtaining files on the machine connected to the Internet.

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

   Copy

   sudo mkdir -p /etc/ssl/nginx

   sudo mkdir -p /etc/ssl/nginx

4. Copy the downloaded.crt and.key files to the/etc/ssl/nginx/ directory and make sure they are namednginx-repo.crt andnginx-repo.key:

   shell

   Copy

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

   sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crtsudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key

5. Install the NGINX Plus package or a dynamic module. Any older NGINX Plus package is automatically replaced.

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

     Copy

     sudo rpm -ihv <rpm_package_name>

     sudo rpm -ihv <rpm_package_name>

   • For Debian, Ubuntu:

     Copy

     sudo dpkg -i <deb_package_name>

     sudo dpkg -i <deb_package_name>

   • For Alpine:

     Copy

     apk add <apk_package_name>

     apk add <apk_package_name>

   • For SLES:

     Copy

     rpm -ivh <rpm_package_name>

     rpm -ivh <rpm_package_name>

6. Copy the downloaded JWT file to the/etc/nginx/ directory and make sure it is namedlicense.jwt:

   Copy

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

   sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

7. Check thenginx version to verify that NGINX Plus is installed correctly:

   Copy

   nginx -v

   nginx -v

8. Install NGINX Instance Manager 2.18 or later in your local environment to enable usage reporting, which is mandatory since R33. For more information, seeDisconnected environments andAbout Subscription Licenses.

9. Configure usage reporting of the NGINX Plus instance to NGINX Instance Manager which is mandatory starting from R33.

   In thenginx.conf configuration file, specify the following directives:

   • themgmt {} block that handles NGINX Plus licensing and usage reporting configuration,

   • theusage_report directive that sets the domain name or IP address of NGINX Instance Manager,

   • theenforce_initial_report directive that enables the 180-day grace period for sending the initial usage report. The initial usage report must be received by F5 licensing endpoint during the grace period, otherwise traffic processing will be stopped:

   nginx

   Copy

   mgmt{usage_reportendpoint=NIM_FQDN;enforce_initial_reportoff;}

   mgmt{usage_reportendpoint=NIM_FQDN;enforce_initial_reportoff;}

10. In NGINX Instance Manager, prepare and send the usage report to F5 licensing endpoint. For more information, seeReport usage to F5 in a disconnected environment.

11. Upload the usage acknowledgement to NGINX Instance Manager. For more information, seeReport usage to F5 in a disconnected environment.

Upgrade NGINX Plus

Upgrade NGINX Plus

Note: Starting fromRelease 24 (R24), NGINX Plus repositories have been separated into individual repositories based on operating system distribution and license subscription. Before upgrading from previous NGINX Plus versions, you must first reconfigure your repositories to point to the correct location. To reconfigure your repository, follow the installation instructions above for your operating system.

Starting fromRelease 24 (R24), NGINX Plus repositories have been separated into individual repositories based on operating system distribution and license subscription. Before upgrading from previous NGINX Plus versions, you must first reconfigure your repositories to point to the correct location. To reconfigure your repository, follow the installation instructions above for your operating system.

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:

     shell

     Copy

     sudo cp -a /etc/nginx /etc/nginx-plus-backupsudo cp -a /var/log/nginx /var/log/nginx-plus-backup

     sudo cp -a /etc/nginx /etc/nginx-plus-backupsudo cp -a /var/log/nginx /var/log/nginx-plus-backup

   • For FreeBSD:

     shell

     Copy

     sudo cp -a /usr/local/etc/nginx /usr/local/etc/nginx-plus-backupsudo cp -a /var/log/nginx /var/log/nginx-plus-backup

     sudo cp -a /usr/local/etc/nginx /usr/local/etc/nginx-plus-backupsudo cp -a /var/log/nginx /var/log/nginx-plus-backup

2. Get the JWT file associated with your NGINX Plus subscription from the MyF5 Customer Portal:

   1. Log in toMyF5.
   2. Go toMy Products & Plans > Subscriptions to see your active subscriptions.
   3. Find your NGINX products or services subscription, and select theSubscription ID for details.
   4. Download theJSON Web Token from the subscription page.

   Note: Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

   Starting fromNGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, seeAbout Subscription Licenses.

3. Create the/etc/nginx/ directory for Linux or the/usr/local/etc/nginx directory for FreeBSD:

   • For Linux:

     Copy

     sudo mkdir -p /etc/nginx

     sudo mkdir -p /etc/nginx

   • For FreeBSD:

     Copy

     sudo mkdir -p /usr/local/etc/nginx

     sudo mkdir -p /usr/local/etc/nginx

   Using custom paths

   If you plan to use a custom path for the license file, note thatcustom paths won’t work until after the R33 upgrade. You’ll need to create a placeholder file at/etc/nginx/license.jwt or/usr/local/etc/nginx/license.jwt on FreeBSD before upgrading.

   1. Before upgrading: Create the placeholder file by running:

      Copy

      touch /etc/nginx/license.jwt

      touch /etc/nginx/license.jwt

   2. After upgrading: Update thelicense_token directive in the NGINX configurationmgmt block to point to your custom path:

      nginx

      Copy

      mgmt{license_token<custom_path>;}

      mgmt{license_token<custom_path>;}

   If you plan to use a custom path for the license file, note thatcustom paths won’t work until after the R33 upgrade. You’ll need to create a placeholder file at/etc/nginx/license.jwt or/usr/local/etc/nginx/license.jwt on FreeBSD before upgrading.

   1. Before upgrading: Create the placeholder file by running:

      Copy

      touch /etc/nginx/license.jwt

      touch /etc/nginx/license.jwt

   2. After upgrading: Update thelicense_token directive in the NGINX configurationmgmt block to point to your custom path:

      nginx

      Copy

      mgmt{license_token<custom_path>;}

      mgmt{license_token<custom_path>;}

4. After downloading the JWT file, copy it to the/etc/nginx/ directory for Linux, or to the/usr/local/etc/nginx directory for FreeBSD, and make sure it’s namedlicense.jwt:

   • For Linux:

     Copy

     sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

     sudo cp <downloaded-file-name>.jwt /etc/nginx/license.jwt

   • For FreeBSD:

     Copy

     sudo cp <downloaded-file-name>.jwt /usr/local/etc/nginx/license.jwt

     sudo cp <downloaded-file-name>.jwt /usr/local/etc/nginx/license.jwt

5. Upgrade to the new NGINX Plus package.

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

     Copy

     sudo yum upgrade nginx-plus

     sudo yum upgrade nginx-plus

   • For Debian and Ubuntu:

     shell

     Copy

     sudo apt updatesudo apt install nginx-plus

     sudo apt updatesudo apt install nginx-plus

   • For FreeBSD:

     Copy

     sudo pkg upgrade nginx-plus

     sudo pkg upgrade nginx-plus

6. Configure NGINX Plus usage reporting which is mandatory starting from R33. By default, no configuration is required. However, configuration is required in specific scenarios, such as NGINX Plus is installed in an offline environment or if the JWT license file is located in a non-default directory.

   For offline environments, usage reporting should be configured for NGINX Instance Manager 2.18 or later. In thenginx.conf configuration file, specify the following directives:

   • themgmt context handles NGINX Plus licensing and usage reporting configuration,

   • theusage_report directive specifies the domain name or IP address of the NGINX Instance Manager,

   • theenforce_initial_report directive enables a 180-day grace period for sending the initial usage report. The initial usage report must be received by F5 licensing endpoint within this grace period. If the report is not received in time, traffic processing will be stopped:

   nginx

   Copy

   mgmt{usage_reportendpoint=NIM_FQDN;enforce_initial_reportoff;}

   mgmt{usage_reportendpoint=NIM_FQDN;enforce_initial_reportoff;}

   In NGINX Instance Manager, prepare and send the usage report to F5 licensing endpoint. For more information, seeReport usage to F5 in a disconnected environment.

   If the JWT license file is located in a directory other than/etc/nginx/ for Linux orusr/local/etc/nginx/ for FreeBSD, you must specify its name and path in thelicense_token directive:

   nginx

   Copy

   mgmt{license_tokencustom/file/path/license.jwt;}

   mgmt{license_tokencustom/file/path/license.jwt;}

   For more information, seeAbout Subscription Licenses.

7. To verify that the new NGINX Plus version is upgraded, run:

   Copy

   nginx -v

   nginx -v

   The output of the command:

   Copy

   nginx version: nginx/1.27.4(nginx-plus-r34)

   nginx version: nginx/1.27.4(nginx-plus-r34)

Upgrade NGINX Plus Modules

Upgrade NGINX Plus Modules

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

• NGINX‑authored andNGINX‑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.

  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 NGINX Open Source version. SeeInstalling NGINX Community Modules.

Explore Related Topics

Explore Related Topics

Install NGINX App Protect

Install NGINX App Protect

To install NGINX App Protect, follow the steps in theNGINX App Protect installation guide.