Upgrade Guide

This guide explains how to upgrade the NGINX Instance Manager server and NGINX Agent.

Before You Begin

Before upgrading, it’s useful to have an upgrade plan. An upgrade plan helps determine what tasks you need to complete before and after installing new versions of Instance Manager and the NGINX Agent.

Review Required Documentation

Review the documentation in this list to understand the requirements for upgrading:

NGINX Instance Manager Release Notes

Read the Instance Manager release notes for information about new features and changes, resolved issues, known issues, and supported upgrade paths.
Technical Specifications Guide

Confirm the recommended system requirements and settings for the version of Instance Manager you’re upgrading to.

Verify the Upgrade Path

Verify that your current version of Instance Manager can be upgraded to the target version. You may be able to upgrade directly to the target version, or you may need to upgrade to an intermediate version first. You can find the supported upgrade paths in the NGINX Instance Manager Release Notes.

To see which version of Instance Manager is installed, run the following command:
- CentOS, RHEL, RPM-Based
- Debian, Ubuntu, Deb-Based
```
yum info nms-instance-manager
```
```
dpkg -s nms-instance-manager
```

Schedule a Maintenance Window

Schedule a time in which you will perform the upgrade. Let users know when the upgrade will occur and how they might be affected.

Upgrading doesn’t take long, just under a minute to upgrade the Instance Manager server and as long to upgrade the NGINX Agent. How long the entire upgrade process takes depends on how many Agents you need to upgrade. Make sure to include time to verify and test the upgrade as well.

During an upgrade, you’ll need to stop the NGINX Agent. When the Agent is stopped, the following conditions occur:

you won’t be able to publish configuration changes,
metrics reporting will be queued and picked up once the Agent is running again,
client connections to Instance Manager may be disconnected, and
users may be logged out and need to reauthenticate after the upgrade.

Upgrade a Test Server

Upgrade Instance Manager in a test environment before upgrading your production server. Upgrading a test server can help identify issues that may slow down or block the upgrade of your production system.

Upgrade NGINX Instance Manager

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.

To install or upgrade Instance Manager from the Yum repository, run the following command:

sudo yum install -y nms-instance-manager

If you encounter a signing key error, try the following steps:

curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key

sudo rpmkeys --import /tmp/nginx_signing.key

To install or upgrade Instance Manager from the Apt repository, run the following command:
```
sudo apt-get update
sudo apt-get install -y nms-instance-manager
```

Post-Upgrade Steps

After an upgrade, 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 NGINX Instance Manager services:
```
sudo systemctl restart nms
```
Don’t forget to upgrade the NGINX Agent.

Upgrade in an Offline Environment

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

Upgrade Steps

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

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

Install the NGINX Instance Manager package:

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

Upgrade the NGINX Instance Manager Package:

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

Install the NGINX Instance Manager package:

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

Upgrade the NGINX Instance Manager Package:

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

Post-Upgrade Steps

After an upgrade, 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 NGINX Instance Manager services:
```
sudo systemctl restart nms
```
Don’t forget to upgrade the NGINX Agent.

Upgrade NGINX Agent

You should upgrade the NGINX Agent whenever you upgrade NGINX Instance Manager to keep the versions in sync. A failure to do so might cause unexpected issues.

Pre-Upgrade Steps

Performing the pre-upgrade tasks in this section helps to ensure that you can successfully recover if the upgrade process has issues.

Make a backup copy of the following locations:
- /etc/nginx-agent
- config_dirs values for any configuration specified in /etc/nginx-agent/nginx-agent.conf

Upgrade Steps

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.
Stop the NGINX Agent:
```
sudo systemctl stop nginx-agent
```

Install the updated version of the NGINX Agent:

curl https://<NGINX-INSTANCE-MANAGER-FQDN>/install/nginx-agent | sudo su -

Start the NGINX Agent:
```
sudo systemctl start nginx-agent
```

Troubleshooting

If you experience problems with the upgrade, follow the steps to create a support package. The support package script packages system and service information into a tar archive for troubleshooting and debugging purposes.

If you need help with troubleshooting, contact NGINX Customer Support.

You can search for Instance Manager troubleshooting guides and knowledge base articles on the AskF5 site.