Docs Menu
Docs Home
/
MongoDB Cloud Manager
/ /

Install the MongoDB Agent to Only Monitor or Backup Deployments

You have a project and want to install the MongoDB Agent to monitor and/or back up your MongoDB deployments. You are choosing not to manage your MongoDB deployments at this time.

Note

Review the Prerequisites First

Please review the MongoDB Agent Prerequisites before installing the MongoDB Agent.

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

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click Windows - MSI.

3

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 Generate Key.

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

4
  1. After the MSI downloads, double-click:

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

  2. If a security warning appears, click Run.

  3. At the Configuration/Log Folder step

    Provide the directory into which these files are saved.

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

  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, you are asked to disable it. 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 interpreter or PowerShell. To learn more about unattended installs, see Microsoft's documentation on Standard Installer Command-Line Options

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

Parameter
Necessity
Value
MMSAPIKEY
Required
Agent API key of your 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, you would invoke msiexec.exe with the following options:

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

In the Install Agent Instructions modal, click Done.

6

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

Note

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

get-childitem env:SystemDrive

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

To change the location of the MongoDB Agent Binaries

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

  2. Below the Download Directory heading, click 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:

    md \<newPath>

    Important

    Make sure 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 with the drive letter on which your backup is stored.

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

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

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

Use this procedure to install the MongoDB Agent:

Important

Starting with version 10.24.0.6714-1, when you install the MongoDB Agent using deb or rpm packages, the package doesn't add MongoDB binaries to the PATH environment variable.

If your deployment depends on the presence of MongoDB binaries in the PATH, you must manually add the paths to MongoDB binaries to the PATH. To learn how to update environment variables, refer to your operating system's documentation.

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

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click Debian 8/9, Ubuntu 16.X/18.X - DEB.

3

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/22.04 or Debian 9/10/11 for 64-bit x86:

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

In the directory where you installed the MongoDB Agent, open theautomation-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.
5

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 theautomation-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.
6

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
7

Issue the following command:

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

In the Install Agent Instructions modal, click Done.

9

Important

Starting with version 10.24.0.6714-1, when you install the MongoDB Agent using deb or rpm packages, the package doesn't add MongoDB binaries to the PATH environment variable.

If your deployment depends on the presence of MongoDB binaries in the PATH, you must manually add the paths to MongoDB binaries to the PATH. To learn how to update environment variables, refer to your operating system's documentation.

On zSeries architecture running Ubuntu 18.04 using a deb package:

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click Ubuntu 18.X Z-Series (s390x) - DEB.

3

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:

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

In the directory where you installed the MongoDB Agent, open theautomation-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.
5

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 theautomation-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.
6

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
7

Issue the following command:

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

In the Install Agent Instructions modal, click Done.

9

Use this procedure to install the MongoDB Agent:

On x86_64 architecture:

Important

Starting with version 10.24.0.6714-1, when you install the MongoDB Agent using deb or rpm packages, the package doesn't add MongoDB binaries to the PATH environment variable.

If your deployment depends on the presence of MongoDB binaries in the PATH, you must manually add the paths to MongoDB binaries to the PATH. To learn how to update environment variables, refer to your operating system's documentation.

Running Amazon Linux using an rpm package:

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click Amazon Linux - RPM.

3

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 64-bit x86:

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

In the directory where you installed the MongoDB Agent, open theautomation-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.
5

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 theautomation-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.
6

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
7

Issue the following command:

sudo service mongodb-mms-automation-agent start
8

In the Install Agent Instructions modal, click Done.

9

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

Important

Starting with version 10.24.0.6714-1, when you install the MongoDB Agent using deb or rpm packages, the package doesn't add MongoDB binaries to the PATH environment variable.

If your deployment depends on the presence of MongoDB binaries in the PATH, you must manually add the paths to MongoDB binaries to the PATH. To learn how to update environment variables, refer to your operating system's documentation.

Using an rpm package:

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click RHEL/CentOS (7.X), SUSE12, Amazon Linux2 - RPM.

3

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 64-bit x86:

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

In the directory where you installed the MongoDB Agent, open theautomation-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.
5

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 theautomation-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.
6

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
7

Issue the following command:

sudo service mongodb-mms-automation-agent start
8

In the Install Agent Instructions modal, click Done.

9

Using a tar archive:

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click RHEL/CentOS (7.X), SUSE12, Amazon Linux 2 - TAR.

3

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 for 64-bit x86:

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

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:

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

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

cd mongodb-mms-automation-agent-<VERSION>.rhel7_x86_64
6

In the directory where you installed the MongoDB Agent, open thelocal.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.
7

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 thelocal.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.
8

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 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
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Deployment page is not already displayed, click Deployment in the sidebar.

2

Click the Agents tab.

3
  1. Click Downloads & Settings.

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

  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.

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.

    mmsConfigBackup=/<newPath>/mms-cluster-config-backup.json
  3. Save the Agent configuration file.

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

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

Run the following commands:

# Create mongod user and group if they do not exist
if ! sudo /usr/bin/id -g mongod &>/dev/null; then
sudo /usr/sbin/groupadd -r mongod
fi
# Create mongod user if they do not exist and assign
# them to the mongod group
if ! sudo /usr/bin/id mongod &>/dev/null; then
sudo /usr/sbin/useradd -M -r -g mongod \
-d /var/lib/mongo -s /bin/false \
-c mongod mongod > /dev/null 2>&1
fi
# Grant the mongod:mongod user and group permissions
# to manage deployments.
sudo chown mongod:mongod /var/lib/mongod-mms-automation
sudo chown mongod:mongod /var/log/mongod-mms-automation
sudo chown mongod:mongod /data
10

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:

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

In the Install Agent Instructions modal, click Done.

12

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

Important

Starting with version 10.24.0.6714-1, when you install the MongoDB Agent using deb or rpm packages, the package doesn't add MongoDB binaries to the PATH environment variable.

If your deployment depends on the presence of MongoDB binaries in the PATH, you must manually add the paths to MongoDB binaries to the PATH. To learn how to update environment variables, refer to your operating system's documentation.

Using an rpm package:

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click RHEL/CentOS (7.X) Power (ppc64le) - RPM.

3

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

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

In the directory where you installed the MongoDB Agent, open theautomation-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.
5

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 theautomation-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.
6

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
7

Issue the following command:

sudo service mongodb-mms-automation-agent start
8

In the Install Agent Instructions modal, click Done.

9

Using a tar archive:

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click RHEL/CentOS (7.X) Power (ppc64le) - TAR.

3

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

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

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:

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

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

cd mongodb-mms-automation-agent-<VERSION>.rhel7_ppc64le
6

In the directory where you installed the MongoDB Agent, open thelocal.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.
7

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 thelocal.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.
8

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 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
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Deployment page is not already displayed, click Deployment in the sidebar.

2

Click the Agents tab.

3
  1. Click Downloads & Settings.

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

  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.

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.

    mmsConfigBackup=/<newPath>/mms-cluster-config-backup.json
  3. Save the Agent configuration file.

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

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

Run the following commands:

# Create mongod user and group if they do not exist
if ! sudo /usr/bin/id -g mongod &>/dev/null; then
sudo /usr/sbin/groupadd -r mongod
fi
# Create mongod user if they do not exist and assign
# them to the mongod group
if ! sudo /usr/bin/id mongod &>/dev/null; then
sudo /usr/sbin/useradd -M -r -g mongod \
-d /var/lib/mongo -s /bin/false \
-c mongod mongod > /dev/null 2>&1
fi
# Grant the mongod:mongod user and group permissions
# to manage deployments.
sudo chown mongod:mongod /var/lib/mongod-mms-automation
sudo chown mongod:mongod /var/log/mongod-mms-automation
sudo chown mongod:mongod /data
10

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:

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

In the Install Agent Instructions modal, click Done.

12

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

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

Important

Starting with version 10.24.0.6714-1, when you install the MongoDB Agent using deb or rpm packages, the package doesn't add MongoDB binaries to the PATH environment variable.

If your deployment depends on the presence of MongoDB binaries in the PATH, you must manually add the paths to MongoDB binaries to the PATH. To learn how to update environment variables, refer to your operating system's documentation.

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click RHEL 7.X/8X Z-Series (s390x) - RPM.

3

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.X/8.X for IBM zSeries:

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

In the directory where you installed the MongoDB Agent, open theautomation-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.
5

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 theautomation-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.
6

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
7

Issue the following command:

sudo service mongodb-mms-automation-agent start
8

In the Install Agent Instructions modal, click Done.

9

On ARM64 architecture running RHEL 8.x/9.x or Amazon Linux 2:

Important

Starting with version 10.24.0.6714-1, when you install the MongoDB Agent using deb or rpm packages, the package doesn't add MongoDB binaries to the PATH environment variable.

If your deployment depends on the presence of MongoDB binaries in the PATH, you must manually add the paths to MongoDB binaries to the PATH. To learn how to update environment variables, refer to your operating system's documentation.

Running RHEL 8.x/9.x or Amazon Linux 2 using the rpm package manager:

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click RHEL/CentOS (8.X/9.X), Amazon Linux 2, Amazon Linux 2023 - TAR (ARM).

3

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 8.x/9.x or Amazon Linux 2 for ARM64:

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

In the directory where you installed the MongoDB Agent, open theautomation-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.
5

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 theautomation-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.
6

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
7

Issue the following command:

sudo service mongodb-mms-automation-agent start
8

In the Install Agent Instructions modal, click Done.

9

Running RHEL 8.x/9.x or Amazon Linux 2 using a tar archive:

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click RHEL/CentOS (8.X/9.X), Amazon Linux 2, Amazon Linux 2023 - TAR (ARM).

3

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 8.x/9.x or Amazon Linux 2 for ARM64:

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

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:

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

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

cd mongodb-mms-automation-agent-<VERSION>.amzn2_aarch64
6

In the directory where you installed the MongoDB Agent, open thelocal.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.
7

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 thelocal.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.
8

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 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
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Deployment page is not already displayed, click Deployment in the sidebar.

2

Click the Agents tab.

3
  1. Click Downloads & Settings.

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

  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.

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.

    mmsConfigBackup=/<newPath>/mms-cluster-config-backup.json
  3. Save the Agent configuration file.

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

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

Run the following commands:

# Create mongod user and group if they do not exist
if ! sudo /usr/bin/id -g mongod &>/dev/null; then
sudo /usr/sbin/groupadd -r mongod
fi
# Create mongod user if they do not exist and assign
# them to the mongod group
if ! sudo /usr/bin/id mongod &>/dev/null; then
sudo /usr/sbin/useradd -M -r -g mongod \
-d /var/lib/mongo -s /bin/false \
-c mongod mongod > /dev/null 2>&1
fi
# Grant the mongod:mongod user and group permissions
# to manage deployments.
sudo chown mongod:mongod /var/lib/mongod-mms-automation
sudo chown mongod:mongod /var/log/mongod-mms-automation
sudo chown mongod:mongod /data
10

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:

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

In the Install Agent Instructions modal, click Done.

12

Use this procedure to install Linux systems that do not use deb or rpm packages.

1
2

If you have a project with existing deployments, you can install the MongoDB Agent on your existing deployments:

  1. Select the desired Project from the Context menu.

  2. Click Deployment.

  3. Click Agents.

  4. Click Downloads & Settings.

  5. From the Select Your Server's Operating System menu, click Other Linux - TAR.

3

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:

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

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:

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

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

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

In the directory where you installed the MongoDB Agent, open thelocal.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.
7

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 thelocal.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.
8

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 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
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Deployment page is not already displayed, click Deployment in the sidebar.

2

Click the Agents tab.

3
  1. Click Downloads & Settings.

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

  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.

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.

    mmsConfigBackup=/<newPath>/mms-cluster-config-backup.json
  3. Save the Agent configuration file.

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

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

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
10

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:

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

In the Install Agent Instructions modal, click Done.

12

Back

Install the MongoDB Agent to Manage Deployments

Next

Verify Integrity of