Upgrade Guide

This guide explains how to upgrade the NGINX Management Suite modules, NGINX Agent, and NGINX Plus.


This guide explains how to upgrade the NGINX Management Suite modules, NGINX Agent, and NGINX Plus to their latest versions, including how to back up your current configuration, run the upgrade script, and verify the results. Also included are instructions for troubleshooting any potential upgrade errors.

See Also:
If you’re upgrading from Instance Manager v1.x, follow the steps in the migration guide to get started. It is not possible to upgrade directly from Instance Manager v1.x to v2.x.

Pre-Upgrade Steps

It’s useful to have an upgrade plan before upgrading. Creating an upgrade plan can help you determine which tasks to complete before and after installing new versions the NGINX Management Suite modules and NGINX Agent.

Review Essential Documentation

Release Notes

Read the release notes for information about the latest features and changes, resolved issues, known issues, and supported upgrade paths.

Tech Specs

Ensure your system meets the recommended requirements and settings NGINX Management Suite:

Verify the Upgrade Path

You can find the supported upgrade paths in the release notes, linked above.

Make sure your current installation can be updated to the target version. You may be able to upgrade directly to the target version, or you may have to upgrade first to an intermediate version.

To see which version of an NGINX Management Suite module is installed, run the following commands:

  • Instance Manager:

    yum info nms-instance-manager
  • API Connectivity Manager:

    yum info nms-api-connectivity-manager
  • Security Monitoring module:

    yum info nms-sm

  • Instance Manager:

    dpkg -s nms-instance-manager
  • API Connectivity Manager:

    dpkg -s nms-api-connectivity-manager
  • Security Monitoring module:

    dpkg -s nms-sm

Schedule a Maintenance Window

Plan the time when the upgrade will take place. Be sure to let users know when the upgrade will take place and how they might be affected.

Upgrades take under a minute for NGINX Management Suite modules and as long for the NGINX Agent. How long the entire upgrade process takes depends on how many NGINX Agents you need to upgrade. Include time for testing and verifying the upgrade as well.

During an upgrade, you will need to stop the NGINX Agent. Stopping the NGINX Agent results in the following conditions:

  • You won’t be able to publish configuration changes;
  • Metrics reporting will be queued and picked up once the NGINX Agent is restarted;
  • Client connections to the NGINX Management Suite host may be disconnected;
  • In the course of the upgrade, users may be logged out and will need to re-authenticate.

Back Up System Files

Follow the steps in the Backup and Recovery Guide to back up essential system files for NGINX Management Suite.

Upgrade a Test Server

We recommend upgrading NGINX Management Suite in a test environment before upgrading your production environment. By doing this, you will be able to identify any potential issues that might interfere with the upgrade.

Upgrade NGINX Management Suite Modules

Instance Manager

API Connectivity Manager


End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Management Suite API Connectivity Manager Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing API Connectivity Manager Module customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

Security Monitoring

Upgrade NGINX Agent

You should upgrade the NGINX Agent whenever you upgrade NGINX Management Suite in order to ensure compatibility between the two versions. Failing to do so could lead to potential issues.

To upgrade the NGINX Agent, take the following steps:

  1. Open an SSH connection to the server where you’ve installed the NGINX Agent and log in.

  2. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade has issues:

    • /etc/nginx-agent
    • config_dirs values for any configuration specified in /etc/nginx-agent/nginx-agent.conf
  3. Stop the NGINX Agent:

    sudo systemctl stop nginx-agent
  4. Install the updated version of the NGINX Agent:

    • CentOS, RHEL, RPM-Based

      sudo yum -y makecache
      sudo yum update -y nginx-agent
    • Debian, Ubuntu, Deb-Based

      sudo apt-get update
      sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold" 
  5. Start the NGINX Agent:

    sudo systemctl start nginx-agent

Upgrade NGINX Plus

We encourage you to upgrade NGINX Plus to take advantage of the latest improvements and features.

  1. Follow the steps to upgrade NGINX Plus for your distribution.

  2. After upgrading NGINX Plus, restart the NGINX Agent:

    sudo systemctl restart nginx-agent