Upgrade Guide

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

Overview

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:

Technical Specifications Guide

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:

CentOS, RHEL, RPM-Based
Debian, Ubuntu, Deb-Based

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 Instance Manager

Select the upgrade procedure that’s appropriate for your environment:

Upgrade Instance Manager from the NGINX Management Suite repo

Upgrade Instance Manager from NGINX Management Suite Repo

This section explains how to upgrade Instance Manager using a Linux package manager – Yum or Apt – to retrieve packages from a public repository. You’ll need to have Internet access to complete these steps.

If you don’t have access to the Internet, refer to the Upgrade in an Offline Environment section.

CentOS, RHEL, RPM-Based
Debian, Ubuntu, Deb-Based

To upgrade to the latest version of the Instance Manger, run the following command:
```
sudo yum update -y nms-instance-manager
```

To upgrade to the latest version of the Instance Manager, run the following command:
```
sudo apt-get update
sudo apt-get install -y --only-upgrade nms-instance-manager
```

Note:

Note, if any NGINX Management Suite modules are installed, one of more of them may need to be upgraded to remain compatible with NGINX Instance Manager. The table of compatible versions can be found here:

Security Monitoring: https://docs.nginx.com/nginx-management-suite/security/releases/release-notes/

API Connectivity Manager: https://docs.nginx.com/nginx-management-suite/acm/releases/release-notes/

Restart the NGINX Management Suite services:

sudo systemctl restart nms
sudo systemctl restart nms-core
sudo systemctl restart nms-dpm
sudo systemctl restart nms-ingestion
sudo systemctl restart nms-integrations

To verify the NGINX Management Services are running, run the following command:
```
ps aufx | grep nms
```
Restart the NGINX web server:
```
sudo systemctl restart nginx
```

After you’ve successfully upgraded Instance Manager, take the following steps to restart the services and optionally reapply SELinux Policies:

Reload NGINX:
```
sudo nginx -s reload
```

(Optional) Reapply the SELinux policy if it’s enabled:

sudo semodule -n -i /usr/share/selinux/packages/nms.pp
sudo /usr/sbin/load_policy
sudo restorecon -F -R /usr/bin/nms-core
sudo restorecon -F -R /usr/bin/nms-dpm
sudo restorecon -F -R /usr/bin/nms-ingestion
sudo restorecon -F -R /usr/lib/systemd/system/nms.service
sudo restorecon -F -R /usr/lib/systemd/system/nms-core.service
sudo restorecon -F -R /usr/lib/systemd/system/nms-dpm.service
sudo restorecon -F -R /usr/lib/systemd/system/nms-ingestion.service
sudo restorecon -F -R /var/lib/nms/modules/manager.json
sudo restorecon -F -R /var/lib/nms/modules.json
sudo restorecon -F -R /var/lib/nms/streaming
sudo restorecon -F -R /var/lib/nms
sudo restorecon -F -R /var/lib/nms/dqlite
sudo restorecon -F -R /var/run/nms
sudo restorecon -F -R /var/lib/nms/modules
sudo restorecon -F -R /var/log/nms

Restart the Instance Manager services:

sudo systemctl restart nms
sudo systemctl restart nms-core
sudo systemctl restart nms-dpm
sudo systemctl restart nms-ingestion
sudo systemctl restart nms-integrations

Make sure to upgrade the NGINX Agent as well.

Upgrade Instance Manager in an offline environment

Upgrade Instance Manager Offline

To upgrade Instance Manager in an offline environment, take the following steps:

CentOS, RHEL, and RPM-Based
Debian, Ubuntu, and Deb-Based

Log in to the MyF5 Customer Portal and download the Instance Manager package files, or use the package provided by your NGINX Sales Team.

Upgrade the Instance Manager package:

sudo yum -y --nogpgcheck update /home/user/nms-instance-manager_<version>.x86_64.rpm

Log in to the MyF5 Customer Portal and download the Instance Manager package files, or use the package provided by your NGINX Sales Team.

Upgrade the Instance Manager package:

sudo apt-get -y install -f /home/user/nms-instance-manager_<version>_amd64.deb

Note:

Note, if any NGINX Management Suite modules are installed, one of more of them may need to be upgraded to remain compatible with NGINX Instance Manager. The table of compatible versions can be found here:

Security Monitoring: https://docs.nginx.com/nginx-management-suite/security/releases/release-notes/

API Connectivity Manager: https://docs.nginx.com/nginx-management-suite/acm/releases/release-notes/

Restart the NGINX Management Suite services:

sudo systemctl restart nms
sudo systemctl restart nms-core
sudo systemctl restart nms-dpm
sudo systemctl restart nms-ingestion
sudo systemctl restart nms-integrations

To verify the NGINX Management Suite services are running, run the following command:
```
ps aufx | grep nms
```
Restart the NGINX web server:
```
sudo systemctl restart nginx
```

After you’ve successfully upgraded Instance Manager, take the following steps to restart the services and optionally reapply SELinux Policies:

Reload NGINX:
```
sudo nginx -s reload
```

(Optional) Reapply the SELinux policy if it’s enabled:

sudo semodule -n -i /usr/share/selinux/packages/nms.pp
sudo /usr/sbin/load_policy
sudo restorecon -F -R /usr/bin/nms-core
sudo restorecon -F -R /usr/bin/nms-dpm
sudo restorecon -F -R /usr/bin/nms-ingestion
sudo restorecon -F -R /usr/lib/systemd/system/nms.service
sudo restorecon -F -R /usr/lib/systemd/system/nms-core.service
sudo restorecon -F -R /usr/lib/systemd/system/nms-dpm.service
sudo restorecon -F -R /usr/lib/systemd/system/nms-ingestion.service
sudo restorecon -F -R /var/lib/nms/modules/manager.json
sudo restorecon -F -R /var/lib/nms/modules.json
sudo restorecon -F -R /var/lib/nms/streaming
sudo restorecon -F -R /var/lib/nms
sudo restorecon -F -R /var/lib/nms/dqlite
sudo restorecon -F -R /var/run/nms
sudo restorecon -F -R /var/lib/nms/modules
sudo restorecon -F -R /var/log/nms

Restart the Instance Manager services:

sudo systemctl restart nms
sudo systemctl restart nms-core
sudo systemctl restart nms-dpm
sudo systemctl restart nms-ingestion
sudo systemctl restart nms-integrations

Make sure to upgrade the NGINX Agent as well.

Upgrade Instance Manager from a Helm chart

Follow the upgrade steps in the Deploy NGINX Management Suite using Helm guide.

Upgrade API Connectivity Manager

Select the upgrade procedure that’s appropriate for your environment:

Upgrade API Connectivity Manager from the NGINX Management Suite repo

Upgrade API Connectivity Manager from NGINX Management Suite Repo

Upgrade API Connectivity Manager from the NGINX Management Suite Repo:

This section explains how to upgrade API Connectivity Manager using a Linux package manager – Yum or Apt – to retrieve packages from a public repository. You’ll need to have Internet access to complete these steps.

CentOS, RHEL, RPM-Based
Debian, Ubuntu, Deb-Based

To upgrade to the latest version of API Connectivity Manager, run the following command:
```
sudo yum update nms-api-connectivity-manager
```
When installing API Connectivity Manager, you may need a newer version of NGINX Management Suite. The installation process will notify you of any version requirements before installing API Connectivity Manager and any dependent packages, including NGINX Management Suite. You may cancel the installation process if a backup of the NGINX Management Suite is needed before upgrading.
Enable the API Connectivity Manager services:
```
sudo systemctl enable nms-acm
```
Restart the API Connectivity Manager services:
```
sudo systemctl restart nms-acm
```
NGINX Management Suite components started this way run by default as the non-root nms user inside the nms group, both of which are created during installation.
To verify the NGINX Management Suite services are running, run the following command:
```
ps aufx | grep nms
```
Restart the NGINX web server:
```
sudo systemctl restart nginx
```

To upgrade to the latest version of API Connectivity Manager, run the following commands:
```
sudo apt-get update
sudo apt-get install --only-upgrade nms-api-connectivity-manager
```
When installing API Connectivity Manager, you may need a newer version of NGINX Management Suite. The installation process will notify you of any version requirements before installing API Connectivity Manager and any dependent packages, including NGINX Management Suite. You may cancel the installation process if a backup of the NGINX Management Suite is needed before upgrading.
Enable the API Connectivity Manager services:
```
sudo systemctl enable nms-acm
```
Restart the API Connectivity Manager services:
```
sudo systemctl restart nms-acm
```
NGINX Management Suite components started this way run by default as the non-root nms user inside the nms group, both of which are created during installation.
To verify the NGINX Management Suite services are running, run the following command:
```
ps aufx | grep nms
```
Restart the NGINX web server:
```
sudo systemctl restart nginx
```

Upgrade Developer Portal from the NGINX Management Suite repo

Upgrade the Developer Portal from NGINX Management Suite Repo

This section explains how to upgrade the Developer Portal using a Linux package manager – Yum or Apt – to retrieve packages from a public repository. You’ll need to have Internet access to complete these steps.

To upgrade the Developer Portal, take the following steps:

CentOS, RHEL, RPM-Based
Debian, Ubuntu, Deb-Based

To install the latest version of the Developer Portal, run the following command:
```
sudo yum update -y nginx-devportal nginx-devportal-ui
```

Enable the following Developer Portal service:

sudo systemctl enable nginx-devportal.service

Restart the Developer Portal service:

sudo systemctl restart nginx-devportal.service

To install the latest version of the Developer Portal, run the following commands:
```
sudo apt-get update
sudo apt-get upgrade -y nginx-devportal nginx-devportal-ui
```

Enable the following Developer Portal service:

sudo systemctl enable nginx-devportal.service

Restart the Developer Portal service:

sudo systemctl restart nginx-devportal.service

Upgrade API Connectivity Manager in an offline environment

Upgrade API Connectivity Manager Offline

To upgrade API Connectivity Manager in an offline environment, take the following steps:

CentOS, RHEL, and RPM-Based
Debian, Ubuntu, and Deb-Based

Log in to the MyF5 Customer Portal and download the API Connectivity Manager package files, or use the package provided by your NGINX Sales Team.

Upgrade the API Connectivity Manager package:

sudo yum --nogpgcheck update /home/user/nms-api-connectivity-manager_<version>.x86_64.rpm

Log in to the MyF5 Customer Portal and download the API Connectivity Manager package files, or use the package provided by your NGINX Sales Team.

Upgrade the API Connectivity Manager package:

sudo apt-get install -f /home/user/nms-api-connectivity-manager_<version>_amd64.deb

When installing API Connectivity Manager, you may need a newer version of NGINX Management Suite. The installation process will notify you of any version requirements before installing API Connectivity Manager and any dependent packages, including NGINX Management Suite. You may cancel the installation process if a backup of the NGINX Management Suite is needed before upgrading.

Enable the API Connectivity Manager services:
```
sudo systemctl enable nms-acm
```
Restart the API Connectivity Manager services:
```
sudo systemctl restart nms-acm
```
NGINX Management Suite components started this way run by default as the non-root nms user inside the nms group, both of which are created during installation.
To verify the NGINX Management Suite services are running, run the following command:
```
ps aufx | grep nms
```
Restart the NGINX web server:
```
sudo systemctl restart nginx  
```

Upgrade DevPortal in an offline environment

Upgrade the Developer Portal Offline

To upgrade the Developer Portal in an offline environment, take the following steps:

CentOS, RHEL, and RPM-Based
Debian, Ubuntu, and Deb-Based

Log in to the MyF5 Customer Portal and download the Developer Portal package files, or use the package provided by your NGINX Sales Team.

Upgrade the Developer Portal packages:

sudo yum -y --nogpgcheck update /home/user/nginx-devportal_<version>.x86_64.rpm
sudo yum -y --nogpgcheck update /home/user/nginx-devportal-ui_<version>.x86_64.rpm

Enable the following Developer Portal service:

sudo systemctl enable nginx-devportal.service

Restart the Developer Portal service:

sudo systemctl restart nginx-devportal.service

Log in to the MyF5 Customer Portal and download the Developer Portal package files, or use the package provided by your NGINX Sales Team.

Upgrade the Developer Portal packages:

sudo apt-get -y install -f /home/user/nginx-devportal_<version>_amd64.deb
sudo apt-get -y install -f /home/user/nginx-devportal-ui_<version>_amd64.deb

Enable the following Developer Portal service:

sudo systemctl enable nginx-devportal.service

Restart the Developer Portal service:

sudo systemctl restart nginx-devportal.service

Upgrade the Security Monitoring module

Important:
Confirm that you have updated Instance Manager to the correct version before upgrading the Security Monitoring module. See the Dependencies with Instance Manager topic for more information.

To upgrade the NGINX Security Monitoring module, take the following steps:

Open an SSH connection to the server where you’ve installed the Security Monitoring module and log in.
Install the updated version of the Security Monitoring module:
- CentOS, RHEL, RPM-Based
```
sudo yum -y makecache
sudo yum update -y nms-sm
```
- Debian, Ubuntu, Deb-Based
```
sudo apt-get update
sudo apt-get install -y nms-sm
```

Upgrade the NGINX Agent

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

Open an SSH connection to the server where you’ve installed the NGINX Agent and log in.
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
Stop the NGINX Agent:
```
sudo systemctl stop nginx-agent
```

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"

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.

Follow the steps to upgrade NGINX Plus for your distribution.
After upgrading NGINX Plus, restart the NGINX Agent:
```
sudo systemctl restart nginx-agent
```

Troubleshooting

For help with common issues and suggested solutions and workarounds, refer to the NGINX Management Suite Troubleshooting Guide.
You can create a support package if you have problems with the upgrade. The support package script packages system and service information into a tar archive for troubleshooting and debugging purposes. If you need to contact NGINX Customer support, they may ask you to provide a support package file.
The AskF5 knowledge base is a helpful place to look for articles related to upgrade issues and solutions.