Navigation
You were redirected from a different version of the documentation. Click here to go back.

Upgrade Ops Manager

    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
    5.0.x Use the procedure on this page to upgrade from Ops Manager 5.0.x to the latest patch version of 5.0.
    4.4.x

    Use the procedure on this page to upgrade from Ops Manager 4.4.x to the latest patch version of 5.0.

    If your current Ops Manager version precedes 4.4.13, MongoDB recommends using the procedure to upgrade to 4.4.13 before upgrading to the latest patch version of 5.0.

    Ops Manager version 4.4.13 fixes a bug that would re-enable Ops Manager instances for API writes during an upgrade.

    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.

    Warning

    To maintain existing settings and availability, back up the following in your current Ops Manager instance:

    • conf-mms.properties and gen.key files to a secure location. The conf-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.
    • Application Database. If the upgrade fails, you need a current backup to restore your Ops Manager instance. Use mongodump to back up your Application Database.

    Considerations

    Before upgrading Ops Manager from 4.2 to 5.0, review the following considerations:

    Backing Databases

    Ops Manager 5.0.0 requires a minimum of MongoDB 4.2.0 for Ops Manager backing databases.

    Personal API Keys

    Ops Manager 5.0 removes the use of Personal API Keys.

    Platform Support Changes

    Ops Manager 5.0 and later make the following changes to supported platforms:

    • Removes support of the Windows platform.
    • Maintains support for managing MongoDB deployments that run on Windows 2016, 2019, 2020.
    • Removes support for managing MongoDB deployments that run on RHEL 7.x on the ppc64le architecture

    Rapid Release Versions

    Rapid Release versions will not be released for Ops Manager 5.0 and later.

    Security Remediation

    Ops Manager upgraded all third party dependencies to recent versions. This addresses existing security vulnerabilities.

    Snapshots during Resharding

    You may not be able to restore a Ops Manager snapshot taken during a resharding operation of a MongoDB 5.0 sharded cluster. A subsequent Ops Manager 5.0.x release will remove this limitation.

    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:

    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:

    Platform Compatibility

    Before you upgrade Ops Manager, make sure:

    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:

    1. Log into the first host that serves a Backup Daemon.

    2. Issue the following command:

      sudo service mongodb-mms-backup-daemon stop
      
    3. 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
      
    4. Repeat steps 2 to 3 with every other Backup Daemon host.

    1. Log into the first host that serves a Backup Daemon.

    2. Issue the following command:

      sudo service mongodb-mms-backup-daemon stop
      
    3. 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
      
    4. Repeat steps 2 to 3 with every other Backup Daemon host.

    1. Log into the first host that serves a Backup Daemon.

    2. Issue the following command:

      <install_dir>/bin/mongodb-mms-backup-daemon stop
      
    3. 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
      
    4. 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:

    1

    Download the latest version of the Ops Manager package.

    1. 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.

    2. From the Platforms drop-down menu, click Ubuntu 18.04.

    3. From the Packages drop-down menu, click DEB for x86_64 architecture.

    4. Click Download.

      The downloaded package is named mongodb-mms-<version>.x86_64.deb, where <version> is the version number.

    2

    Stop your first running Ops Manager instance.

    Issue the following command to stop the Ops Manager Application:

    sudo service mongodb-mms stop
    
    3

    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.

    1. 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
      
    2. When prompted whether to overwrite the currently installed version of mms.conf, you should type Y to replace the existing file.

    3. 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 the JAVA_MMS_UI_OPTS parameter.

    4. 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.

    4

    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.

    5

    [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.

    6

    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:

    1

    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
    
    2

    Download the latest version of the Ops Manager package.

    1. 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.

    2. From the Platforms drop-down menu, click one of the following options:

      • Red Hat + CentOS 6, 7, 8 / SUSE 12 + 15 / Amazon Linux
      • Red Hat 7 (ppc64le) (stable releases only)
      • Red Hat 8 (ppc64le) (stable releases only)
    3. From the Packages drop-down menu, click RPM for x86_64 architecture or RPM (PPC64LE) for ppc64le architecture (RHEL 7 and 8 only) (stable releases only).

    4. Click Download.

      The downloaded package is named mongodb-mms-<version>.x86_64.rpm, where <version> is the version number.

    3

    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:

    sudo rpm -Uvh 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.

    4
    5

    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

    In high availability instances of Ops Manager, the Backup Daemon waits for all nodes to upgrade before starting.

    6

    [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.

    7

    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.

    1

    Stop your first running Ops Manager instance.

    Issue the following command to stop the Ops Manager Application:

    <install_dir>/bin/mongodb-mms stop
    
    2

    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
    
    3

    Start Ops Manager on the upgraded host.

    1. Open your preferred browser to visit the MongoDB Download Center on MongoDB.com.

      If start from MongoDB.com, lick Software arrow right icon Ops Manager arrow right icon Try it now.

    2. From the Version drop-down menu, click one of the provided stable versions.

    3. From the Platform drop-down menu, click one of the following options:

      • Red Hat + CentOS 6, 7, 8 / SUSE 12 + 15 / Amazon Linux 2
      • Red Hat 7 (ppc64le)
      • Debian 9, 10 / Ubuntu 18.04
    4. From the Package drop-down menu, click tar.gz for x86_64 architecture or tar.gz (ppc64le) for ppc64le architecture. (stable releases only)

    5. Click Download.

      The downloaded package is named mongodb-mms-<version>.x86_64.tar.gz, where <version> is the version number.

    4

    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:

    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:

    1. Rename the current installation directory.

      mv <install_dir> <install_dir_old>
      
    2. 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.

    5

    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
    

    Note

    In high availability instances of Ops Manager, the Backup Daemon waits for all nodes to upgrade before starting.

    6

    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.

    7

    Start Ops Manager on the upgraded host.

    Issue the following command:

    <install_dir>/bin/mongodb-mms start
    
    8

    [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.

    9

    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.

    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.
    Configuration Setting Changes

    Ops Manager may replace any changes you made to your configuration file on upgrade, depending on Linux distribution and local configurations.

    When upgrading, you may want to 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 now 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