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.

Update from the legacy Backup and Monitoring Agents

  • Windows
  • macOS
  • Ubuntu/Debian
  • RHEL/CentOS/SLES/AMZ
  • Linux

You have a project with monitored and backed up MongoDB deployments that Automation did not manage and want to update to the MongoDB Agent.

Review the Prerequisites First

If you want to start or continue using Automation to manage your MongoDB deployments, please review the MongoDB Agent Prerequisites before updating to the MongoDB Agent.

Procedure

Use this procedure to update to the MongoDB Agent on x86_64 architecture running Microsoft Windows:

1

Log in to the Ops Manager Application.

2

From the notification banner, click Update All Agents.

The Update to MongoDB Agent page opens to start the update process. The Introducing the MongoDB Agent step displays. When you have finished reading this step, click Next.

3

Optional: Add any existing configuration options for your legacy Agents.

If Automation did not manage your Backup or Monitoring Agents, you can add any Backup or Monitoring settings you had before at the Add Custom Configuration Options for your MongoDB Agent (Optional) step.

Deployments using Kerberos Authentication

Don’t add either of the following settings from the legacy Agents:

  • krb5Principal
  • krb5Keytab

Your legacy Agents authenticated with Kerberos as separate database users. Because the MongoDB Agent combines the functions of the legacy Agents, it employs a single database user. To upgrade to the MongoDB Agent and continue using Kerberos, you must:

  1. Create a new Kerberos User Principal and database user for the MongoDB Agent.
  2. Update the Agent authentication configuration in the Ops Manager Authentication & TLS settings with the new MongoDB Agent Principal and Keytab files.

You can remove the legacy Monitoring and Backup Agent users after updating to the MongoDB Agent.

To add options that you had for your Backup Agent and Monitoring Agent:

  1. Under the Backup Configurations section:
    1. Type the desired setting in the Setting box and its corresponding value in the Value box.
    2. To add more than one Setting, click the + Add Setting link. Another row appears.
    3. Repeat until all settings have been added.
  2. Under the Monitoring Configurations section:
    1. Type the desired setting in the Setting box and the corresponding value in the Value box.
    2. To add more than one Setting, click the + Add Setting link. Another row appears.
    3. Repeat until all settings have been added.
  3. Once you have added all the settings necessary for your deployment, click Next.

You can click the trash icon to remove any settings that you have added.

Important

Ops Manager does not validate any of these settings. Make sure that the settings and values are correct.

4

Download the MongoDB Agent.

  1. Click View Agent Install Instructions. The Install Agent Instructions modal opens.
  2. From the Select Your Server’s Operating System menu, select Windows - MSI.
  3. Click Next. The Install New MongoDB Agent modal opens.
5

Install the MongoDB Agent.

The MongoDB Agent Installation Instructions box displays the following information:

  • Base URL

    Required for binding to a project.

  • Project ID (Required for binding to a project)

  • API Key

    If you do not have an API Key, click plus icon Generate Key.

Warning

Some or all of these values are required in a later step. Copy these values then store them where you can access them later.

6

Run the MongoDB Agent Windows Installer.

  1. After the MSI downloads, double-click:

    mongodb-mms-automation-agent-<VERSION>.windows_x86_64.msi

    Note

    The use of mongodb-mms-automation in the filename is a legacy concern and does not mean that the MongoDB Agent is being installed with Automation configured.

  2. If a security warning appears, click Run.

  3. At the Configuration/Log Folder step, enter the directory where the MSI files are saved.

  4. At the Key Type step, select Agent API Key to bind to a specific project.

  5. Enter the appropriate Agent keys.

    Note

    These keys are provided in the MongoDB Agent Installation Instructions modal described in the previous step.

    If you selected Agent API Key, type the:

    • Base URL
    • Project ID
    • Agent API Key
  6. At the MongoDB Paths step, specify the Log and Backup directories.

  7. At the Windows Firewall Configuration step, select your preferred firewall configuration.

    If you select Configure firewall rules allowing access from only the specified |ipaddr| addresses., type the necessary IPv4 addresses into the provided box.

  8. (Conditional) Windows enables Stealth Mode for the Windows Firewall by default. If you have not disabled it on the MongoDB host on which you are installing the MongoDB Agent, disable it now. Stealth Mode significantly degrades the performance and capability of the MongoDB Agent. Click Disable Stealth Mode.

  9. (Conditional) Windows does not enable Disk Performance Counters by default. If you have not enabled Disk Performance Counters for the MongoDB host, click Enable Disk Performance Counters. The MongoDB Agent uses these counters for some of its hardware monitoring activities.

  10. Click Install.

  11. Click Finish once setup is complete.

7

Finish the installation of the MongoDB Agent.

In the Install Agent Instructions modal, click Done.

8

Verify that the MongoDB Agent is running.

In the Install Agent Instructions modal, wait for each deployment to show Verified in the Install the MongoDB Agent step.

Important

All authentication SCRAM, LDAP, and Kerberos credentials from legacy Agents are retained after the update. All .pem key files are retained as well.

Click Next.

9

(Optional) Change the location of the MongoDB Agent binaries and configuration backup files.

Your system policies or practices may require the MongoDB binaries and Ops Manager configuration backup file to be located somewhere other than the default location of %SystemDrive%\MMSMongoDB\versions.

Note

Windows sets the %SystemDrive% environment variable to the drive on which you installed Windows. By default, you are directed to install Windows on the C: drive. To find your %SystemDrive%, issue the following command from PowerShell:

get-childitem env:SystemDrive

If you want to store these files in a different directory, follow these procedures:

To change the location of the MongoDB Agent Binaries

  1. Click Deployment, then Agents, and then Downloads & Settings.

  2. Below the Download Directory heading, click edit icon to the right of the path shown in Download Directory (Windows).

  3. Change the path to the new path you want.

  4. Click Save.

  5. Create the new directory you specified on each host that runs a MongoDB Agent. Use Windows Explorer to move the file or issue the following command from a Command Prompt or PowerShell:

    md \<newPath>
    

    Important

    Make sure that the system user that runs the MongoDB Agent can write to this new directory. This is usually the SYSTEM user, which requires no additional configuration unless you changed the user.

To change the location of the MongoDB Agent configuration backup

  1. Open the MongoDB Agent configuration file in your preferred text editor.

  2. Change the mmsConfigBackup setting to the new path for the configuration backup file. Replace X in the following example with the drive letter on which your backup is stored.

    mmsConfigBackup=X:\<newPath>\mms-cluster-config-backup.json
    
  3. Save the MongoDB Agent configuration file.

  4. Move the configuration backup file to the new directory. Use Windows Explorer to move the file or issue the following command from a Command Prompt or PowerShell:

    move %SystemDrive%\MMSMongoDB\versions\mms-cluster-config-backup.json \<newPath>
    
10

Repeat the installation procedure for each MongoDB host.

Next Steps

After the MongoDB Agent update completes:

  • If Automation did not previously manage your Monitoring and/or Backup Agents, activate Backup and/or Monitoring on your MongoDB deployment.
  • If Automation did previously manage your Monitoring and/or Backup Agents, they are now activated. To verify that they are activated, click Deployment arrow right icon Servers.
  • If you want to activate Automation, add a deployment to your MongoDB project.
  • Stop and remove the legacy Monitoring Agent.
  • Stop and remove the legacy Backup Agent.
Was this page helpful?