Upgrade Ops Manager
This tutorial describes how to upgrade an existing Ops Manager installation.
Upgrade Path
Warning
Upgrade Managed Databases to MongoDB 4.4 or Later
Ops Manager 8.0 doesn't support MongoDB 4.2 and earlier. If you're using MongoDB 4.2 or earlier and want to upgrade to Ops Manager 8.0, you must upgrade to at least MongoDB 4.4. If you don't upgrade to at least MongoDB 4.4, Ops Manager fails pre-flight checks and won't start. After upgrading to at least MongoDB 4.4, we still recommend that you upgrade to at least MongoDB 6.0 before upgrading to Ops Manager 8.0.
The version of your existing Ops Manager installation determines the upgrade path you must take to upgrade to Ops Manager 4.4 or later.
Important
If you have an Ops Manager 4.2 or later installation with more than one Ops Manager host pointing to the same Application Database, you can upgrade Ops Manager without incurring monitoring downtime. During this upgrade, Ops Manager enters a state known as Upgrade Mode. See Upgrade Mode for more information.
To ensure a successful upgrade, you must follow the upgrade path for your existing version to perform necessary database migrations.
To protect your data, Ops Manager refuses to start direct upgrades from versions 1.8.x and 2.0.x to version 3.4 or later.
There are no supported downgrade paths for Ops Manager.
Note
All upgrades for Ops Manager versions 6.0.x and later use the same procedure. To upgrade to a higher version, you must first use this procedure upgrade to the latest available patch of your initial version, then use the procedure again to upgrade to the next version. If the following table has additional information related to the upgrade procedure for a given version, review it first.
Important
Live Migration (push) Deprecated or Not Supported for Source Deployments Managed or Monitored by Ops Manager
For source deployments running any MongoDB 6.0.+ versions, where the deployments are managed or monitored by Ops Manager, live migration (push) is not supported.
For source deployments running any MongoDB 5.0 and earlier versions, where the deployments are managed or monitored by Ops Manager, live migration (push) is deprecated.
For source deployments running MongoDB 6.0.+, where the deployments are monitored by Cloud Manager, live migration (push) is supported. To learn more, see Live Migrate Your MongoDB Cluster Monitored by Cloud Manager to Atlas.
The following table lists upgrade paths for all versions:
Existing Version | Upgrade Path |
---|---|
8.0.x | Upgrade from Ops Manager 8.0.x to the latest available patch version of 8.0 using this procedure. To learn more, see Ops Manager 8.0 release notes. |
7.0.x | Upgrade from Ops Manager 7.0.x to the latest available patch version of 7.0. Then upgrade to the latest available version of 8.0. Use this procedure for both upgrades. To learn more, see Ops Manager 7.0 release notes. |
6.0.x | Upgrade from Ops Manager 6.0.x to the latest available patch version of 6.0. Then upgrade to the latest available version of 7.0. Use this procedure for both upgrades. To learn more, see Ops Manager 6.0 release notes. |
5.0.x | Upgrade from Ops Manager 5.0.x to the latest available patch version of 5.0. Then upgrade to the latest available version of 6.0. Use this procedure for both processes. To learn more, see Ops Manager 5.0 release notes. |
4.4.x | Upgrade from Ops Manager 4.4.x to the latest available patch version of 4.4. Then upgrade to the latest available version of 5.0. Use this procedure for both processes. IMPORTANT: Ops Manager version 4.4.13 fixes a bug that would re-enable Ops Manager instances for API writes during an upgrade. To learn more, see: |
4.2.x | Upgrade from Ops Manager 4.2.x to the latest available patch version of 4.2. Then upgrade to the latest available version of 4.4. Use this procedure for both processes. An unintentional and temporary disabling of TLS occurs when upgrading to versions earlier than 4.2.24. Upgrading to 4.2.24 or later first avoids this outcome. To learn more, see: |
4.0.x | Use the v4.2 upgrade tutorial to upgrade from Ops Manager 4.0.x to version 4.2.24 or later. Then use this procedure to upgrade to the latest available version of 4.2. An unintentional and temporary disabling of TLS occurs when upgrading to versions earlier than 4.2.24. Upgrading to 4.2.24 or later first avoids this outcome. To learn more, see: |
3.6.x | Use the
v4.0 upgrade tutorial
to upgrade from Ops Manager 3.6.x to version 4.0.x. |
3.4.x | Use the
v3.6 upgrade tutorial
to upgrade from Ops Manager 3.4.x to version 3.6.x. |
2.x or earlier | Use the
v3.4 upgrade tutorial
to upgrade from Ops Manager 2.x or earlier. |
Warning
To maintain existing settings and availability, back up the following in your current Ops Manager instance:
conf-mms.properties
andgen.key
files to a secure location. Theconf-mms.properties
stores settings for the Ops Manager instance. The gen.key provides details to encrypt and decrypt Ops Managers backing databases and user credentials. Ops Manager might delete these files as part of the upgrade process.
As an extra precaution, you may use mongodump
to create a binary
export of the Application Database. No officially
supported backup method exists for the Application Database. If the
upgrade fails, reach out to MongoDB Support for help fixing the
issue with the Ops Manager version.
Considerations
Before upgrading Ops Manager from 7.0 to 8.0, review the following considerations:
Backing Databases
Ops Manager 8.0.0 requires a minimum of MongoDB 6.0.0 for Ops Manager backing databases.
Note
Your MongoDB version for Ops Manager backing databases can't be later than your Ops Manager version.
Compatible MongoDB Tools
If Ops Manager manages your MongoDB Tools, the tool versions are upgraded when you upgrade Ops Manager.
If you run Ops Manager 8.0.x in local mode, you must download and
install a compatible version of the MongoDB Tools TGZ package to the versions
directory.
To access older versions of the MongoDB Tools, click Archived releases on the Download page.
Ops Manager Platform Support
Removes Ops Manager support for RedHat Enterprise Linux 7.
Removes Ops Manager support for SUSE Linux Enterprise Server 12.
Removes Ops Manager support for Ubuntu 20.04 LTS.
Important
Deprecates Ops Manager support for Amazon Linux v2 LTS.
Deprecates Ops Manager support for Debian 11.
Automation Support Changes
Removes support for automating, monitoring, and backing up MongoDB versions 4.2 and earlier. Ops Manager can only manage databases that run MongoDB 4.4 or higher.
Important
Deprecates support for automating, monitoring, and backing up MongoDB versions 5.0 and earlier.
Note
Queryable backups are not supported when you use config shards.
Prerequisites
Hardware and Software Requirements
Your servers must meet the Ops Manager System Requirements.
Warning
Potential for Production Failure
Your Ops Manager instance can fail in production if you fail to configure the following:
Ops Manager hosts per the Ops Manager System Requirements.
MongoDB hosts per the Production Notes in the MongoDB manual. MongoDB instances in Ops Manager include:
The Ops Manager Application Database,
Each blockstore.
Ensure that all data-bearing members are running before you start the
upgrade process. To determine the status of the replica set members, run
replSetGetStatus
.
If your backing databases run the MMAPv1 storage engine, the upgrade process fails. Ops Manager prompts you to upgrade the storage engine for those backing databases to WiredTiger.
Administrator Privileges
You must have administrator privileges on the servers on which you perform the upgrade.
Download Software from MongoDB
To download the software, click the download link available on the customer downloads page. MongoDB provides the URL of that page to its customers.
If you can't access this link, visit the download page for a current evaluation copy of the Ops Manager software.
If you need an earlier version of the Ops Manager software, visit the Release Archive.
Download Software to Run in Local Mode
If you plan to run Ops Manager in Local Mode, download the MongoDB software to your versions library directory. The required software includes:
All versions of MongoDB Community or Enterprise that you want to install
MongoDB Tools. The version of MongoDB Tools must match the version that the Ops Manager release notes list as compatible with your Ops Manager version.
Platform Compatibility
Before you upgrade Ops Manager, make sure:
The platform of the hosts serving Ops Manager is compatible with 5.0.
The MongoDB Agents managing your MongoDB deployments are compatible with Ops Manager 5.0.
The platform of the hosts serving the Ops Manager agents are compatible with the Agents.
If you use BI Connector, upgrade MongoDB to 4.4 or later.
If you upgraded the platform for the MongoDB Agent hosts, upgrade the MongoDB Agents before upgrading Ops Manager.
Procedure
Note
Upgrade Mode for Highly Available applications
If you have an Ops Manager 4.2 or later installation with more than one Ops Manager host pointing to the same Application Database, you can upgrade Ops Manager without incurring monitoring downtime. During this upgrade, Ops Manager enters a state known as Upgrade Mode. This mode enables the following benefits throughout the upgrade process:
Alerts and monitoring operate
Ops Manager instances remain live
Ops Manager Application may be accessed in read-only mode
Ops Manager APIs that write or delete data are disabled
Your Ops Manager instance stays in Upgrade Mode until all Ops Manager hosts have been upgraded and restarted.
You should not upgrade more than one Ops Manager host at a time.
When Ops Manager enters upgrade mode, the Backup Daemons attempt to stop themselves. This process can fail if the Daemons are in the middle of a long backup job. In this case, do one of the following:
Restart the first Ops Manager instance once the Backup Daemons finish the job.
Stop the Backup Daemons manually.
To manually stop your Backup Daemons:
Log into the first host that serves a Backup Daemon.
Issue the following command:
sudo service mongodb-mms-backup-daemon stop Verify that you shut down the Backup Daemon:
ps -ef | grep mongodb-mms-backup-daemon If the Backup Daemon continues to run, issue this command:
sudo /etc/init.d/mongodb-mms-backup-daemon stop Repeat steps 2 to 3 with every other Backup Daemon host.
Log in to the first host that serves a Backup Daemon.
Issue the following command:
sudo service mongodb-mms-backup-daemon stop Verify that you shut down the Backup Daemon:
ps -ef | grep mongodb-mms-backup-daemon If the Backup Daemon continues to run, issue this command:
sudo /etc/init.d/mongodb-mms-backup-daemon stop Repeat steps 2 to 3 with every other Backup Daemon host.
Log into the first host that serves a Backup Daemon.
Issue the following command:
<install_dir>/bin/mongodb-mms-backup-daemon stop Verify that you shut down the Backup Daemon:
ps -ef | grep mongodb-mms-backup-daemon If the Backup Daemon continues to run, issue this command:
sudo /etc/init.d/mongodb-mms-backup-daemon stop Repeat steps 2 to 3 with every other Backup Daemon host.
If you're running your Ops Manager Application in a high availability configuration, complete this procedure on one Ops Manager host at a time.
Use this procedure to upgrade the Ops Manager Application on hosts installed using deb
packages:
Download the latest version of the Ops Manager package.
Open your preferred browser to visit the MongoDB Download Center on MongoDB.com.
If you start from MongoDB.com, click Products Ops Manager Try it now.
From the Platforms drop-down menu, click Ubuntu 22.04.
From the Packages drop-down menu, click DEB for x86_64 architecture.
Click Download.
The downloaded package is named
mongodb-mms-<version>.x86_64.deb
, where<version>
is the version number.
Install the Ops Manager package on the host that you are upgrading.
Note
Upgrade Mode for Highly Available Ops Manager Applications
If you have an Ops Manager 4.4 installation with more than one Ops Manager host pointing to the same Application Database, this Ops Manager deployment runs with high availability. After you upgrade one Ops Manager host of a highly available Ops Manager deployment, that deployment enters Upgrade Mode.
Install the
.deb
package on each Ops Manager Application and Backup Daemon host. Issue the following command, where<version>
is the version of the.deb
package:sudo dpkg -i mongodb-mms_<version>_x86_64.deb When prompted whether to overwrite the currently installed version of
mms.conf
, you should typeY
to replace the existing file.If you modified the ports or the JVM settings that Ops Manager uses, you need to re-apply those changes to the
mms.conf
file after Ops Manager is upgraded.Warning
Don't add passwords or secrets to JVM arguments in the
mms.conf
file. Ops Manager exposes them as plain text in the diagnostic archives.The upgrade to Ops Manager 4.1 and 4.2 removed the
-d64
flag from theJAVA_MMS_UI_OPTS
parameter.When upgrading to Ops Manager 4.4.11, Ops Manager prompts you to choose which version of the
/opt/mongodb/mms/conf/conf-mms.properties
file it should use. To avoid having to manually reconfigure Ops Manager, choose the current file. For more information, see 4.4.11 Release Notes.
Start Ops Manager on the upgraded host.
sudo service mongodb-mms start
Note
In high availability instances of Ops Manager, the Backup Daemon waits for all nodes to upgrade before starting.
Log into your upgraded Ops Manager host after it restarts. If your login succeeds, the upgrade succeeded.
[Optional] Repeat the preceding steps for all other Ops Manager hosts in your High Availability deployment.
Note
The logs that Ops Manager generates during startup may temporarily pause
at Starting pre-flight checks
while Ops Manager upgrades all its servers
to the same version.
If your upgrade is successful, repeat steps 1 to 4 on the next host in your high availability Ops Manager deployment.
Update all Agents.
Once your upgrade has finished, login to your Ops Manager instance. Ops Manager displays a banner that says One or more agents are out of date.
Click Update All Agents, then confirm the changes.
Important
If Ops Manager manages your MongoDB Tools, the tool versions are upgraded with the agents.
If Ops Manager manages your BI Connector, the BI Connector version is upgraded with the agents.
Use this procedure to upgrade the Ops Manager Application on hosts installed using rpm
packages:
Stop your first running Ops Manager instance.
On RHEL, CentOS, SUSE12 hosts that use systemd, issue the following command to stop the Ops Manager Application:
sudo service mongodb-mms stop
For platforms that use SysVInit
, issue the following command:
sudo /etc/init.d/mongodb-mms stop
Download the latest version of the Ops Manager package.
Open your preferred browser to visit the MongoDB Download Center on MongoDB.com.
If you start from MongoDB.com, click Products Ops Manager Try it now.
From the Platforms dropdown menu, click one of the following options:
Red Hat + CentOS 7, 8, 9 / SUSE 12 + 15 / Amazon Linux 2, Amazon Linux 2023
From the Packages dropdown menu, click RPM.
Click Download.
The downloaded package is named
mongodb-mms-<version>.x86_64.rpm
, where<version>
is the version number.
Install the Ops Manager package on the Ops Manager host that you are upgrading.
Note
Upgrade Mode for Highly Available Ops Manager Applications
If you have an Ops Manager 4.4 installation with more than one Ops Manager host pointing to the same Application Database, this Ops Manager deployment runs with high availability. After you upgrade one Ops Manager host of a highly available Ops Manager deployment, that deployment enters Upgrade Mode.
To install the .rpm
package on the upgraded Ops Manager host, issue
the following command, where <version>
is the Ops Manager version:
sudo rpm -Uvh mongodb-mms-<version>.x86_64.rpm
Warning
rpm
packages for Ops Manager versions 6.0.0, 6.0.1, and 6.0.2
contained incorrect version information that could cause standard
upgrades to fail. If upgrading from any of these versions to
version 6.0.3 or greater, upgrade the package using the
--force
flag:
sudo rpm -Uvh --force mongodb-mms-<version>.x86_64.rpm
When upgrading to Ops Manager 5.0.x, Ops Manager keeps the current
/opt/mongodb/mms/conf/conf-mms.properties
file. Ops Manager
saves the conf-mms.properties
installed with this version as
/opt/mongodb/mms/conf/conf-mms.properties.rpmnew
.
Warning
Don't add passwords or secrets to JVM arguments in the mms.conf
file. Ops Manager exposes them as plain text in the diagnostic archives.
Replace init
files with symlinks
The following existing files block upgrading an Ops Manager 4.2 installation using RPM:
/etc/init.d/mongodb-mms
/etc/init.d/mongodb-mms-backup-daemon
To complete the upgrade:
Issue the following commands to move the old
init
files:sudo mv /etc/init.d/mongodb-mms /etc/init.d/mongodb-mms-5.0 sudo mv /etc/init.d/mongodb-mms-backup-daemon /etc/init.d/ mongodb-mms-backup-daemon-5.0 sudo mv /etc/init.d/mongodb-mms /etc/init.d/mongodb-mms-6.0 sudo mv /etc/init.d/mongodb-mms-backup-daemon /etc/init.d/ mongodb-mms-backup-daemon-6.0 Issue the following commands to symbolically link the Ops Manager files to their
init
files:sudo ln -s /opt/mongodb/mms/bin/mongodb-mms /etc/init.d/mongodb-mms sudo ln -s /opt/mongodb/mms/bin/mongodb-mms-backup-daemon /etc/init.d/mongodb-mms-backup-daemon
Start Ops Manager on the upgraded host.
On RHEL, CentOS, SUSE12 hosts that use systemd, issue the following command:
sudo service mongodb-mms start
For platforms that use SysVInit
, issue the following command:
sudo /etc/init.d/mongodb-mms start
Note
The logs that Ops Manager generates during startup may temporarily pause
at Starting pre-flight checks
while Ops Manager upgrades all its servers
to the same version.
[Optional] Repeat the preceding steps for all other Ops Manager hosts in your High Availability deployment.
Log into the Ops Manager host that you upgraded after it restarts. If your login succeeds, the upgrade succeeded.
If your login succeeded, repeat these steps on the next host in your high availability Ops Manager deployment.
Update all Agents.
Once your upgrade has finished, login to your Ops Manager instance. Ops Manager displays a banner that says One or more agents are out of date.
Click Update All Agents, then confirm the changes.
Important
If Ops Manager manages your MongoDB Tools, the tool versions are upgraded with the agents.
If Ops Manager manages your BI Connector, the BI Connector version is upgraded with the agents.
Use this procedure to upgrade Linux systems that do not use
deb
or rpm
packages.
Back up configuration files on the Ops Manager host.
On the Ops Manager host that you're upgrading, back up your existing configuration files and logs to a directory other than the install directory.
Important
You need the backed-up <install_dir>/conf/conf-mms.properties
file for later in this procedure.
Example
The following commands back up the configuration files and logs to your home directory:
cp -a <install_dir>/conf ~/mms_conf.backup cp -a <install_dir>/logs ~/mms_logs.backup
If the Versions Directory
is in <install_dir>
then back it up.
cp -a <install_dir>/mongodb-releases ~/mms_versions.backup
You must also back up the gen.key
file that Ops Manager uses to
encrypt and decrypt Ops Manager's backing databases and user credentials.
Ops Manager requires an identical gen.key
file on every
server that is part of a highly available Ops Manager deployment.
Download the latest version of the Ops Manager package.
Open your preferred browser to visit the MongoDB Download Center on MongoDB.com.
If you start from MongoDB.com, click Products Ops Manager Try it now.
From the Version dropdown menu, click one of the provided stable versions.
From the Platform dropdown menu, click one of the following options:
Red Hat + CentOS 7, 8, 9 / SUSE 12 + 15 / Amazon Linux 2, Amazon Linux 2023
Debian 9, 10, 11 / Ubuntu 18.04
From the Package dropdown menu, click tar.gz.
Click Download.
The downloaded package is named
mongodb-mms-<version>.x86_64.tar.gz
, where<version>
is the version number.
Install the Ops Manager package on each host that you are upgrading.
Note
Upgrade Mode for Highly Available Ops Manager Applications
If you have an Ops Manager 4.4 installation with more than one Ops Manager host pointing to the same Application Database, this Ops Manager deployment runs with high availability. After you upgrade one Ops Manager host of a highly available Ops Manager deployment, that deployment enters Upgrade Mode.
Navigate to the directory into which you want to install Ops Manager. Extract the archive to that directory:
tar -zxf mongodb-mms-<version>.x86_64.tar.gz
Important
To install a new version in the same directory as the old version, follow these steps:
Rename the current installation directory.
mv <install_dir> <install_dir_old> Create a new directory with the original name of your old directory.
mkdir <install_dir>
This avoids an empty installation directory and code library conflicts.
On each Ops Manager host, restore the backed up logs and configuration files into the Ops Manager installation directory.
All log files should be restored. Most, but not all, configuration file should be restored. Restore:
conf-mms.properties
- The settings for this Ops Manager deployment.
gen.key
- The encryption key for the backing databases of this Ops Manager deployment.
Example
These commands restore the configuration files and logs from your home directory:
cp -a ~/mms_logs.backup <install_dir>/logs cp -a ~/mms_conf.backup/conf-mms.properties <install_dir>/conf/conf-mms.properties cp -a ~/mms_conf.backup/gen.key <install_dir>/conf/gen.key
If you backed up the Versions Directory
previously, restore it to <install_dir
>.
cp -a ~/mms_versions.backup <install_dir>/mongodb-releases.
Note
In high availability instances of Ops Manager, the Backup Daemon waits for all nodes to upgrade before starting.
Optional. On each Ops Manager server, merge any needed changes into the mms.conf
file from your backup.
The mms.conf
file is rarely customized, as it contains port and
JVM configuration settings. If you modified the ports or the JVM settings that Ops Manager uses,
you need to re-apply those changes from your backup
copy to the mms.conf
file after Ops Manager is upgraded.
Warning
Don't add passwords or secrets to JVM arguments in the mms.conf
file. Ops Manager exposes them as plain text in the diagnostic archives.
The upgrade to Ops Manager 4.1 and 4.2 removed the -d64
flag from
the JAVA_MMS_UI_OPTS
parameter.
[Optional] Repeat the preceding steps for all other Ops Manager hosts in your High Availability deployment.
Log into the Ops Manager host that you upgraded after it restarts. If your login succeeds, the upgrade succeeded.
If your login succeeded, repeat these steps on the next host in your high availability Ops Manager deployment.
Update all Agents.
Once your upgrade has finished, login to your Ops Manager instance. Ops Manager displays a banner that says One or more agents are out of date.
Click Update All Agents, then confirm the changes.
Important
If Ops Manager manages your MongoDB Tools, the tool versions are upgraded with the agents.
If Ops Manager manages your BI Connector, the BI Connector version is upgraded with the agents.
Troubleshooting
Unrecognized VM Option
The pre-flight check output or startup log should include an error like
Unrecognized VM option 'UseParNewGC'
. This error may occur if any of
the following files have been edited:
/etc/rc.d/init.d/mongodb-mms
mms.conf
conf-mms.properties
Remove -XX:+UseParNewGC
from the config files to resolve this issue.
Configuration Setting Changes
Depending on your Linux distribution and local configurations, Ops Manager may replace any changes you made to your configuration file on upgrade. In Ops Manager 5.0 and later, if you use RPM packages, Ops Manager no longer updates the configuration file upon upgrade. If a new Ops Manager version requires new properties in the configuration file, you must add them to the file upon upgrade.
When upgrading, update the mongo.mongoUri
value to include the
new parameters introduced with the MongoDB Java driver. By
default, this driver enables retryable reads and retryable writes. If you
set custom logic to retry reads and writes, the attempts may take too long.
To disable these default values, add the following to your connection string:
Example
mongodb://SERVER:PORT/?maxPoolSize=150&retryWrites=false&retryReads=false
Unrecognized VM Option
The pre-flight check output or startup log should include an error like
Unrecognized VM option 'UseParNewGC'
. This error may occur if any of
the following files have been edited:
/etc/rc.d/init.d/mongodb-mms
mms.conf
conf-mms.properties
Remove -XX:+UseParNewGC
from the config files to resolve this issue.
Configuration Setting Changes
Depending on your Linux distribution and local configurations, Ops Manager may replace any changes you made to your configuration file on upgrade. In Ops Manager 5.0 and later, if you use RPM packages, Ops Manager no longer updates the configuration file upon upgrade. If a new Ops Manager version requires new properties in the configuration file, you must add them to the file upon upgrade.
Unrecognized VM Option
The pre-flight check output or startup log should include an error like
Unrecognized VM option 'UseParNewGC'
. This error may occur if any of
the following files have been edited:
/etc/rc.d/init.d/mongodb-mms
mms.conf
conf-mms.properties
Remove -XX:+UseParNewGC
from the config files to resolve this issue.
Configuration Setting Changes
Depending on your Linux distribution and local configurations, Ops Manager may replace any changes you made to your configuration file on upgrade. In Ops Manager 5.0 and later, if you use RPM packages, Ops Manager no longer updates the configuration file upon upgrade. If a new Ops Manager version requires new properties in the configuration file, you must add them to the file upon upgrade.
When upgrading, update the mongo.mongoUri
value to include the
new parameters introduced with the MongoDB Java driver. By
default, this driver enables retryable reads and retryable writes. If you
set custom logic to retry reads and writes, the attempts may take too long.
To disable these default values, add the following to your connection string:
Example
mongodb://SERVER:PORT/?maxPoolSize=150&retryWrites=false&retryReads=false
Illegal Reflective Access
This warning displays due to the version of the Guice library that Ops Manager uses. You can safely ignore this warning.