Upgrading NGINX Plus

This article explains how to upgrade existing NGINX Plus installation and dynamic modules.

About

Keeping your NGINX Plus installation updated ensures it includes the latest features, security patches, and fixes. Critical bug patches and security updates are provided for the two most recent releases of NGINX Plus. Each NGINX Plus release reaches End of Software Development upon the next version’s release, meaning no new features or routine bug fixes will be added to that version.

Prerequisites

Before upgrading, verify the following:

1. Your operating system is configured to retrieve binary packages from the official NGINX Plus repository: ensure that nginx-plus.crt and nginx-plus.key and repository file are set. See installation instructions for your operating system: Amazon Linux 2023, Amazon Linux 2, RHEL-based 8.1, RHEL-based 9, RHEL-based 10, Debian, Ubuntu, FreeBSD, SLES, Alpine.

2. Your NGINX Plus subscription is active. You can verify your subscription on the MyF5 Customer Portal.

3. For NGINX Plus R33 and later, license reporting is configured. If upgrading from R32 or earlier, add the license file before upgrading and configure usage reporting. See NGINX Plus R32 upgrade note.

Upgrade steps

1. Back up the configuration and log files.

   • For Linux:

     sudo cp -a /etc/nginx /etc/nginx-plus-backup && \
     sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

   • For FreeBSD:

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

2. Upgrade to the newest NGINX Plus package.

   • For RHEL-based:

     sudo yum upgrade nginx-plus

   • For Debian and Ubuntu:

     sudo apt update && \
     sudo apt install nginx-plus

   • For FreeBSD:

     sudo pkg upgrade nginx-plus

3. Verify the upgrade:

   • Check the NGINX Plus version:

     nginx -v

     The output of the command:

     nginx version: nginx/1.29.8 (nginx-plus-r37.0.0)

   • Check the error log:

     tail /var/log/nginx/error.log

Upgrade notes

NGINX Plus R24 and earlier

Starting from Release 24 (R24), NGINX Plus repositories have been separated into individual repositories based on operating system distribution and license subscription. Before upgrading from NGINX Plus R24 and earlier 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: Amazon Linux 2023, Amazon Linux 2, RHEL-based 8.1, RHEL-based 9, Debian or Ubuntu, FreeBSD, SLES.

NGINX Plus R32 and earlier

Starting from NGINX Plus Release 33, a JWT license file is required for each NGINX Plus instance. For more information, see About Subscription Licenses.

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

   1. Log in to MyF5.

2. Go to My Products & Plans > Subscriptions to see your active subscriptions.

3. Find your NGINX subscription, and select the Subscription ID for details.

4. Download the JSON Web Token file from the subscription page.

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

   • For Linux:

     sudo mkdir -p /etc/nginx

   • For FreeBSD:

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

   Using custom paths

If you’re upgrading from NGINX Plus R32 or earlier to R33 or later and plan to use a custom path for the license file, note that the custom path isn’t recognized until after the upgrade. You must first create a placeholder file at /etc/nginx/license.jwt (or /usr/local/etc/nginx/license.jwt on FreeBSD).

1. Before upgrading: Create the placeholder file:

   touch /etc/nginx/license.jwt

2. After upgrading: Update the license_token directive in the mgmt block of the configuration to point to your custom path:

   mgmt {
     license_token <custom_path>;
   }

:::

3. 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 named license.jwt:

   • For Linux:

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

   • For FreeBSD:

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

4. Perform an upgrade.

5. After upgrade, it is possibly necessary to configure NGINX Plus usage reporting. By default, no configuration is required. However, if NGINX Plus is installed in an offline environment or if the JWT license file is located in a non-default directory, extra configuration is required.

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

   • the mgmt context handles NGINX Plus licensing and usage reporting configuration,

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

   • the enforce_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:

   mgmt {
       usage_report endpoint=NIM_FQDN;
       enforce_initial_report off;
   }

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

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

   mgmt {
       license_token custom/file/path/license.jwt;
   }

Upgrade 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 NGINX Open Source version. See Installing NGINX Community Modules.