Navigation
This version of the documentation is archived and no longer supported. It will be removed on EOL_DATE. 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. It will be removed on EOL_DATE.

Install the Automation Agent on Windows

Overview

Ops Manager Automation relies on an Automation Agent, which must be installed on every server that runs a monitored MongoDB deployment. The Automation Agents periodically poll Ops Manager to determine the goal configuration, deploy changes as needed, and report deployment status back to Ops Manager.

Automation Agents can run only on 64-bit architectures.

Prerequisites

Server Networking Access

The hosts that serve the MongoDB deployments must:

  • Have full networking access to each other through their fully qualified domain names (FQDNs). Each host must be able to reach every other host through the FQDN. To find the FQDN for each host, run the following command in Powershell:

    net config workstation | findstr /C:"Full Computer name"
    
  • Resolve each FQDN to a unique IP address.

    1. Download and install the Windows BIND tools.

    2. Run the following command to resolve the FQDN:

      dig +short myip.opendns.com @resolver1.opendns.com
      
  • Set the Common Name or Subject Alternative Name value of any SSL certificates to the MongoDB host’s FQDN.

The network configuration must allow each Automation Agent to make a direct connection to every MongoDB deployment listed on the Deployment page. Ops Manager does not support port forwarding.

Installing to a Server that Already Runs MongoDB

If you install the Automation Agent to a server that is already running a MongoDB process, the agent must have:

  • Permission to stop the MongoDB process. The Automation Agent will restart the process using the agent’s own set of MongoDB binaries. If you had installed MongoDB with a package manager, use the same package manager to install the Automation Agent. This gives the agent the same owner as MongoDB.
  • Read and Write permissions on the MongoDB data directory and log directory.
  • Permission to stop, start, and update any existing Monitoring and Backup Agents.

Installing to a Server Before Installing MongoDB

If you deploy the Automation Agent to a server that does not have MongoDB installed, ensure the user that owns the Automation Agent has Read and Write permissions on the MongoDB data and log directories you plan to use.

Important

Windows Firewall stealth mode should be disabled on the MongoDB servers on which the Automation Agent is installed for best performance.

Procedure

This section includes procedures for both installing and updating the Automation Agent.

Install the Automation Agent on Windows

You can also access install instructions in Ops Manager, including commands you can copy and paste: click Deployment, then Agents, then Downloads & Settings.

1

Login to Ops Manager.

2

Begin or Manage a Deployment

When you reach the Install an Automation Agent on each server page, all hosts are listed.

  1. Click on the Install Agent menu of the first MongoDB host.
  2. Select Windows - MSI.
3

Download the Automation Agent.

The Automation Agent Installation Instructions box displays the following information:

  • Base URL (Required for either binding to a project or adding the host to a server pool)

    Server Pools deprecated as of Ops Manager 4.0

    As of Ops Manager 4.0, server pools are deprecated and disabled by default.

  • Project ID (Required for binding to a project)

  • + Generate Key button to generate an Agent API Key (Required for binding to a project).

    Note

    The button appears only if the current user is the project owner and the project either has no Agent API keys or just the Original Group API key. An Original Group API key exists only in projects created prior to the new Agent API Key model. The new model allows a project to have more than one key and permits any of the project’s agents to use any of the keys. For more information, see Manage Agent API Keys. If you do not see the + Generate Key button and do not remember your existing agent api key, you can generate a key on the Agent API Keys tab. To navigate to the tab, select Deployment view, then click the Agents tab and then the Agent API Keys tab.

    You can use an Agent API key that you have already generated for the project. Otherwise, you can generate a new Agent API key. A project can have more than one Agent API key, and any of the project’s agents can use any of the keys. For more information, see Manage Agent API Keys.

    Important

    When you generate an Agent API key, Ops Manager displays it one time only. You must copy it and store it in a secure place. Ops Manager will never display the full key again.

Some or all of these values are required in a later step, so keep this box open.

4

Install the Automation Agent.

  1. After the MSI downloads, double-click mongodb-mms-automation-agent-<version>.windows_x86_64.msi

  2. If a security warning appears, click Run.

  3. At the Configuration/Log Folder step

    Provide the directory into which these files are saved.

  4. At the Key Type step, select:

    • Agent API Key to bind to a specific project or
    • Server Pool Key to add the host to a server pool.
  5. Enter the appropriate agent keys.

    Note

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

    If you selected Agent API Key, type the:

    • Base URL
    • Project ID
    • Agent API Key

    If you selected Server Pool Key, type the:

    • Base URL
    • Project ID
    • Server Pool Key.

    To find the server pool key, in the Admin menu, go to Server Pool view and click on the Agent Configuration tab.

  6. At the Automation Paths step, specify the Log and Backup directories

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

    If you click 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 Automation Agent, you are asked to disable it. Stealth Mode significantly degrades the performance and capability of the Automation 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 Automation Agent uses these counters for some of its hardware monitoring activities.

  10. Click Install.

  11. Click Finish once setup is complete.

After the MSI downloads, you can run an unattended install. You run an unattended install from the command line in either the command interpreter or PowerShell. To learn more about unattended installs, see Microsoft’s documentation on Standard Installer Command-Line Options

To run the MSI installer unattended from the command line, you invoke msiexec.exe with the /q and /i flags and a combination of required and optional parameters:

Parameter Necessity Value
MMSAPIKEY Required Agent API key of your Ops Manager project.
MMSBASEURL Required URL of the Ops Manager host.
MMSGROUPID Required Unique Identifier of your Ops Manager project.
CONFIGLOGDIR Optional Absolute file path to which Ops Manager should write the Automation Agent configuration file.
LOGFILE Optional Absolute file path to which Ops Manager should write the Automation Agent log
MMSCONFIGBACKUP Optional Absolute file path to the Ops Manager automation configuration backup JSON file.

Example

To install the Automation Agent unattended, you would invoke msiexec.exe with the following options:

msiexec.exe /q /i "C:\PATH\TO\mongodb-mms-automation-agent-<VERSION>.windows_x86_64.msi" MMSGROUPID=<GROUP.ID> MMSAPIKEY=<AGENT.API.ID> MMSBASEURL="<http://opsmanager.example.com:8080>" LOGFILE="C:\MMSData\Server\Log\automation-agent.log" MMSCONFIGBACKUP="C:\MMSData\Automation\mms-cluster-config-backup.json"
5

Verify the Automation Agent is running.

The Automation Agent starts automatically after installation. This step verifies that it is running and can communicate with Ops Manager.

6

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

By default, the MongoDB binaries and Ops Manager configuration backup file are located in %SystemDrive%\MMSAutomation\versions.

Note

Windows sets the %SystemDrive% environment variable to the drive on which you installed Windows. By default, you would be directed to install Windows on the C: drive. To find your %SystemDrive%, issue with 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 Automation Agent Binaries:

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

  2. Below the Download Directory heading, click the pencil 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 an Automation Agent. Use Windows Explorer to move the file or issue the following command from a Command Prompt or PowerShell:

    md \<newPath>
    

    Important

    Make sure the system user that runs the Automation 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 Automation Agent configuration backup:

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

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

    mmsConfigBackup=X:\<newPath>\mms-cluster-config-backup.json
    
  3. Save the Automation 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%\MMSAutomation\versions\mms-cluster-config-backup.json \<newPath>
    
7

Repeat installation procedure for each MongoDB host.

Update the Automation Agent on Windows

Important

If any Automation Agent for any deployment is out of date, Ops Manager displays a warning on the Deployment page.

1

Click Update All Agents.

2

Click Review & Deploy.

3

Review and approve your changes.

Otherwise, click Cancel and you can make additional changes.