Update from the legacy Backup and Monitoring Agents
You have a project with monitored and backed up MongoDB deployments that Automation did not manage and want to update to the MongoDB Agent.
Note
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:
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
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 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.
Run the MongoDB Agent Windows Installer.
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.If a security warning appears, click Run.
At the Configuration/Log Folder step, enter the directory where the
MSI
files are saved.At the Key Type step, select Agent API Key to bind to a specific project.
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
At the MongoDB Paths step, specify the Log and Backup directories.
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.
(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.
(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.
Click Install.
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 Prompt 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, 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
MongoDB Agent configuration file. |
LOGFILE | Optional | Absolute file path to which Ops Manager should write the
MongoDB Agent log |
MMSCONFIGBACKUP | Optional | Absolute file path to the Ops Manager automation
configuration backup JSON file. |
Example
To install the MongoDB Agent unattended,
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\MongoDB\mms-cluster-config-backup.json"
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.
(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
Click Deployment, then Agents, and then Downloads & Settings.
Below the Download Directory heading, click to the right of the path shown in Download Directory (Windows).
Change the path to the new path you want.
Click Save.
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
Open the MongoDB Agent configuration file in your preferred text editor.
Change the
mmsConfigBackup
setting to the new path for the configuration backup file. ReplaceX
in the following example with the drive letter on which your backup is stored.mmsConfigBackup=X:\<newPath>\mms-cluster-config-backup.json Save the MongoDB Agent configuration file.
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>
Use this procedure to update to the MongoDB Agent:
On x86_64 architecture running Debian 9, Ubuntu 18.04, Ubuntu 20.04, or Ubuntu 22.04:
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
Download the latest version of the MongoDB Agent.
Starting with this step, follow the MongoDB Agent installation modal and copy the commands provided into the Linux shell.
From a system shell on the host that will run the MongoDB Agent,
issue the following curl
command to download the installer for Ubuntu 18.04/20.04/22.04 or Debian 9/10/11 for 64-bit x86:
curl -OL https://<OpsManagerHost>:<Port>/download/agent/automation/mongodb-mms-automation-agent-manager-latest.amd64.ubuntu1604.deb
Note
Replace <OpsManagerHost>:<Port>
with the hostname and port of
your Ops Manager Application. If present, replace <version>
with the
major version of the operating system. For example, replace
<version>
with 7
for RHEL 7.x.
Edit the MongoDB Agent configuration file.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor:
sudo vi /etc/mongodb-mms/automation-agent.config
Update the following configuration options:
Key | Value |
---|---|
ProjectID of your project. | |
Agent API key of your project. | |
URL (hostname and port) of the Ops Manager Application. |
The resulting changes to the automation-agent.config file should look like the following:
mmsGroupId=<Project ID> mmsApiKey=<agent API key> mmsBaseUrl=<application URL>
Optional: Configure the MongoDB Agent to use a proxy server.
To configure the MongoDB Agent to connect to Ops Manager via a proxy
server, you must specify the server in the httpProxy
environment variable.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor.
sudo vi /etc/mongodb-mms/automation-agent.config
Add the following configuration key:
Key | Value |
---|---|
URL (hostname and port) of to your proxy server. |
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.
To create a data directory and set the owner as the mongodb
user:
sudo mkdir -p /data; sudo chown mongodb:mongodb /data
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.
On zSeries architecture running Ubuntu 18.04 using a
deb
package:
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
Download the latest version of the MongoDB Agent.
Starting with this step, follow the MongoDB Agent installation modal and copy the commands provided into the Linux shell.
From a system shell on the host that will run the MongoDB Agent,
issue the following curl
command to download the installer for Ubuntu 18.04 for IBM zSeries:
curl -OL https://<OpsManagerHost>:<Port>/download/agent/automation/mongodb-mms-automation-agent-manager-latest.s390x.ubuntu1804.deb
Note
Replace <OpsManagerHost>:<Port>
with the hostname and port of
your Ops Manager Application. If present, replace <version>
with the
major version of the operating system. For example, replace
<version>
with 7
for RHEL 7.x.
Edit the MongoDB Agent configuration file.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor:
sudo vi /etc/mongodb-mms/automation-agent.config
Update the following configuration options:
Key | Value |
---|---|
ProjectID of your project. | |
Agent API key of your project. | |
URL (hostname and port) of the Ops Manager Application. |
The resulting changes to the automation-agent.config file should look like the following:
mmsGroupId=<Project ID> mmsApiKey=<agent API key> mmsBaseUrl=<application URL>
Optional: Configure the MongoDB Agent to use a proxy server.
To configure the MongoDB Agent to connect to Ops Manager via a proxy
server, you must specify the server in the httpProxy
environment variable.
In the directory where you installed the MongoDB Agent, open the local.config file in your preferred text editor.
vi <install-path>/local.config
Add the following configuration key:
Key | Value |
---|---|
URL (hostname and port) of to your proxy server. |
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.
To create a data directory and set the owner as the mongodb
user:
sudo mkdir -p /data; sudo chown mongodb:mongodb /data
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.
Use this procedure to update to the MongoDB Agent:
On x86_64 architecture:
Running RHEL / CentOS 6.x using an rpm
package:
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
Download the latest version of the MongoDB Agent.
Starting with this step, follow the MongoDB Agent installation modal and copy the commands provided into the Linux shell.
From a system shell on the host that will run the MongoDB Agent,
issue the following curl
command to download the installer for RHEL 6 for 64-bit x86:
curl -OL https://<OpsManagerHost>:<Port>/download/agent/automation/mongodb-mms-automation-agent-manager-latest.x86_64.rpm
Note
Replace <OpsManagerHost>:<Port>
with the hostname and port of
your Ops Manager Application. If present, replace <version>
with the
major version of the operating system. For example, replace
<version>
with 7
for RHEL 7.x.
Edit the MongoDB Agent configuration file.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor:
sudo vi /etc/mongodb-mms/automation-agent.config
Update the following configuration options:
Key | Value |
---|---|
ProjectID of your project. | |
Agent API key of your project. | |
URL (hostname and port) of the Ops Manager Application. |
The resulting changes to the automation-agent.config file should look like the following:
mmsGroupId=<Project ID> mmsApiKey=<agent API key> mmsBaseUrl=<application URL>
Optional: Configure the MongoDB Agent to use a proxy server.
To configure the MongoDB Agent to connect to Ops Manager via a proxy
server, you must specify the server in the httpProxy
environment variable.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor.
sudo vi /etc/mongodb-mms/automation-agent.config
Add the following configuration key:
Key | Value |
---|---|
URL (hostname and port) of to your proxy server. |
Prepare the data directory.
The data directory stores MongoDB data and must be owned by the
mongod
user. For an existing MongoDB deployment, ensure the
directory has the mongod
user as owner. If no MongoDB deployment
exists, create the directory and set the owner.
The following commands create a data directory and set the owner as
the mongod
user:
sudo mkdir /data; sudo chown mongod:mongod /data
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.
Running RHEL (7.x, 8.x, or 9.x) or CentOS (7.x or 8.x), SUSE12, SUSE15, or Amazon Linux 2:
Using an rpm
package:
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
Download the latest version of the MongoDB Agent.
Starting with this step, follow the MongoDB Agent installation modal and copy the commands provided into the Linux shell.
From a system shell on the host that will run the MongoDB Agent,
issue the following curl
command to download the installer for RHEL 7 for 64-bit x86:
curl -OL https://<OpsManagerHost>:<Port>/download/agent/automation/mongodb-mms-automation-agent-manager-latest.x86_64.rhel<version>.rpm
Note
Replace <OpsManagerHost>:<Port>
with the hostname and port of
your Ops Manager Application. If present, replace <version>
with the
major version of the operating system. For example, replace
<version>
with 7
for RHEL 7.x.
Edit the MongoDB Agent configuration file.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor:
sudo vi /etc/mongodb-mms/automation-agent.config
Update the following configuration options:
Key | Value |
---|---|
ProjectID of your project. | |
Agent API key of your project. | |
URL (hostname and port) of the Ops Manager Application. |
The resulting changes to the automation-agent.config file should look like the following:
mmsGroupId=<Project ID> mmsApiKey=<agent API key> mmsBaseUrl=<application URL>
Optional: Configure the MongoDB Agent to use a proxy server.
To configure the MongoDB Agent to connect to Ops Manager via a proxy
server, you must specify the server in the httpProxy
environment variable.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor.
sudo vi /etc/mongodb-mms/automation-agent.config
Add the following configuration key:
Key | Value |
---|---|
URL (hostname and port) of to your proxy server. |
Prepare the data directory.
The data directory stores MongoDB data and must be owned by the
mongod
user. For an existing MongoDB deployment, ensure the
directory has the mongod
user as owner. If no MongoDB deployment
exists, create the directory and set the owner.
The following commands create a data directory and set the owner as
the mongod
user:
sudo mkdir /data; sudo chown mongod:mongod /data
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.
Using a tar
archive:
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
Download the latest version of the MongoDB Agent.
Starting with this step, follow the MongoDB Agent installation modal and copy the commands provided into the Linux shell.
From a system shell on the host that will run the MongoDB Agent,
issue the following curl
command to download the installer for RHEL for 64-bit x86:
curl -OL https://<OpsManagerHost>:<Port>/download/agent/automation/mongodb-mms-automation-agent-manager-latest.rhel7_x86_64.tar.gz
Note
Replace <OpsManagerHost>:<Port>
with the hostname and port of
your Ops Manager Application. If present, replace <version>
with the
major version of the operating system. For example, replace
<version>
with 7
for RHEL 7.x.
Edit the MongoDB Agent configuration file.
In the directory where you installed the MongoDB Agent, open the local.config file in your preferred text editor:
vi <install-path>/local.config
Update the following configuration options:
Key | Value |
---|---|
ProjectID of your project. | |
Agent API key of your project. | |
URL (hostname and port) of the Ops Manager Application. |
The resulting changes to the local.config file should look like the following:
mmsGroupId=<Project ID> mmsApiKey=<agent API key> mmsBaseUrl=<application URL>
Optional: Configure the MongoDB Agent to use a proxy server.
To configure the MongoDB Agent to connect to Ops Manager via a proxy
server, you must specify the server in the httpProxy
environment variable.
In the directory where you installed the MongoDB Agent, open the local.config file in your preferred text editor.
vi <install-path>/local.config
Add the following configuration key:
Key | Value |
---|---|
URL (hostname and port) of to your proxy server. |
Optional: Create the binary, log, and data directories.
If you have existing Monitoring Agent and/or Backup Agent users and do not plan on activating Automation, you only need to create the log directory.
Create the following directories to store files that the MongoDB Agent needs.
Note
The use of mongodb-mms-automation
in the file path is a
legacy artifact and does not mean that the MongoDB Agent is being
installed with Automation configured.
Component | Default Directory | Description |
---|---|---|
Binaries | /var/lib/mongodb-mms-automation | These are the binaries that the MongoDB Agent manages.
They include the MongoDB Agent, BI Connector, and MongoDB
binaries. |
MongoDB Agent logs | /var/log/mongodb-mms-automation | These are the log files that the MongoDB Agent creates. |
MongoDB databases | /data | These are the databases that the MongoDB Agent creates and
manages. |
Run the following commands to create the directories:
sudo mkdir -m 755 -p /var/lib/mongodb-mms-automation sudo mkdir -m 755 -p /var/log/mongodb-mms-automation sudo mkdir -m 755 -p /data
By default, the Agent binaries and Ops Manager
configuration backup file are located in
/var/lib/mongodb-mms-automation
.
If you want to store these files in a different
directory, follow these procedures:
To change the location of the Agent Binaries:
Click Deployment, then Agents, and then Downloads & Settings.
Below the Download Directory heading, click the pencil icon to the right of the path shown in Download Directory (Linux).
Change the path to the new path you want.
Click Save.
Create the new directory you specified on each host that runs an Agent.
sudo mkdir -m 755 -p /<newPath>
To change the location of the Agent configuration backup:
Open the Agent configuration file in your preferred text editor.
Change the
mmsConfigBackup
setting to the new path for the configuration backup file.mmsConfigBackup=/<newPath>/mms-cluster-config-backup.json Save the Agent configuration file.
Move the configuration backup file to the new directory.
sudo mv /var/lib/mongodb-mms-automation/mms-cluster-config-backup.json /<newPath>
Assign permissions to the system user that runs the MongoDB Agent.
Run the following commands:
Create mongodb user and group if they do not exist if ! sudo /usr/bin/id -g mongodb &>/dev/null; then sudo /usr/sbin/groupadd -r mongodb fi Create mongodb user if they do not exist and assign them to the mongodb group if ! sudo /usr/bin/id mongodb &>/dev/null; then sudo /usr/sbin/useradd -M -r -g mongodb \ -d /var/lib/mongo -s /bin/false \ -c mongodb mongodb > /dev/null 2>&1 fi Grant the mongodb:mongodb user and group permissions to manage deployments. sudo chown mongodb:mongodb /var/lib/mongodb-mms-automation sudo chown mongodb:mongodb /var/log/mongodb-mms-automation sudo chown mongodb:mongodb /data
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.
On RHEL / CentOS (7.x) on PowerPC architecture (managing MongoDB 3.4 or later deployments):
Using an rpm
package:
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
Download the latest version of the MongoDB Agent.
Starting with this step, follow the MongoDB Agent installation modal and copy the commands provided into the Linux shell.
From a system shell on the host that will run the MongoDB Agent,
issue the following curl
command to download the installer for RHEL 7 for PowerPC:
curl -OL https://<OpsManagerHost>:<Port>/download/agent/automation/mongodb-mms-automation-agent-manager-latest.ppc641e.rhel<version>.rpm
Note
Replace <OpsManagerHost>:<Port>
with the hostname and port of
your Ops Manager Application. If present, replace <version>
with the
major version of the operating system. For example, replace
<version>
with 7
for RHEL 7.x.
Edit the MongoDB Agent configuration file.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor:
sudo vi /etc/mongodb-mms/automation-agent.config
Update the following configuration options:
Key | Value |
---|---|
ProjectID of your project. | |
Agent API key of your project. | |
URL (hostname and port) of the Ops Manager Application. |
The resulting changes to the automation-agent.config file should look like the following:
mmsGroupId=<Project ID> mmsApiKey=<agent API key> mmsBaseUrl=<application URL>
Optional: Configure the MongoDB Agent to use a proxy server.
To configure the MongoDB Agent to connect to Ops Manager via a proxy
server, you must specify the server in the httpProxy
environment variable.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor.
sudo vi /etc/mongodb-mms/automation-agent.config
Add the following configuration key:
Key | Value |
---|---|
URL (hostname and port) of to your proxy server. |
Prepare the data directory.
The data directory stores MongoDB data and must be owned by the
mongod
user. For an existing MongoDB deployment, ensure the
directory has the mongod
user as owner. If no MongoDB deployment
exists, create the directory and set the owner.
The following commands create a data directory and set the owner as
the mongod
user:
sudo mkdir /data; sudo chown mongod:mongod /data
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.
Using a tar
archive:
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
Download the latest version of the MongoDB Agent.
Starting with this step, follow the MongoDB Agent installation modal and copy the commands provided into the Linux shell.
From a system shell on the host that will run the MongoDB Agent,
issue the following curl
command to download the installer for RHEL 7 for PowerPC:
curl -OL https://<OpsManagerHost>:<Port>/download/agent/automation/mongodb-mms-automation-agent-manager-latest.rhel7_ppc64le.tar.gz
Note
Replace <OpsManagerHost>:<Port>
with the hostname and port of
your Ops Manager Application. If present, replace <version>
with the
major version of the operating system. For example, replace
<version>
with 7
for RHEL 7.x.
Edit the MongoDB Agent configuration file.
In the directory where you installed the MongoDB Agent, open the local.config file in your preferred text editor:
vi <install-path>/local.config
Update the following configuration options:
Key | Value |
---|---|
ProjectID of your project. | |
Agent API key of your project. | |
URL (hostname and port) of the Ops Manager Application. |
The resulting changes to the local.config file should look like the following:
mmsGroupId=<Project ID> mmsApiKey=<agent API key> mmsBaseUrl=<application URL>
Optional: Configure the MongoDB Agent to use a proxy server.
To configure the MongoDB Agent to connect to Ops Manager via a proxy
server, you must specify the server in the httpProxy
environment variable.
In the directory where you installed the MongoDB Agent, open the local.config file in your preferred text editor.
vi <install-path>/local.config
Add the following configuration key:
Key | Value |
---|---|
URL (hostname and port) of to your proxy server. |
Optional: Create the binary, log, and data directories.
If you have existing Monitoring Agent and/or Backup Agent users and do not plan on activating Automation, you only need to create the log directory.
Create the following directories to store files that the MongoDB Agent needs.
Note
The use of mongodb-mms-automation
in the file path is a
legacy artifact and does not mean that the MongoDB Agent is being
installed with Automation configured.
Component | Default Directory | Description |
---|---|---|
Binaries | /var/lib/mongodb-mms-automation | These are the binaries that the MongoDB Agent manages.
They include the MongoDB Agent, BI Connector, and MongoDB
binaries. |
MongoDB Agent logs | /var/log/mongodb-mms-automation | These are the log files that the MongoDB Agent creates. |
MongoDB databases | /data | These are the databases that the MongoDB Agent creates and
manages. |
Run the following commands to create the directories:
sudo mkdir -m 755 -p /var/lib/mongodb-mms-automation sudo mkdir -m 755 -p /var/log/mongodb-mms-automation sudo mkdir -m 755 -p /data
By default, the Agent binaries and Ops Manager
configuration backup file are located in
/var/lib/mongodb-mms-automation
.
If you want to store these files in a different
directory, follow these procedures:
To change the location of the Agent Binaries:
Click Deployment, then Agents, and then Downloads & Settings.
Below the Download Directory heading, click the pencil icon to the right of the path shown in Download Directory (Linux).
Change the path to the new path you want.
Click Save.
Create the new directory you specified on each host that runs an Agent.
sudo mkdir -m 755 -p /<newPath>
To change the location of the Agent configuration backup:
Open the Agent configuration file in your preferred text editor.
Change the
mmsConfigBackup
setting to the new path for the configuration backup file.mmsConfigBackup=/<newPath>/mms-cluster-config-backup.json Save the Agent configuration file.
Move the configuration backup file to the new directory.
sudo mv /var/lib/mongodb-mms-automation/mms-cluster-config-backup.json /<newPath>
Assign permissions to the system user that runs the MongoDB Agent.
Run the following commands:
Create mongodb user and group if they do not exist if ! sudo /usr/bin/id -g mongodb &>/dev/null; then sudo /usr/sbin/groupadd -r mongodb fi Create mongodb user if they do not exist and assign them to the mongodb group if ! sudo /usr/bin/id mongodb &>/dev/null; then sudo /usr/sbin/useradd -M -r -g mongodb \ -d /var/lib/mongo -s /bin/false \ -c mongodb mongodb > /dev/null 2>&1 fi Grant the mongodb:mongodb user and group permissions to manage deployments. sudo chown mongodb:mongodb /var/lib/mongodb-mms-automation sudo chown mongodb:mongodb /var/log/mongodb-mms-automation sudo chown mongodb:mongodb /data
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.
On zSeries architecture (managing MongoDB 3.4 or later deployments):
Running RHEL (7.x, 8.x, or 9.x) or CentOS (7.x or 8.x)
using the rpm
package manager:
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
Download the latest version of the MongoDB Agent.
Starting with this step, follow the MongoDB Agent installation modal and copy the commands provided into the Linux shell.
From a system shell on the host that will run the MongoDB Agent,
issue the following curl
command to download the installer for RHEL 7.X/8.X for IBM zSeries:
curl -OL https://<OpsManagerHost>:<Port>/download/agent/automation/mongodb-mms-automation-agent-manager-latest.s390x.rhel<version>.rpm
Note
Replace <OpsManagerHost>:<Port>
with the hostname and port of
your Ops Manager Application. If present, replace <version>
with the
major version of the operating system. For example, replace
<version>
with 7
for RHEL 7.x.
Edit the MongoDB Agent configuration file.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor:
sudo vi /etc/mongodb-mms/automation-agent.config
Update the following configuration options:
Key | Value |
---|---|
ProjectID of your project. | |
Agent API key of your project. | |
URL (hostname and port) of the Ops Manager Application. |
The resulting changes to the automation-agent.config file should look like the following:
mmsGroupId=<Project ID> mmsApiKey=<agent API key> mmsBaseUrl=<application URL>
Optional: Configure the MongoDB Agent to use a proxy server.
To configure the MongoDB Agent to connect to Ops Manager via a proxy
server, you must specify the server in the httpProxy
environment variable.
In the directory where you installed the MongoDB Agent, open the automation-agent.config file in your preferred text editor.
sudo vi /etc/mongodb-mms/automation-agent.config
Add the following configuration key:
Key | Value |
---|---|
URL (hostname and port) of to your proxy server. |
Prepare the data directory.
The data directory stores MongoDB data and must be owned by the
mongod
user. For an existing MongoDB deployment, ensure the
directory has the mongod
user as owner. If no MongoDB deployment
exists, create the directory and set the owner.
The following commands create a data directory and set the owner as
the mongod
user:
sudo mkdir /data; sudo chown mongod:mongod /data
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.
Use this procedure to install update to the MongoDB Agent on
Linux systems that do not use deb
or rpm
packages.
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.
Important
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:
Create a new Kerberos User Principal and database user for the MongoDB Agent.
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:
Under the Backup Configurations section:
Type the desired setting in the Setting box and its corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Under the Monitoring Configurations section:
Type the desired setting in the Setting box and the corresponding value in the Value box.
To add more than one Setting, click the + Add Setting link. Another row appears.
Repeat until all settings have been added.
Once you have added all the settings necessary for your deployment, click Next.
You can click the 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.
Download the latest version of the MongoDB Agent.
Starting with this step, follow the MongoDB Agent installation modal and copy the commands provided into the Linux shell.
From a system shell on the host that will run the MongoDB Agent,
issue the following curl
command to download the installer for Generic 64-bit Linux:
curl -OL https://<OpsManagerHost>:<Port>/download/agent/automation/mongodb-mms-automation-agent-manager-latest.linux_x86_64.tar.gz
Note
Replace <OpsManagerHost>:<Port>
with the hostname and port of
your Ops Manager Application. If present, replace <version>
with the
major version of the operating system. For example, replace
<version>
with 7
for RHEL 7.x.
Edit the MongoDB Agent configuration file.
In the directory where you installed the MongoDB Agent, open the local.config file in your preferred text editor:
vi <install-path>/local.config
Update the following configuration options:
Key | Value |
---|---|
ProjectID of your project. | |
Agent API key of your project. | |
URL (hostname and port) of the Ops Manager Application. |
The resulting changes to the local.config file should look like the following:
mmsGroupId=<Project ID> mmsApiKey=<agent API key> mmsBaseUrl=<application URL>
Optional: Configure the MongoDB Agent to use a proxy server.
To configure the MongoDB Agent to connect to Ops Manager via a proxy
server, you must specify the server in the httpProxy
environment variable.
In the directory where you installed the MongoDB Agent, open the local.config file in your preferred text editor.
vi <install-path>/local.config
Add the following configuration key:
Key | Value |
---|---|
URL (hostname and port) of to your proxy server. |
Optional: Create the binary, log, and data directories.
If you have existing Monitoring Agent and/or Backup Agent users and do not plan on activating Automation, you only need to create the log directory.
Create the following directories to store files that the MongoDB Agent needs.
Note
The use of mongodb-mms-automation
in the file path is a
legacy artifact and does not mean that the MongoDB Agent is being
installed with Automation configured.
Component | Default Directory | Description |
---|---|---|
Binaries | /var/lib/mongodb-mms-automation | These are the binaries that the MongoDB Agent manages.
They include the MongoDB Agent, BI Connector, and MongoDB
binaries. |
MongoDB Agent logs | /var/log/mongodb-mms-automation | These are the log files that the MongoDB Agent creates. |
MongoDB databases | /data | These are the databases that the MongoDB Agent creates and
manages. |
Run the following commands to create the directories:
sudo mkdir -m 755 -p /var/lib/mongodb-mms-automation sudo mkdir -m 755 -p /var/log/mongodb-mms-automation sudo mkdir -m 755 -p /data
By default, the Agent binaries and Ops Manager
configuration backup file are located in
/var/lib/mongodb-mms-automation
.
If you want to store these files in a different
directory, follow these procedures:
To change the location of the Agent Binaries:
Click Deployment, then Agents, and then Downloads & Settings.
Below the Download Directory heading, click the pencil icon to the right of the path shown in Download Directory (Linux).
Change the path to the new path you want.
Click Save.
Create the new directory you specified on each host that runs an Agent.
sudo mkdir -m 755 -p /<newPath>
To change the location of the Agent configuration backup:
Open the Agent configuration file in your preferred text editor.
Change the
mmsConfigBackup
setting to the new path for the configuration backup file.mmsConfigBackup=/<newPath>/mms-cluster-config-backup.json Save the Agent configuration file.
Move the configuration backup file to the new directory.
sudo mv /var/lib/mongodb-mms-automation/mms-cluster-config-backup.json /<newPath>
Assign permissions to the system user that runs the MongoDB Agent.
Run the following commands:
Create mongodb user and group if they do not exist if ! sudo /usr/bin/id -g mongodb &>/dev/null; then sudo /usr/sbin/groupadd -r mongodb fi Create mongodb user if they do not exist and assign them to the mongodb group if ! sudo /usr/bin/id mongodb &>/dev/null; then sudo /usr/sbin/useradd -M -r -g mongodb \ -d /var/lib/mongo -s /bin/false \ -c mongodb mongodb > /dev/null 2>&1 fi Grant the mongodb:mongodb user and group permissions to manage deployments. sudo chown mongodb:mongodb /var/lib/mongodb-mms-automation sudo chown mongodb:mongodb /var/log/mongodb-mms-automation sudo chown mongodb:mongodb /data
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.
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 Servers.
If you want to activate Automation, add a deployment to your MongoDB project.