• MongoDB Agent >
• Update to the MongoDB Agent >
• Update from the legacy Monitoring Agent

Update from the legacy Monitoring Agent

You have a project with monitored MongoDB deployments that Automation does 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

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

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

1

Log in to the Cloud Manager.

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

Add any existing configuration options for your legacy Monitoring Agent.

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

To add options that you had for your Monitoring Agent, 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.
4. 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

Cloud 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:

• 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.

• Interactive
• Unattended

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 artifact 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

   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.

5. Enter the appropriate Agent keys.

   Note

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

   • Type your Project ID into the Project ID field.
   • Type your Agent API Key into the Agent API Key field.

6. At the MongoDB 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 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.

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 Cloud Manager project.
MMSGROUPID	Required	Unique Identifier of your Cloud Manager project.
CONFIGLOGDIR	Optional	Absolute file path to which Cloud Manager should write the MongoDB Agent configuration file.
LOGFILE	Optional	Absolute file path to which Cloud Manager should write the MongoDB Agent log
MMSCONFIGBACKUP	Optional	Absolute file path to the Cloud Manager automation configuration backup JSON file.

Example

To install the MongoDB Agent unattended, invoke msiexec.exe with the following options:

copy

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"

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 Cloud 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 with following command from PowerShell:

copy

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 an MongoDB Agent. Use Windows Explorer to move the file or issue the following command from a Command Prompt or PowerShell:

   copy

   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.

   copy

   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:

   copy

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

10

Repeat the installation procedure for each MongoDB host.

Use this procedure to update to the MongoDB Agent on x86_64 architecture running macOS 10.8 or later:

1

Log in to the Cloud Manager.

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

Add any existing configuration options for your legacy Monitoring Agent.

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

To add options that you had for your Monitoring Agent, 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.
4. 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

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

4

Install 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 Mac OSX (10.8 and above) - TAR.
3. Click Next. The Install New MongoDB Agent modal opens.

5

Download the latest version of the MongoDB Agent.

Note

Starting with this step, follow the MongoDB Agent installation modal and copy the provided commands into the macOS Terminal.

From a system shell on the host that will run the MongoDB Agent, issue the following curl command to download the installer for macOS:

copy

curl -OL https://cloud.mongodb.com/download/agent/automation/mongodb-mms-automation-agent-manager-latest.osx_x86_64.tar.gz

6

Extract the MongoDB Agent.

You can install the MongoDB Agent in any directory. If you want to move the archive to another directory before extracting, you may do so.

To install the MongoDB Agent, extract the archive:

copy

tar -xvzf mongodb-mms-automation-agent-<VERSION>.osx_x86_64.tar.gz

7

Change to the extracted binary directory.

Change into the directory that was created after extracting the MongoDB Agent binary:

copy

cd mongodb-mms-automation-agent-<VERSION>.osx_x86_64

8

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.

copy

vi <install-path>/local.config

Update the following configuration options:

Key	Value
mmsGroupId	ProjectID of your project.
mmsApiKey	Agent API key of your project.

9

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

To configure the MongoDB Agent to connect to Cloud 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.

copy

vi <install-path>/local.config

Add the following configuration key:

Key	Value
httpProxy	URL (hostname and port) of to your proxy server.

10

Optional: Create the binary, log, and data directories.

If you have an existing Monitoring Agent user 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:

copy

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

Using a Different Path than /var/lib

By default, the Agent binaries and Cloud 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:

1. Click Deployment, then 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 (Linux/MacOS).

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 Agent.

   copy

   sudo mkdir -m 755 -p /<newPath>
   

To change the location of the Agent configuration backup:

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

2. Change the mmsConfigBackup setting to the new path for the configuration backup file.

   copy

   mmsConfigBackup=/<newPath>/mms-cluster-config-backup.json
   

3. Save the Agent configuration file.

4. Move the configuration backup file to the new directory.

   copy

   sudo mv /var/lib/mongodb-mms-automation/mms-cluster-config-backup.json /<newPath>
   

11

Assign permissions to the system user that runs the MongoDB Agent.

Run the following commands:

copy

# 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

12

Start the MongoDB Agent.

From the directory in which you installed the MongoDB Agent and as the system user you created in the last step, issue the following command:

copy

nohup ./mongodb-mms-automation-agent \
  --config=local.config \
  >> /var/log/mongodb-mms-automation/automation-agent-fatal.log 2>&1 &

13

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.

14

Finish the installation of the MongoDB Agent.

In the Install Agent Instructions modal, click Done.

15

Repeat the installation procedure for each MongoDB host.

Use this procedure to update to the MongoDB Agent:

• Intel/AMD
• PowerPC
• IBM ZSeries

On x86_64 architecture running, Debian 8, Debian 9, Ubuntu 18.04, or Ubuntu 20.04:

1

Log in to the Cloud Manager.

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

Add any existing configuration options for your legacy Monitoring Agent.

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

To add options that you had for your Monitoring Agent, 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.
4. 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

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

4

Install 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 Debian 8/9/10, Ubuntu 16.X/18.X/20.x - DEB.
3. Click Next. The Install New MongoDB Agent modal opens.

5

Download the latest version of the MongoDB Agent.

Note

Starting with this step, follow the MongoDB Agent installation modal and copy the provided commands 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 or Debian 9/10 for 64-bit x86:

copy

curl -OL https://cloud.mongodb.com/download/agent/automation/mongodb-mms-automation-agent-manager-latest.amd64.ubuntu1604.deb

6

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.

copy

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

Update the following configuration options:

Key	Value
mmsGroupId	ProjectID of your project.
mmsApiKey	Agent API key of your project.

7

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

To configure the MongoDB Agent to connect to Cloud 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.

copy

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

Add the following configuration key:

Key	Value
httpProxy	URL (hostname and port) of to your proxy server.

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.

To create a data directory and set the owner as the mongodb user:

copy

sudo mkdir -p /data; sudo chown mongodb:mongodb /data

9

Start the MongoDB Agent.

Issue the following command:

copy

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

10

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.

11

Finish the installation of the MongoDB Agent.

In the Install Agent Instructions modal, click Done.

12

Repeat the installation procedure for each MongoDB host.

On PowerPC architecture running Ubuntu 18.x (managing MongoDB 3.6 or later deployments only):

• DEB package
• TAR archive

Using a ``deb`` package: .. include:: /includes/steps/update-monitoring-to-mongodb-agent-ppc64e1.ubuntu1604-deb.rst

Using a ``tar`` archive: .. include:: /includes/steps/update-monitoring-to-mongodb-agent-ubuntu1604-ppc64le-tar.rst

On zSeries architecture running Ubuntu 18.x using a deb package:

1

Log in to the Cloud Manager.

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

Add any existing configuration options for your legacy Monitoring Agent.

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

To add options that you had for your Monitoring Agent, 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.
4. 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

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

4

Install 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 Ubuntu 18.X Z-Series (s390x) - DEB.
3. Click Next. The Install New MongoDB Agent modal opens.

5

Download the latest version of the MongoDB Agent.

Note

Starting with this step, follow the MongoDB Agent installation modal and copy the provided commands 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:

copy

curl -OL https://cloud.mongodb.com/download/agent/automation/mongodb-mms-automation-agent-manager-latest.s390x.ubuntu1804.deb

6

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.

copy

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

Update the following configuration options:

Key	Value
mmsGroupId	ProjectID of your project.
mmsApiKey	Agent API key of your project.

7

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

To configure the MongoDB Agent to connect to Cloud 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.

copy

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

Add the following configuration key:

Key	Value
httpProxy	URL (hostname and port) of to your proxy server.

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.

To create a data directory and set the owner as the mongodb user:

copy

sudo mkdir -p /data; sudo chown mongodb:mongodb /data

9

Start the MongoDB Agent.

Issue the following command:

copy

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

10

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.

11

Finish the installation of the MongoDB Agent.

In the Install Agent Instructions modal, click Done.

12

Repeat the installation procedure for each MongoDB host.

Use this procedure to update to the MongoDB Agent:

• Intel/AMD
• PowerPC
• IBM ZSeries

On x86_64 architecture:

• RHEL/CentOS 6.x, Amazon Linux
• RHEL/CentOS (7.x/8.x), SUSE12/15, Amazon Linux 2

Running RHEL / CentOS 6.x using an rpm package:

1

Log in to the Cloud Manager.

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

Add any existing configuration options for your legacy Monitoring Agent.

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

To add options that you had for your Monitoring Agent, 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.
4. 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

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

4

Install 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 Amazon Linux - RPM.
3. Click Next. The Install New MongoDB Agent modal opens.

5

Download the latest version of the MongoDB Agent.

Note

Starting with this step, follow the MongoDB Agent installation modal and copy the provided commands 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:

copy

curl -OL https://cloud.mongodb.com/download/agent/automation/mongodb-mms-automation-agent-manager-latest.x86_64.rpm

6

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.

copy

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

Update the following configuration options:

Key	Value
mmsGroupId	ProjectID of your project.
mmsApiKey	Agent API key of your project.

7

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

To configure the MongoDB Agent to connect to Cloud 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.

copy

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

Add the following configuration key:

Key	Value
httpProxy	URL (hostname and port) of to your proxy server.

8

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:

copy

sudo mkdir /data; sudo chown mongod:mongod /data

9

Start the MongoDB Agent.

Issue the following command:

copy

sudo service mongodb-mms-automation-agent start

10

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.

11

Finish the installation of the MongoDB Agent.

In the Install Agent Instructions modal, click Done.

12

Repeat the installation procedure for each MongoDB host.

Running RHEL / CentOS 7.x, SUSE12, SUSE15 or Amazon Linux 2:

• RPM package
• TAR archive

Using an ``rpm`` package: .. include:: /includes/steps/update-monitoring-to-mongodb-agent-x86-64.rhel7-rpm.rst

Using a ``tar`` archive: .. include:: /includes/steps/update-monitoring-to-mongodb-agent-rhel7-x86-64-tar.rst

On RHEL / CentOS (7.x) on PowerPC architecture (managing MongoDB 3.4 or later deployments):

• RPM package
• TAR archive

Using an ``rpm`` package: .. include:: /includes/steps/update-monitoring-to-mongodb-agent-ppc641e.rhel7-rpm.rst

Using a ``tar`` archive: .. include:: /includes/steps/update-monitoring-to-mongodb-agent-rhel7-ppc64le-tar.rst

On zSeries architecture (managing MongoDB 3.4 or later deployments):

• 6.x
• 7.x

Running RHEL / CentOS 6.x using the rpm package manager:

1

Log in to the Cloud Manager.

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

Add any existing configuration options for your legacy Monitoring Agent.

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

To add options that you had for your Monitoring Agent, 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.
4. 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

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

4

Install 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 Amazon Linux - RPM.
3. Click Next. The Install New MongoDB Agent modal opens.

5

Download the latest version of the MongoDB Agent.

Note

Starting with this step, follow the MongoDB Agent installation modal and copy the provided commands 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 IBM zSeries:

copy

curl -OL https://cloud.mongodb.com/download/agent/automation/mongodb-mms-automation-agent-manager-latest.s390x.rhel6.rpm

6

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.

copy

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

Update the following configuration options:

Key	Value
mmsGroupId	ProjectID of your project.
mmsApiKey	Agent API key of your project.

7

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

To configure the MongoDB Agent to connect to Cloud 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.

copy

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

Add the following configuration key:

Key	Value
httpProxy	URL (hostname and port) of to your proxy server.

8

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:

copy

sudo mkdir /data; sudo chown mongod:mongod /data

9

Start the MongoDB Agent.

Issue the following command:

copy

sudo service mongodb-mms-automation-agent start

10

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.

11

Finish the installation of the MongoDB Agent.

In the Install Agent Instructions modal, click Done.

12

Repeat the installation procedure for each MongoDB host.

Running RHEL / CentOS 7.x using the rpm package manager:

1

Log in to the Cloud Manager.

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

Add any existing configuration options for your legacy Monitoring Agent.

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

To add options that you had for your Monitoring Agent, 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.
4. 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

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

4

Install 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 RHEL 7.X Z-Series (s390x) - RPM.
3. Click Next. The Install New MongoDB Agent modal opens.

5

Download the latest version of the MongoDB Agent.

Note

Starting with this step, follow the MongoDB Agent installation modal and copy the provided commands 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 IBM zSeries:

copy

curl -OL https://cloud.mongodb.com/download/agent/automation/mongodb-mms-automation-agent-manager-latest.s390x.rhel7.rpm

6

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.

copy

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

Update the following configuration options:

Key	Value
mmsGroupId	ProjectID of your project.
mmsApiKey	Agent API key of your project.

7

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

To configure the MongoDB Agent to connect to Cloud 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.

copy

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

Add the following configuration key:

Key	Value
httpProxy	URL (hostname and port) of to your proxy server.

8

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:

copy

sudo mkdir /data; sudo chown mongod:mongod /data

9

Start the MongoDB Agent.

Issue the following command:

copy

sudo service mongodb-mms-automation-agent start

10

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.

11

Finish the installation of the MongoDB Agent.

In the Install Agent Instructions modal, click Done.

12

Repeat the installation procedure for each MongoDB host.

Use this procedure to install update to the MongoDB Agent on Linux systems that do not use deb or rpm packages.

1

Log in to the Cloud Manager.

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

Add any existing configuration options for your legacy Monitoring Agent.

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

To add options that you had for your Monitoring Agent, 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.
4. 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

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

4

Install 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 Other Linux - TAR.
3. Click Next. The Install New MongoDB Agent modal opens.

5

Download the latest version of the MongoDB Agent.

Note

Starting with this step, follow the MongoDB Agent installation modal and copy the provided commands 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:

copy

curl -OL https://cloud.mongodb.com/download/agent/automation/mongodb-mms-automation-agent-manager-latest.linux_x86_64.tar.gz

6

Extract the MongoDB Agent.

You can install the MongoDB Agent in any directory. If you want to move the archive to another directory before extracting, you may do so.

To install the MongoDB Agent, extract the archive:

copy

tar -xvzf mongodb-mms-automation-agent-<VERSION>.linux_x86_64.tar.gz

7

Change to the extracted binary directory.

Change into the directory that was created after extracting the MongoDB Agent binary:

copy

cd mongodb-mms-automation-agent-<VERSION>.linux_x86_64

8

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.

copy

vi <install-path>/local.config

Update the following configuration options:

Key	Value
mmsGroupId	ProjectID of your project.
mmsApiKey	Agent API key of your project.

9

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

To configure the MongoDB Agent to connect to Cloud 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.

copy

vi <install-path>/local.config

Add the following configuration key:

Key	Value
httpProxy	URL (hostname and port) of to your proxy server.

10

Optional: Create the binary, log, and data directories.

If you have an existing Monitoring Agent user 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:

copy

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

Using a Different Path than /var/lib

By default, the Agent binaries and Cloud 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:

1. Click Deployment, then 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 (Linux/MacOS).

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 Agent.

   copy

   sudo mkdir -m 755 -p /<newPath>
   

To change the location of the Agent configuration backup:

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

2. Change the mmsConfigBackup setting to the new path for the configuration backup file.

   copy

   mmsConfigBackup=/<newPath>/mms-cluster-config-backup.json
   

3. Save the Agent configuration file.

4. Move the configuration backup file to the new directory.

   copy

   sudo mv /var/lib/mongodb-mms-automation/mms-cluster-config-backup.json /<newPath>
   

11

Assign permissions to the system user that runs the MongoDB Agent.

Run the following commands:

copy

# 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

12

Start the MongoDB Agent.

From the directory in which you installed the MongoDB Agent and as the system user you created in the last step, issue the following command:

copy

nohup ./mongodb-mms-automation-agent \
  --config=local.config \
  >> /var/log/mongodb-mms-automation/automation-agent-fatal.log 2>&1 &

13

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.

14

Finish the installation of the MongoDB Agent.

At the Final Steps modal, the legacy Backup and Monitoring Agents are put into standby mode. Click Finish.

15

Repeat the installation procedure for each MongoDB host.

Next Steps

After the MongoDB Agent update completes:

• If Automation did not previously manage your Monitoring Agent, activate Backup and/or Monitoring on your MongoDB deployment.
• If Automation did previously manage your Monitoring Agent, it is now activated. To verify that Automation is 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.

←   Update from all legacy Agents Update from the legacy Backup and Monitoring Agents  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.