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 with deb Packages

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.

Use this procedures to install the Automation Agent on Ubuntu with deb packages. For Debian systems, use the Install or Upgrade the Automation Agent from an Archive procedure.

To install the Automation Agent to a server without using a deb package, use the Install or Upgrade the Automation Agent from an Archive procedure.

Prerequisites

64-Bit Architecture

The Automation Agent can run only on a 64-bit architecture.

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 the shell:

    hostname -f
    
  • Resolve each FQDN to a unique IP address. Run the following command in the shell 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.

Root Access

To install the Automation Agent using a deb package, you must have root access.

Procedures

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

Install the Automation Agent with a deb Package

Installation Tip for Binding the Agent to a Project

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 Ubuntu<version> - DEB.
3

Download the latest version of the Automation Agent archive.

On a system shell, issue a curl command to download the deb for the agent that works on your platform:

Note

Replace <OpsManagerHost:Port> with the hostname and port of your Ops Manager installation.

For Ubuntu 15.04+ or 16.04+ on x64 architecture:

curl -OL https://<OpsManagerHost:Port>/download/agent/automation/mongodb-mms-automation-agent-manager_latest_amd64.ubuntu1604.deb

For Ubuntu 16.X on PowerPC architecture (managing MongoDB 3.4 or later deployments only):

curl -OL https://<OpsManagerHost:Port>/download/agent/automation/mongodb-mms-automation-agent-manager_latest_ppc64e1.ubuntu1604.deb

For Ubuntu 14.04+ on x64 architecture:

curl -OL https://<OpsManagerHost:Port>/download/agent/automation/mongodb-mms-automation-agent-manager_latest_amd64.deb
4

Install the Automation Agent Package.

To install the agent that works on your platform, issue the appropriate command to install the package:

For Ubuntu 15.04+ or 16.04+ on x64 architecture:

sudo dpkg -i mongodb-mms-automation-agent-manager_latest_amd64.ubuntu1604.deb

For Ubuntu 16.X on PowerPC architecture (managing MongoDB 3.4 or later deployments only):

sudo dpkg -i mongodb-mms-automation-agent-manager_latest_ppc64e1.ubuntu1604.deb

For Ubuntu 14.04+ on x64 architecture:

sudo dpkg -i mongodb-mms-automation-agent-manager_latest_amd64.deb
5

Generate an agent API key or retrieve an existing agent API key for your Ops Manager project.

  1. Click + Generate Key.

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.

  1. Enter your password and click Verify.
  2. Click + Generate Key again.

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.

6

Edit the automation-agent.config file.

In the directory where you installed the Automation Agent, edit the automation-agent.config file to either:

Open the file with an editor. For example:

sudo vi /etc/mongodb-mms/automation-agent.config

In the directory where you installed the Automation Agent, open the local.config file in your preferred text editor.

The changes you make depend whether or not you are using server pools.

Update the following configuration keys:

Key Change
mmsGroupId Set to your ProjectID.
mmsApiKey Set to the project’s agent API key.
mmsBaseUrl Set to the URL of the Ops Manager Application. Include the port number.

The resulting changes to the local.config file should look like the following:

mmsGroupId=<Project ID>
mmsApiKey=<agent API key>
mmsBaseUrl=<application URL>

Important

Do not configure the Server Pool settings:

Server Pools deprecated as of Ops Manager 4.0

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

Update the following configuration keys:

Key Change
mmsBaseUrl Set to the URL of the Ops Manager Application. Include the port number.
serverPoolKey

Set to the 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.

serverPoolPropertiesFile

Set to the full filepath of a file that contains server properties. Ensure the Automation Agent can read the file.

The properties file contains key/value pairs of the form <property>=<value>. The Ops Manager Administrator decides on both the property names and values.

Note

Ensure that the properties file contains the desired property names and values before starting the Automation Agent on the server.

Once the server is registered with the pool, changes to the properties file do not take effect until the server is first removed and the Automation Agent restarted.

serverPoolStateFile

Set to the full filepath of the file to be used by the Automation Agent.

Ensure that the directory path to the file exists and the agent has read and write access to the directory. The file itself need not exist; however, if it does exist, the agent must have read and write access to the file.

The resulting changes to the local.config file should look like the following:

mmsBaseUrl=<application URL>
serverPoolKey=somekeyabc123
serverPoolPropertiesFile=<path to server properties file>
serverPoolStateFile=<path to server state file>

Important

Do not configure the Project settings:

7

Optional: Configure the Automation Agent to use a proxy server.

To configure the agent to connect to Ops Manager via a proxy server, you must specify the server in the httpProxy environment variable. In the /etc/mongodb-mms/automation-agent.config file, set the httpProxy value to the URL of to your proxy server:

httpProxy="http://proxy.example.com:9000"
8

Prepare the data directory.

The data directory stores MongoDB data. For an existing MongoDB deployment, ensure that the directory is owned by the mongodb user. If no MongoDB deployment exists, create the directory and set the owner.

sudo mkdir /data
sudo chown mongodb:mongodb /data
9

Start the Automation Agent.

Issue the following command:

For Ubuntu 15.X or later:

sudo systemctl start mongodb-mms-automation-agent.service

For Ubuntu 14.04+:

sudo start mongodb-mms-automation-agent
10

Verify that the Automation Agent can connect to Ops Manager.

Click Verify Agent on the Automation Agent Installation Instructions modal.

Update the Automation Agent with a deb Package

Important

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

If you use this procedure, you do not need to stop the agent. The update package automatically stops, unpacks, and then restarts the agent.

1

Log in to the host where the Automation Agent is installed.

2

Stop any currently running Automation Agents.

Issue the following command on the MongoDB host:

pkill -f mongodb-mms-automation-agent
3

Login to Ops Manager.

4

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

5

Download the latest version of the Automation Agent archive.

On a system shell, issue a curl command to download the deb for the agent that works on your platform:

Note

Replace <OpsManagerHost:Port> with the hostname and port of your Ops Manager installation.

For Ubuntu 15.04+ or 16.04+ on x64 architecture:
curl -OL https://<OpsManagerHost:Port>/download/agent/automation/mongodb-mms-automation-agent-manager_latest_amd64.ubuntu1604.deb
For Ubuntu 16.X on PowerPC architecture (managing MongoDB 3.4 or later deployments only):
curl -OL https://<OpsManagerHost:Port>/download/agent/automation/mongodb-mms-automation-agent-manager_latest_ppc64e1.ubuntu1604.deb
For Ubuntu 14.04+ on x64 architecture:
curl -OL https://<OpsManagerHost:Port>/download/agent/automation/mongodb-mms-automation-agent-manager_latest_amd64.deb
6

Install the Automation Agent Package.

To install the agent that works on your platform, issue the appropriate command to install the package:

For Ubuntu 15.04+ or 16.04+ on x64 architecture:
sudo dpkg -i mongodb-mms-automation-agent-manager_latest_amd64.ubuntu1604.deb
For Ubuntu 16.X on PowerPC architecture (managing MongoDB 3.4 or later deployments only):
sudo dpkg -i mongodb-mms-automation-agent-manager_latest_ppc64e1.ubuntu1604.deb
For Ubuntu 14.04+ on x64 architecture:
sudo dpkg -i mongodb-mms-automation-agent-manager_latest_amd64.deb
7

Prepare the data directory.

The data directory stores MongoDB data. For an existing MongoDB deployment, ensure that the directory is owned by the mongodb user. If no MongoDB deployment exists, create the directory and set the owner.

sudo mkdir /data
sudo chown mongodb:mongodb /data
8

Start the Automation Agent.

Issue the following command:

For Ubuntu 15.X or later:
sudo systemctl start mongodb-mms-automation-agent.service
For Ubuntu 14.04+:
sudo start mongodb-mms-automation-agent
9

Upgrade the Automation Agent in Ops Manager.

After you have updated the Automation Agent, Ops Manager recognizes that the updated Agent does not match the version specified in the Automation Configuration. Ops Manager displays a banner informing you that one or more agents are out of date. Click Update All Agents to make Ops Manager update the Automation Configuration and complete the upgrade.

10

Click Review & Deploy to review your changes.

Ops Manager displays your proposed changes.

  1. If you are satisfied, click Confirm & Deploy.
  2. If you want to make further configuration changes, click Cancel. Click Modify for the cluster to make additional changes.