Navigation
This version of the documentation is archived and no longer supported. To learn how to upgrade your version of MongoDB Ops Manager, refer to the upgrade documentation.
You were redirected from a different version of the documentation. Click here to go back.
This version of the manual is no longer supported.

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.2 or later.

    Important

    • To ensure a successful upgrade, you must:
      • Follow the upgrade path for your existing version to perform necessary database migrations.
      • Upgrade versions in chronological order. Your new release must have been released after the version you are upgrading.
    • 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.
    • To upgrade high availability environments, you must shut down every Ops Manager application server before starting any Ops Manager application servers upgraded to the new version.

    The following table lists upgrade paths for all versions:

    Existing Version Upgrade Path
    4.2.x

    Use this tutorial to upgrade from Ops Manager 4.2.x to 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.

    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.

    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.0 to 4.2, review the following considerations:

    Backup

    Backup support for MongoDB 4.2 with "featureCompatibilityVersion" : 4.2 is currently limited. Support will be extended in future releases of Ops Manager.

    Backup Features Supported at Present

    Feature MongoDB 4.2 with FCV : 4.2 MongoDB 4.2 with FCV : 4.0 MongoDB 4.0 or earlier
    Backs up Data using WiredTiger Snapshots check circle icon    
    Backs up Data using the Backup Daemon   check circle icon check circle icon
    Backs up Replica Sets check circle icon check circle icon check circle icon
    Backs up Sharded Clusters check circle icon check circle icon check circle icon
    Can Filter using Namespaces   check circle icon check circle icon
    Can Specify Sync Source Database   check circle icon check circle icon
    Can Restore Data to Specific Point in Time check circle icon check circle icon check circle icon
    Can Perform Incremental Backups [*] check circle icon check circle icon check circle icon
    Supports Snapshots that use Encryption check circle icon [†] check circle icon check circle icon
    Supports Saving to Blockstore Snapshot Storage check circle icon check circle icon check circle icon
    Supports Saving to S3 Snapshot Storage check circle icon check circle icon check circle icon
    Supports Saving to File System Storage   check circle icon check circle icon
    Supports Databases running MongoDB Enterprise check circle icon check circle icon check circle icon
    Supports Databases running MongoDB Community   check circle icon check circle icon
    Requires a MongoDB Agent with backup enabled on every mongod cluster node check circle icon    
    [*]Ops Manager requires a full backup for your first backup, after a snapshot has been deleted, and if the blockstore block size has been changed. Incremental backups reduce network transfer and storage costs. This feature works with MongoDB 4.2.6 or later.
    [†]

    Ops Manager supports encrypted snapshots as of version 4.2.16.

    Querying an encrypted snapshot requires MongoDB Enterprise 4.2.9 or 4.4.0.

    Requirements and Limitations

    To run backups and restores if you are running MongoDB 4.2 with "featureCompatibilityVersion" : 4.2, you:

    • Must run MongoDB Enterprise.
    • Cannot use namespace filter lists to define the namespaces included in a backup. Snapshots using FCV 4.2 always include all namespaces.
    • Cannot specify a sync source database. For FCV 4.2 replica sets, no Initial Sync step is required. When taking a Snapshot, Ops Manager selects the replica set member with the least performance impact and greatest storage-level duplication of Snapshot data.
    • Cannot save your backup to a file system store. Backup supports MongoDB and S3 Snapshot Storage.
    • Must deploy a MongoDB Agent with every mongod node in the cluster.

    Note

    If Ops Manager doesn’t manage your cluster:

    • Grant the backup permission to the MongoDB user that runs backups.
    • Ensure that the operating system user that runs the MongoDB Agent has read permission for all data files (including journal files) of the deployment.

    Backing Databases

    Consider converting your backing databases to use the WiredTiger storage engine. Ops Manager supports MongoDB 4.0.x and 4.2.x. MongoDB 4.2 removed the MMAPv1 storage engine.

    MongoDB Agent

    • MongoDB Agent doesn’t support automation of MongoDB 2.6 and 3.0.
    • Customers using Kerberos (GSSAPI) authentication for unmanaged Monitoring and/or Backup Agents must create a single new GSSAPI principal for the combined MongoDB Agent.
    • MongoDB Agent doesn’t support the sslRequireValidServerCertificates parameter. You can no longer use the workaround of manually managed Monitoring and Backup Agents.

    Automation

    The Version Manager has been removed. All versions now can be used and Ops Manager internally determines which versions the MongoDB Agent needs to have available in its configuration. The ability to configure custom builds has been retained.

    Network

    When using Ops Manager in IPv6-only environments, any connections to the internet must support dual-stack IPv4/IPv6.

    Kubernetes

    When you use the Kubernetes Operator and upgrade Ops Manager, upgrade to Ops Manager 4.2.1. If you must remain on 4.2.0, change to your Kubernetes StatefulSet to restart your MongoDB Agents and trigger a rolling restart of all the database pods. This issue doesn’t exist in Ops Manager 4.2.1 or later.

    Upgrade Versions in Chronological Order

    When you upgrade to another version, make sure the new version has a release_date that was released after the date of the version you want to upgrade. You might have this issue when upgrading from the current version (4.2) to rapid release (4.3) version. In this case, the version numbers don’t correspond to release dates.

    Example

    • MongoDB released Ops Manager 4.3.5 on 16 Jan 2020, but released Ops Manager 4.2.8 on 06 Feb 2020. You can’t upgrade Ops Manager from 4.2.8 to 4.3.5.
    • MongoDB released Ops Manager 4.3.7 on 27 Feb 2020. You can upgrade Ops Manager from 4.2.8 to 4.3.7.

    To find the release dates, download the ops_manager_release_archive JSON file. Search for version to find the Ops Manager versions to and from which you are upgrading.

    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.

    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.2 installation with more than one Ops Manager host pointing to the same Application Database, you can upgrade Ops Manager to a newer 4.2 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.

    Upgrade Mode works with Ops Manager 4.2 and later only.

    You should not upgrade more than one Ops Manager host at a time.

    You need to stop all Backup Daemons before upgrading to later versions of 4.2.x. To stop your Backup Daemons:

    1. Log into the first host that serves a Backup Daemon.
    2. Click the Start button.
    3. Click Administrative Tools.
    4. Click Services.
    5. Right-click the MongoDB Ops Manager Backup Daemon Service and select Stop.
    6. Repeat steps 2 to 5 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:

      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 running Microsoft Windows:

    1

    Stop your first running Ops Manager instance.

    To shutdown Ops Manager:

    1. Click the Start button.
    2. Click Administrative Tools.
    3. Click Services.
    4. Right-click the MongoDB Ops Manager HTTP Service and select Stop.
    2

    Uninstall the current version of Ops Manager.

    To uninstall Ops Manager:

    1. Click the Start button.
    2. Click Control Panel.
    3. Click Programs and Features.
    4. 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.

    3

    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 Microsoft Windows Server 2008 R2, 2012, 2012 R2 + 2016.

    3. From the Packages drop-down menu, click MSI.

    4. Click Download.

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

    4

    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.2 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:

    1. Double click the MSI package.
    2. Follow the instructions in the Setup Wizard.
    3. 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.

    5

    Start Ops Manager on the upgraded host.

    To start the service:

    1. Click the Start button.
    2. Click Administrative Tools.
    3. Click Services.
    4. In the Services list, right-click the MongoDB Ops Manager HTTP Service and select Start.
    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.

    Use this procedure to upgrade the Ops Manager Application on hosts installed using deb packages:

    1

    Stop your first running Ops Manager instance.

    Issue the following command to stop the Ops Manager Application:

    sudo service 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:

      • Ubuntu 16.04 + 18.04
      • Ubuntu 16.04 (ppc64le)
    3. From the Packages drop-down menu, click DEB for x86_64 architecture or DEB (PPC64LE) for ppc64le architecture (Ubuntu 16.04 only).

    4. Click Download.

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

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

      The upgrade to Ops Manager 4.1 and 4.2 removed the -d64 flag from the JAVA_MMS_UI_OPTS parameter.

    4

    Start Ops Manager on the upgraded host.

    sudo service mongodb-mms start
    
    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.

    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 Amazon Linux 1 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 / SUSE 12 / Amazon Linux
      • Red Hat 7 (ppc64le)
    3. From the Packages drop-down menu, click RPM for x86_64 architecture or RPM (PPC64LE) for ppc64le architecture (RHEL 7 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.2 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
    

    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.

    The upgrade to Ops Manager 4.1 and 4.2 removed the -d64 flag from the JAVA_MMS_UI_OPTS parameter.

    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 Amazon Linux 1 platforms that use SysVInit, issue the following command:

    sudo /etc/init.d/mongodb-mms start
    
    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.

    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 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 / SUSE 12 / Amazon Linux
      • Red Hat 7 (ppc64le)
      • Ubuntu 14.04, 16.04 + 18.04
      • Ubuntu 16.04 (ppc64le)
    3. From the Packages drop-down menu, click TAR.GZ for x86_64 architecture or TAR.GZ (PPC64LE) for ppc64le architecture.

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

    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.

    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.