- Install Ops Manager >
- Upgrade Ops Manager
Upgrade Ops Manager¶
On this page
This tutorial describes how to upgrade an existing Ops Manager installation.
Upgrade Path¶
Warning
Ops Manager unintentionally and temporarily disables TLS/SSL when upgrading Ops Manager from version 4.2.0 through 4.2.23 to version 4.4.x. This behavior is a bug and may expose deployments to risk.
Upgrade to Ops Manager 4.2.24 or later, then upgrade to Ops Manager 4.4.
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
- 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.
The following table lists upgrade paths for all versions:
Existing Version | Upgrade Path |
---|---|
4.4.x | Use the procedure on this page to upgrade from Ops Manager 4.4.x to the latest patch version of 4.4.x. |
4.2.x | Use the procedure on this page to upgrade from Ops Manager 4.2.x to 4.2.24 or later first, then to the latest patch version of 4.4. An unintentional and temporary disabling of TLS occurs when upgrading to versions earlier than 4.2.24. Upgrading to 4.2.24 first avoids this outcome. |
4.0.x | Use the v4.2 upgrade tutorial to upgrade from Ops Manager 4.0.x to version 4.2.24 or later. An unintentional and temporary disabling of TLS occurs when upgrading to versions earlier than 4.2.24. Upgrading to 4.2.24 first avoids this outcome. |
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. |
There are no supported downgrade paths for Ops Manager.
- Windows
- Ubuntu/Debian
Important
It is crucial that you back up the existing conf-mms.properties
and gen.key
files because the upgrade process deletes them.
Important
It is crucial that you back up the existing conf-mms.properties
and gen.key
files because the upgrade process deletes them.
Considerations¶
Before upgrading Ops Manager from 4.2 to 4.4, review the following considerations:
Backing Databases¶
Ops Manager 4.4.0 requires a minimum of MongoDB 4.0.0 for Ops Manager backing databases.
Compatible MongoDB Tools¶
If you run Ops Manager 4.4.0 in local mode, you must download and install a compatible version of the MongoDB Tools TGZ package to the Versions Directory.
Ops Manager Server Versions | Compatible MongoDB Database Tools Version |
---|---|
4.4.17, | 100.5.0 |
4.4.11, 4.4.12, 4.4.13, 4.4.14, 4.4.15, 4.4.16, | 100.3.1 |
4.4.10 | 100.3.0 |
4.4.5, 4.4.6, 4.4.7, 4.4.8, 4.4.9 | 100.2.0 |
4.4.2, 4.4.3, 4.4.4 | 100.1.0 |
4.4.0, 4.4.1 | 100.0.2 |
To access older versions of the MongoDB Tools, click Archived releases on the Download page.
Personal API Keys¶
Ops Manager 4.4 deprecates the use of Personal API Keys.
- Can’t create new Personal API Keys.
- Removes support for Personal API Keys in Ops Manager 4.6.
Encryption Using gen.key
File¶
Ops Manager 4.4 requires an identical gen.key
file on each server
hosting an Ops Manager Application or Backup Daemon.
Ops Manager uses the file to encrypt and decrypt Ops Manager’s backing
databases and user credentials. Back up the gen.key
file to a
secure location.
Backup Changes for FCV 4.2 and later¶
Ops Manager no longer supports encrypting cluster snapshots with local key encryption.
Platform Support Changes¶
Ops Manager Microsoft Windows Support Changes¶
- Support for running Ops Manager on the Windows platform ends after the 4.4 series.
- Future releases of Ops Manager still support managing MongoDB deployments that run on Windows.
MongoDB Platform Support Changes¶
- Ops Manager 4.4 removes support for managing MongoDB deployments with the MongoDB Agent
that runs on the following platforms:
- Amazon Linux 1 on the x86_64 architecture
- RHEL 7.x, Ubuntu 16.x on the PowerPC (
ppc64le
) architecture - RHEL 6.x/7.x, Ubuntu 18.x, and SUSE 12.x on zSeries (
s390x
) architecture
Server Pools¶
Ops Manager 4.4 removes support for Server Pools.
Prerequisites¶
Hardware and Software Requirements¶
Your servers must meet the Ops Manager System Requirements.
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 Ops Manager Backup Daemon head database, and
- Each blockstore.
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 Link¶
You must have the download link available on the customer downloads page that MongoDB provided to you. If you do not have this link, you can access the download page for evaluation.
Platform Compatibility¶
Before you upgrade Ops Manager, make sure:
- The platform of the hosts serving Ops Manager is compatible with 4.4.
- The MongoDB Agents managing your MongoDB deployments are compatible with Ops Manager 4.4.
- The platform of the hosts serving the Ops Manager agents are compatible with the Agents.
If you upgraded the platform for the MongoDB Agent hosts, upgrade the MongoDB Agents before upgrading Ops Manager.
Procedure¶
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, you can upgrade Ops Manager to a newer 4.4 version without incurring monitoring downtime. During this upgrade, Ops Manager enters a state known as Upgrade Mode. The benefits of this mode are that 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:
- Windows
- Ubuntu/Debian
- RHEL/CentOS/SLES/AMZ
- Linux
- Log into the first host that serves a Backup Daemon.
- Click the Start button.
- Click Administrative Tools.
- Click Services.
- Right-click the MongoDB Ops Manager Backup Daemon Service and select Stop.
- Repeat steps 2 to 5 with every other Backup Daemon host.
Log into the first host that serves a Backup Daemon.
Issue the following command:
Verify that you shut down the Backup Daemon:
If the Backup Daemon continues to run, issue this command:
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:
Verify that you shut down the Backup Daemon:
If the Backup Daemon continues to run, issue this command:
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:
Verify that you shut down the Backup Daemon:
If the Backup Daemon continues to run, issue this command:
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.
- Windows
- Ubuntu/Debian
- RHEL/CentOS/SLES/AMZ
- Linux
Use this procedure to upgrade the Ops Manager Application on hosts running Microsoft Windows:
Stop your first running Ops Manager instance.¶
To shutdown Ops Manager:
- Click the Start button.
- Click Administrative Tools.
- Click Services.
- Right-click the MongoDB Ops Manager HTTP Service and select Stop.
Uninstall the current version of Ops Manager.¶
To uninstall Ops Manager:
- Click the Start button.
- Click Control Panel.
- Click Programs and Features.
- Right-click MongoDB Ops Manager and select Uninstall.
Important
If you do not uninstall the previous version of Ops Manager, you receive an error message during the upgrade.
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 on MongoDB.com instead of following the link above, click Get MongoDB, then select Ops Manager from the Tools menu.
From the Platforms drop-down menu, click Microsoft Windows Server 2008 R2, 2012, 2012 R2 + 2016.
From the Packages drop-down menu, click MSI.
Click Download.
The downloaded package is named
mongodb-mms-<version>.msi
, where<version>
is the version number.
Install the Ops Manager MSI package on the host that you are upgrading.¶
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:
- Double click the MSI package.
- Follow the instructions in the Setup Wizard.
- During setup, the Configuration/Log Folder step prompts you to specify a folder where the configuration and log files will be stored.
The installation restricts access to the folder to users with the Administrator access privileges only.
Start Ops Manager on the upgraded host.¶
To start the service:
- Click the Start button.
- Click Administrative Tools.
- Click Services.
- In the Services list, right-click the MongoDB Ops Manager HTTP Service and select Start.
[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.
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 arrow right icon Ops Manager arrow right icon Try it now.
From the Platforms dropdown menu, click Ubuntu 18.04.
From the Packages dropdown 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.
Stop your first running Ops Manager instance.¶
Issue the following command to stop the Ops Manager Application:
Install the Ops Manager package on the host that you are upgrading.¶
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: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.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.¶
[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.
Use this procedure to upgrade the Ops Manager Application on hosts installed using rpm
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 arrow right icon Ops Manager arrow right icon Try it now.
From the Platforms dropdown menu, click one of the following options:
- Red Hat + CentOS 7, 8 / SUSE 12 + 15 / Amazon Linux
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.¶
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:
RPM Upgrade to 4.1+ modifies Ops Manager mms.conf
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.
When upgrading to Ops Manager 4.4.11, Ops Manager saves the current
/opt/mongodb/mms/conf/conf-mms.properties
file as the
/opt/mongodb/mms/conf/conf-mms.properties.rpmsave
file.
To avoid having to manually reconfigure Ops Manager, rename
/opt/mongodb/mms/conf/conf-mms.properties.rpmsave
to /opt/mongodb/mms/conf/conf-mms.properties
:
For more information, see 4.4.11 Release Notes.
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:Issue the following commands to symbollically link the Ops Manager files to their
init
files:
[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.
Use this procedure to upgrade Linux systems that do not use
deb
or rpm
packages.
Stop your first running Ops Manager instance.¶
Issue the following command to stop the Ops Manager Application:
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:
Start Ops Manager on the upgraded host.¶
Open your preferred browser to visit the MongoDB Download Center on MongoDB.com.
If you start from MongoDB.com, click Products arrow right icon Ops Manager arrow right icon 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 / SUSE 12 + 15 / Amazon Linux 2
- Debian 9, 10 / 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.¶
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:
Important
To install a new version in the same directory as the old version, follow these steps:
Rename the current installation directory.
Create a new directory with the original name of your old directory.
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:
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.
Start Ops Manager on the upgraded host.¶
Issue the following command:
[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.
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:mms.conf
conf-mms.properties
Remove
-XX:+UseParNewGC
from the config files to resolve this issue.
- 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.
- 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.
- 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.
- Illegal Reflective Access
- This warning displays due to the version of the Guice library that Ops Manager uses. You can safely ignore this warning.