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.

Upgrade Ops Manager from a tar.gz or zip Archive

This tutorial describes how to upgrade an existing Ops Manager installation using a tar.gz or zip file.

Upgrade Path

The version of your existing Ops Manager installation determines the upgrade path you must take to upgrade to Ops Manager 4.0 or later.


  • 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.
  • In 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.0.x Use this tutorial to upgrade from Ops Manager 4.0.x to a more recent 4.0.x version.
3.6.x Use this 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.


It is crucial that you back up the existing and gen.key files because the upgrade process will delete existing data.


Upgrading to Ops Manager 4.0

Before upgrading Ops Manager from 3.6 to 4.0, complete the following actions:

  • Upgrade all backing databases to MongoDB 3.4 or later.


Hardware and Software Requirements

Your servers must meet the Ops Manager System Requirements.


Failure to configure servers according to the Ops Manager System Requirements, including the requirement to read the MongoDB Production Notes, can lead to production failure.

Administrator Privileges

You must have administrator privileges on the servers on which you perform the upgrade.



Before you perform the upgrade procedure, ensure that you have a current backup of the Ops Manager backing databases. To perform a full backup, see Shut Down and Back Up Ops Manager.


Stop all existing Ops Manager services.

Shut down the Ops Manager Application.

<install_dir>/bin/mongodb-mms stop

On each Ops Manager server, back up your existing configuration files and logs to a directory other than the install directory.


You need the backed-up <install_dir>/conf/ file for later in this procedure.


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

Download the latest version of the Ops Manager archive.

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

    If you start on 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.


Install the Ops Manager package on each server being used for Ops Manager.

Navigate to the directory to which to install Ops Manager. Extract the archive to that directory:

tar -zxf mongodb-mms-<version>.x86_64.tar.gz

On each Ops Manager server, 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:
The settings for this Ops Manager deployment.
The encryption key for the backing databases of this Ops Manager deployment.


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/ <install_dir>/conf/
cp -a ~/mms_conf.backup/gen.key <install_dir>/conf/gen.key

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.


Start Ops Manager on every server.

Issue the following command:

<install_dir>/bin/mongodb-mms start

Update all Agents.

Once your upgrade has finished and you log into 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.