Navigation
This version of the documentation is archived and no longer supported. To learn how to upgrade your version of MongoDB Ops Manager, refer to the upgrade documentation.
You were redirected from a different version of the documentation. Click here to go back.
This version of the manual is no longer supported.

MongoDB Agent Settings

    This page describes possible settings for the MongoDB Agent. These values are set after first launching Ops Manager and not through manual editing of these files.

    See Ops Manager Configuration Settings for the Ops Manager settings and their values.

    Warning

    If you edit authentication or TLS settings through Settings or Deployments in the Ops Manager interface, those changes overwrite any manual changes in this configuration file.

    Configuration File & Settings Locations

    The location of the MongoDB Agent configuration file is C:\MMSData\Automation\automation-agent.config.

    Note

    The MongoDB Agent configuration file is named automation-agent.config as a way to enable easier upgrades for those using legacy agents.

    The location of the MongoDB Agent configuration file is /path/to/install/local.config.

    The location of the MongoDB Agent configuration file is /etc/mongodb-mms/automation-agent.config.

    Note

    The MongoDB Agent configuration file is named automation-agent.config as a way to enable easier upgrades for those using legacy agents.

    The location of the MongoDB Agent configuration file is /etc/mongodb-mms/automation-agent.config.

    Note

    The MongoDB Agent configuration file is named automation-agent.config as a way to enable easier upgrades for those using legacy agents.

    The location of the MongoDB Agent configuration file is /path/to/install/local.config.

    You can configure additional Monitoring settings and Backup settings through the Ops Manager UI.

    MongoDB Agent Settings

    The following required settings vary depending on whether or not you use server pools. All other settings are set to default values.

    mmsBaseUrl

    Type: string

    Specifies the URL of the Ops Manager Application.

    mmsBaseUrl=http://example.com:8080
    
    mmsGroupId

    Type: string

    Required.

    Specifies the ID of your Ops Manager project. In Ops Manager, click Deployments, then Agents and then select the appropriate operating system under Downloads & Settings.

    When the Install Agent Instructions box appears, these values can be copied directly from this box by clicking copy icon .

    This setting is usually set when the MongoDB Agent is installed and is required to bind the server to a project.

    mmsGroupId=8zvbo2s2asigxvmpnkq5yexf
    
    mmsApiKey

    Type: string

    Required.

    Specifies the Ops Manager agent API key of your Ops Manager project.

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

    To generate an Agent API key, go to the Agent API Keys tab. To navigate to the tab, from the Deployment view, click the Agents tab and then the Agent API Keys tab.

    Important

    When you generate an Agent API Key, Ops Manager displays it one time only. You must copy this key. Treat it like a password; store it in a secure place. Ops Manager never displays the full key again.

    This setting is usually set when the MongoDB Agent is installed and is required to bind the server to a project.

    Note

    You can specify the password from a shell command by using the mmsApiKeyExec option instead of mmsApiKey.

    mmsApiKey=8zvbo2s2asigxvmpnkq5yexf
    

    Important

    Do not configure the Server Pool settings:

    Server Pools deprecated as of Ops Manager 4.0

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

    serverPoolKey

    Type: string

    Required.

    Specifies the Server Pool Key.

    The server pool key associates this server to the server pool.

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

    serverPoolKey=somekeyabc123
    
    serverPoolPropertiesFile

    Type: string

    Required.

    Specifies the full filepath of a file that contains server properties.

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

    Note

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

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

    The properties and the values in this file may be presented to the user during server request as options when a user requests servers from the server pool. That is, the user can request servers that match certain properties.

    The Ops Manager Administrator determines which properties to display to the user in the server request screen. For details, see Servers Request Options page.

    Ensure the MongoDB Agent can read the file:

    chmod 755 /path/to/some/propertiesfile.txt
    
    serverPoolPropertiesFile=/path/to/some/propertiesfile.txt
    
    serverPoolStateFile

    Specifies the full filepath of the file to be used by the MongoDB Agent. Required if adding the server to a server pool.

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

    serverPoolStateFile=/path/to/some/statefile.txt
    

    Important

    Do not configure the Project settings:

    Logging Settings

    logFile

    Type: string

    Specifies the path to which Ops Manager should write the MongoDB Agent’s log.

    The default path depends on your platform. The MongoDB Agent uses the default filename automation-agent.log whether or not the deployment uses Automation.

    Platform Default Path
    Linux /var/log/mongodb-mms-automation/automation-agent.log
    Windows C:\MMSAutomation\log\mongodb-mms-automation\automation-agent.log
    logFile=/path/to/mongodb-mms-automation/automation-agent.log
    
    logLevel

    Type: string

    Specifies the level of logging granularity.

    Warning

    The Admin Project Settings for Monitoring Agent Log Level and Automation Agent Log Level override this parameter.

    Choose from the following severity levels, from most to least amount of information:

    • DEBUG
    • INFO
    • WARN
    • ERROR
    • FATAL

    By default, logLevel is INFO.

    logLevel=ROUTINE
    

    Each level includes the log items included in the succeeding levels.

    Example

    • If you choose DEBUG, the MongoDB Agent logs all messages, including INFO, WARN, ERROR and FATAL.
    • If you choose FATAL, the MongoDB Agent only logs FATAL messages.
    maxLogFiles

    Type: integer

    Specifies the maximum number of rotated log files to retain.

    By default, maxLogFiles is 10. You can change the value to retain a different quantity of rotated log files.

    maxLogFiles=15
    
    maxLogFileDurationHrs

    Type: float

    Specifies the number of hours after which the logs are rotated.

    Manually Rotate the MongoDB Agent Logs

    On UNIX- and Linux-based systems you can manually rotate the MongoDB Agent logs. Issue a kill command with the SIGUSR1 signal for the Agent process:

    kill -SIGUSR1 <AgentID>
    

    On Windows-based systems, you can manually restart the MongoDB Agent with a Service restart:

    1. Click the Start menu.
    2. Search for services.
    3. Find the MongoDB Agent.
    4. Right-click on the Agent and click Restart.

    This rotates the MongoDB Agent logs.

    maxLogFileSizeBytes

    Type: integer

    Specifies the maximum size, in bytes, of a log file before the logs are rotated. If unspecified, the MongoDB Agent does not rotate logs based on file size.

    maxLogFileSizeBytes=536870912
    

    Connection Settings

    dialTimeoutSeconds

    Type: integer

    Specifies the number of seconds to wait before a connection times out. By default, connections time out after 40 seconds. However, The MongoDB Agent may frequently time out of connections for one or more of the following reasons:

    • High network latency
    • High server load
    • Large TLS keys
    • Lack of TLS accelerator
    • Insufficient CPU speed

    MongoDB recommends gradually increasing the value of the dialTimeoutSeconds MongoDB Agent configuration setting to prevent frequent premature connection timeouts.

    dialTimeoutSeconds=40
    

    Note

    Increasing this value also increases the time required to deploy configuration changes to the MongoDB Agent. Experiment with small, incremental increases until you determine the optimum value for your deployment.

    serverSelectionTimeoutSeconds

    Type: integer

    Specifies the number of seconds the MongoDB Agent waits before it stops trying to establish a connection to a MongoDB process. By default, the MongoDB Agent abandons attempts to establish a connection after 10 seconds.

    serverSelectionTimeoutSeconds=10
    

    HTTP Proxy Settings

    httpProxy

    Type: string

    Specifies the URL of an HTTP proxy server the MongoDB Agent can use.

    httpProxy=http://proxy.example.com:8080
    

    Configuration Backup Settings

    mmsConfigBackup

    Type: string

    Specifies the path to the Ops Manager configuration backup file. This file describes the desired state of the deployment.

    mmsConfigBackup=/path/to/mms-cluster-config-backup.json
    

    Note

    When Ops Manager is installed, it stores the configuration backup file is stored in one of the following places, depending on your platform:

    Platform Configuration Backup File Path
    Linux /var/lib/mongodb-mms-automation/
    Windows %SystemDrive%\MMSAutomation

    Ops Manager TLS Settings

    Specify the settings that the MongoDB Agent uses when communicating with Ops Manager using TLS.

    sslTrustedMMSServerCertificate

    Type: string

    Specifies the absolute path that contains the trusted Certificate Authority certificates in PEM format. This certificate verifies that the MongoDB Agent is talking to the designated Ops Manager instance.

    sslTrustedMMSServerCertificate=/path/to/ca.pem
    

    Note

    Add the Certificate Authority for the downloads.mongodb.com certificate to this .pem file if you:

    1. Need your MongoDB Agents to download their MongoDB installers from the Internet,
    2. Use TLS to encrypt connections, and
    3. Signed your certificates with a private CA. (You set the sslTrustedMMSServerCertificate option.)

    To learn how to download TLS certificates from another web site, see the OpenSSL Cookbook entry.

    Important

    When Ops Manager starts, it caches the Certificate Authority you provided. If you change your Certificate Authority certificate, restart Ops Manager.

    sslRequireValidMMSServerCertificates

    Type: boolean

    Deprecated since version v4.2: Use tlsRequireValidMMSServerCertificates

    tlsRequireValidMMSServerCertificates

    Type: boolean

    Specifies if the MongoDB Agent should validate TLS certificates presented by Ops Manager.

    Warning

    Setting this option to false disables certificate verification and makes connections between the MongoDB Agent and Ops Manager susceptible to man-in-the-middle attacks. Setting this option to false is only recommended for testing purposes.

    tlsRequireValidMMSServerCertificates=true
    
    sslMMSServerClientCertificate

    Type: string

    Specifies the path to the file containing the client’s private key, certificate, and optional intermediate certificates in PEM format. The MongoDB Agent uses the client certificate when connecting to Ops Manager over TLS if Ops Manager requires client certificates, such as when Ops Manager runs with Client Certificate Mode set to Required for Agents Only or Required for All Requests.

    See also

    To learn how to set Client Certificate Mode, see Ops Manager Configuration Settings.

    sslMMSServerClientCertificate=/path/to/client.pem
    
    sslMMSServerClientCertificatePassword

    Type: string

    Specifies the password needed to decrypt the private key in the sslMMSServerClientCertificate file. This setting is required when the client certificate PEM file is encrypted.

    Note

    Use the sslMMSServerClientCertificatePasswordExec option instead of sslMMSServerClientCertificatePassword to specify the password from a shell command.

    sslMMSServerClientCertificatePassword=password
    
    sslRequireValidMMSServerCertificates

    Type: boolean

    Specifies if the MongoDB Agent should validate SSL certificates from Ops Manager.

    Warning

    Setting this option to false disables certificate verification and makes connections between the MongoDB Agent and Ops Manager susceptible to man-in-the-middle attacks. Setting this option to false is only recommended for testing purposes.

    sslServerClientCertificate

    Type: string

    Specifies the path to the file containing the client’s private key, certificate, and optional intermediate certificates in PEM format. The MongoDB Agent uses the client certificate when connecting to Ops Manager over TLS if Ops Manager requires client certificates, such as when Ops Manager runs with Client Certificate Mode set to Required for Agents Only or Required for All Requests.

    See also

    See Client Certificate Mode in Ops Manager Configuration Settings for how to specify this setting in the Ops Manager Application.

    sslServerClientCertificate=/path/to/client.pem
    
    sslServerClientCertificatePassword

    Specifies the password needed to decrypt the private key in the sslServerClientCertificate file. This setting is required when the client certificate PEM file is encrypted.

    sslServerClientCertificatePassword=password
    
    sslRequireValidMMSBackupServerCertificate

    Specifies if the MongoDB Agent should validate TLS certificates from Ops Manager.

    Warning

    Setting this option to false disables certificate verification and makes connections between the MongoDB Agent and Ops Manager susceptible to man-in-the-middle attacks. Setting this option to false is only recommended for testing purposes.

    sslRequireValidMMSBackupServerCertificate=true
    

    Externally Sourced Configuration Settings

    enableLocalConfigurationServer

    Type: boolean

    Specifies whether the MongoDB Agent stores MongoDB process configuration files on disk or cached in memory.

    This option defaults to false, which stores the configuration files on disk. Setting this option to true caches the configuration in memory.

    Warning

    Setting this option to true impacts the availability of your deployment.

    When this feature is enabled, the MongoDB Agent doesn’t store the MongoDB process configuration on disk. If the Ops Manager app server is unavailable and the MongoDB Agent attempts to restart, then the MongoDB Agent stops running because it doesn’t have the necessary configuration information. If a MongoDB process crashes while the MongoDB Agent isn’t running, then the MongoDB Agent can’t restart the process.

    enableLocalConfigurationServer=false
    
    localConfigurationServerPort

    Type: integer

    Specifies the port to serve the MongoDB process configuration to when using the local configuration server. To set this option, enableLocalConfigurationServer must be true.

    If unspecified, the MongoDB Agent chooses an available port automatically.

    localConfigurationServerPort=20128
    
    mmsApiKeyExec

    Type: string

    Specifies a shell command to call the Ops Manager agent API key of your Ops Manager project .

    mmsApiKeyExec=echo $myKey
    
    sslMMSServerClientCertificatePasswordExec

    Type: string

    Important

    Deprecated. Use tlsMMSServerClientCertificatePasswordExec instead.

    tlsMMSServerClientCertificatePasswordExec

    Type: string

    Specifies a shell command to call the password needed to decrypt the private key in the MMSServerClientCertificate file. Either this setting or tlsMMSServerClientCertificatePassword is required when the client certificate PEM file is encrypted.

    tlsMMSServerClientCertificatePasswordExec=python /path/to/PEMPassword.py
    

    Automation Settings

    The following configuration settings are used for authentication in automated clusters.

    MongoDB Kerberos Settings

    Specify these settings if Automation authenticates to hosts using Kerberos. To configure Kerberos, see Configure the Monitoring Agent for Kerberos.

    krb5ConfigLocation

    Type: string

    Specifies an absolute path to an non-system-standard location for the Kerberos configuration file.

    krb5ConfigLocation=/path/to/krb_custom.conf
    

    Note

    Ops Manager creates a Kerberos Credential (Ticket) Cache for each agent automatically when Kerberos is enabled. If you want to override the location of the Kerberos Credential Cache, you must set the KRB5CCNAME environment variable to the desired file name and path before running the agent.

    backupAgentKrb5CCName

    Type string

    Specifies the KRB5CC environment variable that the MongoDB Agent sets for the Backup process. Used only to authenticate the Backup to your MongoDB deployment when the MongoDB Agent starts the Backup function.

    backupAgentKrb5CCName=/path/to/credentials_cache_file
    
    monitoringAgentKrb5CCName

    Type string

    Specifies the KRB5CC environment variable that the MongoDB Agent sets for the Monitoring function. Used only to authenticate Monitoring to your MongoDB deployment when the MongoDB Agent starts the Monitoring function.

    monitoringAgentKrb5CCName=/path/to/credentials_cache_file
    

    Monitoring Settings

    Use the Ops Manager interface to configure Monitoring settings.

    Log Settings

    1. In the navigation, click Deployment.

    2. Click the Agents tab.

    3. Click Downloads & Settings.

    4. In the Agent Log Settings section, click edit icon next to Monitoring Log Settings.

    5. Edit the Monitoring log settings:

      Setting Default Value UI Suggested Value
      Linux Log File Path /var/log/mongodb-mms-automation/monitoring-agent.log  
      Windows Log File Path %SystemDrive%\MMSAutomation\log\mongodb-mms-automation\monitoring-agent.log  
      Rotate Logs YES  
      Size Threshold (MB) 1000  
      Time Threshold (Hours) 24  
      Max Uncompressed Files   5
      Max Percent of Disk   2
      Total Number of Log Files 0  
    6. Click Save.

    Custom Settings

    1. In the navigation, click Deployment.
    2. Click the Agents tab.
    3. Click Downloads & Settings.
    4. In the Custom Configuration section, next to Edit Custom Configurations, click edit icon .
    5. Enter the Monitoring configuration setting and value.
    6. Click Save and Close.

    You can configure the following Monitoring settings:

    Note

    The following settings are deprecated:

    Backup Settings

    Use the Ops Manager interface to configure Backup settings.

    Log Settings

    1. In the navigation, click Deployment.

    2. Click the Agents tab.

    3. Click Downloads & Settings.

    4. In the Agent Log Settings section, click edit icon next to: guilabel:Backup Log Settings.

    5. Edit the Backup log settings:

      Setting Default Value UI Suggested Value
      Linux Log File Path /var/log/mongodb-mms-automation/backup-agent.log  
      Windows Log File Path %SystemDrive%\MMSAutomation\log\mongodb-mms-automation\backup-agent.log  
      Rotate Logs YES  
      Size Threshold (MB) 1000  
      Time Threshold (Hours) 24  
      Max Uncompressed Files   5
      Max Percent of Disk   2
      Total Number of Log Files 0  
    6. Click Save.

    Custom Settings

    1. In the navigation, click Deployment.
    2. Click the Agents tab.
    3. Click Downloads & Settings.
    4. In the Custom Configuration section, next to Edit Custom Configurations, click edit icon .
    5. Enter a Backup configuration setting and value.
    6. Click Save and Close.

    You can configure the following Backup settings: