Navigation

Automation Configuration Resource

Overview

The Public API provides the automationConfig resource to let you manipulate your group’s automation configuration. The configuration defines the various MongoDB clusters, replica sets and standalones in the deployment and defines how each process runs. The Automation Agents build the deployment according to the goals specified. Each Automation Agent is responsible for the MongoDB processes that run on its host. The configuration also specifies settings for the deployment’s agents.

When a running MongoDB process matches its defined configuration, the process is in “goal state.” When all processes on all hosts are in goal state, the deployment itself is in goal state.

For example automation configurations, please see the following page on GitHub: https://github.com/10gen-labs/mms-api-examples/tree/master/automation/.

To update the automation configuration, you must issue the request from an IP address on your user account’s whitelist.

Endpoints

Get the Automation Configuration

Retrieve the current automation configuration for a group.

GET /api/public/v1.0/groups/GROUP-ID/automationConfig

Update the Automation Configuration

PUT /api/public/v1.0/groups/GROUP-ID/automationConfig

Use PUT to update a group’s automation configuration. Do not use PATCH. For steps for updating an automation configuration, see Update the Automation Configuration.

To make updates to the Monitoring Agent or Backup Agent other than hostname, you must do so through a different endpoint. See Update the Monitoring Agent or Backup Agent.

When you submit updates, Ops Manager makes internal modifications to the data and then saves your new configuration version. For example, Ops Manager might add a field to each specified community MongoDB version to indicate where the agents download them from.

The Automation Agents continuously poll Ops Manager for changes to the configuration and fetch configuration updates when they occur. The agents then adjust the states of their live processes to match.

Warning

There is no protection in the Public API to prevent concurrent modifications. If two administrators both start with a configuration based on the current version, make their own modifications, and then submit their modifications, the later modification wins.

Update the Monitoring Agent or Backup Agent

Some attributes of the monitoringVersions and backupVersions objects cannot be updated through the automationConfig endpoint. Ops Manager provides the following endpoints to update these fields.

Important

Do not use these endpoints to update the agent’s host. To update monitoringVersions.hostname or backupVersions.hostname, use the endpoint to update the entire configuration.

Update Monitoring Agent attributes:

PUT /api/public/v1.0/groups/GROUP-ID/automationConfig/monitoringAgentConfig

Update Backup Agent attributes:

PUT /api/public/v1.0/groups/GROUP-ID/automationConfig/backupAgentConfig

The endpoints update the following agent attributes. Pass an object with all the attributes that you use, whether or not the value is changing. If you do not use a field, do not include it:

  • logPath (required for non-Windows operating systems)
  • logPathWindows (required for Windows operating systems)
  • logRotate
    • logRotate.sizeThresholdMB
    • logRotate.timeThresholdHrs
    • logRotate.numUncompressed
    • logRotate.percentOfDiskspace
  • username
  • password
  • kerberosPrincipal
  • kerberosKeytab
  • kerberosWindowsUsername (only required if Windows MongoDB deployment uses Kerberos authentication)
  • kerberosWindowsPassword (only required if Windows MongoDB deployment uses Kerberos authentication)
  • sslPEMKeyFile
  • sslPEMKeyFileWindows (only required if deployment contains Windows processes)
  • sslPEMKeyPwd

Other Representations of the Automation Configuration

The Automation Agent stores a copy of the configuration in the mms-cluster-config-backup.json file. The agent stores the most recent version of configuration with which the agent was able to reach goal state. If an agent is not able to process configuration changes, it continues to store an older version of the configuration.

Users with global roles can view Ops Manager‘s internal representation of the deployment configuration, which is much larger than the automation configuration and includes additional fields used only internally. Never use this representation to update the automation configuration. The representation is called the Raw AutomationConfig is viewable through the Deployment page.

Automation Configuration Entity

This section describes the fields that comprise the automation configuration. For additional examples, see the following page on GitHub: https://github.com/10gen-labs/mms-api-examples/tree/master/automation/.

Configuration Version

This lists the version of the automation configuration.

"version" : <integer>
Name Type Description
version integer The version of the configuration.

Download Base

The download base is the path to the directory where automatic version downloads will be targeted and scripts for starting processes will be created.

"options" : {
    "downloadBase" : <string>,
    "downloadBaseWindows" : <string>
}
Name Type Description
options object The options object is required and must contain both the downloadBase and downloadBaseWindows fields.
options.downloadBase string The directory on Linux and Unix (including Mac OS X) platforms for automatic version downloads and startup scripts.
options.downloadBaseWindows string The directory on Windows platforms for automatic version downloads and startup scripts.

MongoDB Versions Specifications

The mongoDbVersions array defines specification objects for the MongoDB instances found in the processes array. Each MongoDB instance in the processes array must have a specification object in this array.

"mongoDbVersions" : [
    {
        "name" : <string>,
        "builds" : [
            {
                "platform" : <string>,
                "url" : <string>,
                "gitVersion" : <string>,
                "modules" : [ <string>, ... ],
                "architecture" : <string>,
                "bits" : <integer>,
                "win2008plus" : <Boolean>,
                "winVCRedistUrl" : <string>,
                "winVCRedistOptions" : [ <string>, ... ],
                "winVCRedistDll" : <string>,
                "winVCRedistVersion" : <string>
            },
            ...
        ],
    },
    ...
]
Name Type Description
mongoDbVersions array of objects The mongoDbVersions array is required and defines specification objects for the MongoDB instances found in the processes array. Each MongoDB instance in processes must have a specification object in mongoDbVersions.
mongoDbVersions.name string The name of the specification object. The specification object is attached to a MongoDB instance through the instance’s processes.version field in this configuration.
mongoDbVersions.builds array of objects Objects that define the builds for this MongoDB instance.
mongoDbVersions.builds.platform string The platform for this MongoDB instance.
mongoDbVersions.builds.url string The URL from which to download MongoDB for this instance.
mongoDbVersions.builds.gitVersion string The commit identifier that identifies the state of the code used to build the MongoDB process. The MongoDB buildInfo command returns the gitVersion identifier.
mongoDbVersions.builds.modules array The list of modules for this version. Corresponds to the modules field returned by MongoDB 3.2+ buildInfo command.
mongoDbVersions.builds.architecture string The processor’s architecture. Possible values are amd64 or ppc64le.
mongoDbVersions.builds.bits integer Deprecated. The processor’s bus width. Do not remove or make modifications to this field.
mongoDbVersions.builds.win2008plus Boolean Optional. Set to true if this is a Windows build that requires either Windows 7 later or Windows Server 2008 R2 or later.
mongoDbVersions.builds.winVCRedistUrl string Optional. The URL from which the required version of the Microsoft Visual C++ redistributable can be downloaded.
mongoDbVersions.builds.winVCRedistOptions array Optional. String values that list the command-line options to be specified when running the Microsoft Visual C++ redistributable installer. Each command-line option is a separate string in the array.
mongoDbVersions.builds.winVCRedistDll string Optional. The name of the Microsoft Visual C++ runtime DLL file that the agent will check to determine if a new version of the Microsoft Visual C++ redistributable is needed.
mongoDbVersions.builds.winVCRedistVersion string Optional. The minimum version of the Microsoft Visual C++ runtime DLL that must be present to skip over the installation of the Microsoft Visual C++ redistributable.

Automation Agent

The agentVersion object is optional and specifies the version of Automation Agent.

"agentVersion" : {
    "name" : <string>,
    "directoryUrl" : <string>
}
Name Type Description
agentVersion object Optional The version of the Automation Agent to run. If the running version does not match this setting, the Automation Agent downloads the specified version, shuts itself down, and starts the new version.
agentVersion.name string The desired version of the Automation Agent (e.g. “1.8.1.1042-1”).
agentVersion.directoryUrl string The URL from which to download Automation Agent.

Monitoring Agent

The monitoringVersions array is optional and specifies the version of the Monitoring Agent.

"monitoringVersions" : [
    {
        "name" : <string>,
        "hostname" : <string>,
        "urls" : {
            <platform1> : {
                <build1> : <string>,
                ...,
                "default" : <string>
            },
            ...
        },
        "baseUrl" : <string>,
        "logPath" : <string>,
        "logRotate" : {
            "sizeThresholdMB" : <number>,
            "timeThresholdHrs" : <integer>,
            "numUncompressed": <integer>,
            "percentOfDiskspace" : <number>
        }
    },
    ...
]
Name Type Description
monitoringVersions array of objects Optional. Objects that define version information for each Monitoring Agent.
monitoringVersions.name string

The desired version of the Monitoring Agent (e.g. “2.9.1.176-1”).

For MongoDB compatibility with Automation, see MongoDB Compatibility Matrix.

monitoringVersions.hostname string The hostname of the machine that runs the Monitoring Agent. If the Monitoring Agent is not running on the machine, Ops Manager installs the agent from the location specified in monitoringVersions.urls.
monitoringVersions.urls object The platform- and build-specific URLs from which to download the Monitoring Agent.
monitoringVersions.urls.<platform> object This field has a name that identifies an operating system and optionally a version. The field contains an object with key-value pairs, where each key is either the name of a build or default and each value is a URL for downloading the Monitoring Agent. The object must include the default key set to the default download URL for the platform.
monitoringVersions.baseUrl string The base URL used for the mmsBaseUrl setting in the Monitoring Agent Configuration.
monitoringVersions.logPath string Optional. The directory where the agent stores its logs. The default is to store logs in /dev/null. To update, see the monitoringAgentConfig endpoint.
monitoringVersions.logRotate object Optional. Enables log rotation for the MongoDB logs for a process. To update, see the monitoringAgentConfig endpoint.
monitoringVersions.logRotate.sizeThresholdMB number The maximum size in MB for an individual log file before rotation. To update, see the monitoringAgentConfig endpoint.
monitoringVersions.logRotate.timeThresholdHrs integer The maximum time in hours for an individual log file before rotation. To update, see the monitoringAgentConfig endpoint.
monitoringVersions.logRotate.numUncompressed integer Optional. The maximum number of total log files to leave uncompressed, including the current log file. The default is 5. In earlier versions of Ops Manager, this field was named maxUncompressed. The earlier name is still recognized, though the new version is preferred. To update, see the monitoringAgentConfig endpoint.
monitoringVersions.logRotate.percentOfDiskspace number Optional. The maximum percentage of total disk space all log files should take up before deletion. The default is .02. To update, see the monitoringAgentConfig endpoint.

Backup Agent

The backupVersions array is optional and specifies the version of the Backup Agent.

"backupVersions" : [
    {
        "name" : <string>,
        "hostname" : <string>,
        "urls" : {
            <platform1> : {
                <build1> : <string>,
                ...,
                "default" : <string>
            },
            ...
        },
        "baseUrl" : <string>,
        "logPath" : <string>,
        "logRotate" : {
            "sizeThresholdMB" : <number>,
            "timeThresholdHrs" : <integer>,
            "numUncompressed": <integer>,
            "percentOfDiskspace" : <number>
        }
    },
    ...
]
Name Type Description
backupVersions array of objects Optional. Objects that define version information for each Backup Agent.
backupVersions.name string The desired version of the Backup Agent (e.g. “3.1.1.263-1”).
backupVersions.hostname string The hostname of the machine that runs the Backup Agent. If the Backup Agent is not running on the machine, Ops Manager installs the agent from the location specified in backupVersions.urls.
backupVersions.urls object The platform- and build-specific URLs from which to download the Backup Agent.
backupVersions.urls.<platform> object This field has a name that identifies an operating system and optionally a version. The field contains an object with key-value pairs, where each key is either the name of a build or default and each value is a URL for downloading the Backup Agent. The object must include the default key set to the default download URL for the platform.
backupVersions.baseUrl string The base URL used for the mothership and https settings in the Backup Agent Configuration. For example, for "baseUrl"=https://cloud.mongodb.com, the backup configuration fields would have these values: mothership=api-backup.mongodb.com and https"=true.
backupVersions.logPath string Optional. The directory where the agent stores its logs. The default is to store logs in /dev/null. To update, see the backupAgentConfig endpoint.
backupVersions.logRotate object Optional. Enables log rotation for the MongoDB logs for a process. To update, see the backupAgentConfig endpoint.
backupVersions.logRotate.sizeThresholdMB number The maximum size in MB for an individual log file before rotation. To update, see the backupAgentConfig endpoint.
backupVersions.logRotate.timeThresholdHrs integer The maximum time in hours for an individual log file before rotation. To update, see the backupAgentConfig endpoint.
backupVersions.logRotate.numUncompressed integer Optional. The maximum number of total log files to leave uncompressed, including the current log file. The default is 5. To update, see the backupAgentConfig endpoint.
backupVersions.logRotate.percentOfDiskspace number Optional. The maximum percentage of total disk space all log files should take up before deletion. The default is .02. To update, see the backupAgentConfig endpoint.

MongoDB Instances

The processes array determines the configuration of your MongoDB instances. You can also use the array to restore an instance.

"processes" : [
    {
        "name" : <string>,
        "processType" : <string>,
        "version" : <string>,
        "<args>" : <object>,
        "disabled" : <Boolean>,
        "manualMode" : <Boolean>,
        "hostname" : <string>,
        "authSchemaVersion" : <integer>,
        "featureCompatibilityVersion" : <string>,
        "cluster": <string>,
        "numCores": <integer>,
        "logRotate" : {
            "sizeThresholdMB" : <number>,
            "timeThresholdHrs" : <integer>,
            "numUncompressed": <integer>,
            "percentOfDiskspace" : <number>
        },
        "alias": <string>,
        "backupRestoreUrl" : <string>
    },
    ...
]
Name Type Description
processes array of objects The processes array contains objects that define the mongos and mongod instances that Ops Manager monitors. Each object defines a different instance.
processes.name string A unique name to identify the instance.
processes.processType string Either mongod or mongos.
processes.version string The name of the mongoDbVersions specification used with this instance.
processes.<args> object This field is named either args2_6, for MongoDB versions 2.6 and higher (including 3.0 and higher), or args2_4, for versions 2.4 and earlier. The field contains a MongoDB configuration object in the format appropriate to the version. For information on format and supported MongoDB options, see supported configuration options.
processes.disabled Boolean Optional. Set to true to shut down the process.
processes.manualMode Boolean Optional. Set to true to operate this process in manual mode. The Automation Agent will take no actions on the process.
processes.hostname string The name of the host this process should run on. This defaults to localhost.
processes.authSchemaVersion integer The schema version of the user credentials for MongoDB database users. This should match all other elements of the processes array that belong to the same cluster. The possible values are 3 and 5. The default is 5 for MongodDB 3.x clusters and 3 for MongoDB 2.6 clusters. See Upgrade to SCRAM-SHA-1 in the MongoDB 3.0 release notes for more information.
processes.featureCompatibilityVersion string Enables MongoDB 3.4 features that are not backwards compatible with MongDB 3.2. Valid values are “3.2” and “3.4”. New deployments of MongoDB 3.4 automatically set the value of this field to “3.4”. However, upgrading a host from 3.2 to 3.4 does not automatically add the field with a value of 3.4. See the setFeatureCompatibilityVersion reference for more information about behavior and affected features.
processes.cluster string Optional. Required for a mongos. The name of the cluster. This must correspond to the sharding.name field in the sharding array for the mongos.
processes.numCores integer Optional. The number of cores the process should be bound to. The Automation Agent will spread processes out across the cores as evenly as possible.
processes.logRotate object Optional. Enables log rotation for the MongoDB logs for a process.
processes.logRotate.sizeThresholdMB number The maximum size in MB for an individual log file before rotation. The file rotates immediately if the file meets either this sizeThresholdMB or the processes.logRotate.timeThresholdHrs limit.
processes.logRotate.timeThresholdHrs integer

The maximum time in hours for an individual log file before the next rotation. The time is since the last rotation.

The log file rotates immediately if the file meets either this timeThresholdHrs or the processes.logRotate.sizeThresholdMB limit.

processes.logRotate.numUncompressed integer Optional. The maximum number of total log files to leave uncompressed, including the current log file. The default is 5.
processes.logRotate.percentOfDiskspace number

Optional. The maximum percentage of total disk space that can be used to store the log files. If this limit is exceeded, the compressed log files are deleted to meet this limit, starting with the oldest log files first.

The default is .02.

processes.alias string Optional. A hostname alias (often a DNS CNAME) for the server on which the process runs. If an alias is specified, the Automation Agent prefers the alias over the host specified in processes.hostname when connecting to the server. You can also specify this alias in replicaSets.host and sharding.configServer.
processes.backupRestoreUrl string Optional. This is used only when creating a restore and specifies the delivery url for the restore. See Automate Backup Restoration through the API.

Replica Sets

The replicaSets array defines each replica set’s configuration. This field is required for deployments with replica sets.

"replicaSets" : [
    {
        "_id" : <string>,
        "version" : <integer>
        "members" : [
            {
                "_id" : <integer>,
                "host" : <string>
            },
            ...
        ],
        "force" : {
            "currentVersion" : <integer>
        }
    },
    ...
]
Name Type Description
replicaSets array of objects Optional. Objects that define the configuration of each replica set. The Automation Agent uses the values in this array to create valid replica set configuration documents. The agent regularly checks that replica sets are configured correctly. If a problem occurs, the agent reconfigures the replica set according to its configuration document. The array can contain the following top-level fields from a replica set configuration document: _id; version; and members. For more information on the configuration documents, see replSetGetConfig in the MongoDB manual.
replicaSets._id string The name of the replica set.
replicaSets.version integer The version of the replica set configuration.
replicaSets.members array of objects Objects that define each member of the replica set. The members.host field must specify the host’s name as listed in processes.name. The Automation Agent expands the host field to create a valid replica set configuration. For more information on members objects, see replSetGetConfig in the MongoDB manual.
replicaSets.force object Optional. An object that contains the currentVersion field set to a version number. Automation will force a reconfiguration of the replica set if and only if the value of currentVersion equals the current version of the replica set. You can use force to reconfigure a replica set that has lost members and can’t reach a majority of votes.

Sharded Clusters

The sharding array defines the configuration of each sharded cluster. This field is required for deployments with sharded clusters.

"sharding" : [
    {
        "managedSharding" : <boolean>,
        "name" : <string>,
        "configServerReplicaSet" : <string>,
        // "configServerReplicaSet" applies if the config server is a replica set.
        // For legacy mirrored config servers, use "configServer", which takes a
        // string array.
        "collections" : [
            {
                "_id" : <string>,
                "key" : [
                    [ shard key ],
                    [ shard key ],
                    ...
                ],
                "unique" : <boolean>
            },
            ...
        ],
        "shards" : [
            {
                "_id" : <string>,
                "rs" : <string>,
                "tags" : [ <string>, ... ]
            },
            ...
        ],
        "tags" : [
            {
                "ns" : <string>,
                "min" : [
                    {
                        "field" : <string>,
                        "fieldType" : <string>,
                        "value" : <string>
                    }
                ],
                "max" : [
                    {
                        "field" : <string>,
                        "fieldType" : <string>,
                        "value" : <string>
                    }
                ],
                "tag" : <string>
            },
            ...
        ]
    },
    ...
]
Name Type Description
sharding array of objects Optional. Objects that define the configuration of each sharded cluster. Each object in the array contains the specifications for one cluster. The Automation Agent regularly checks each cluster’s state against the specifications. If the specification and cluster don’t match, the agent will change the configuration of the cluster, which might cause the balancer to migrate chunks.
sharding.managedSharding boolean If true, Ops Manager Automation manages all sharded collections and tags (i.e., zones) in the deployment.
sharding.name string The name of the cluster. This must correspond with the value in processes.cluster for a mongos.
sharding.configServerReplica string

The name of the config server’s replica set.

Use this field only for a config server that is a replica set. If you use legacy mirrored config servers (config servers that are not a replica set), use sharding.configServer.

sharding.configServer array of strings

For legacy mirrored config servers, an array that contains the names of the config server hosts. The host names are the same names used in each host’s processes.name field.

Use this field only for legacy mirrored config servers (config servers that are not a replica set), which are available only with MongoDB 3.2 and earlier. Otherwise use sharding.configServerReplica.

Important

MongoDB 3.4 removes support for mirrored config servers.

sharding.collections array of objects Objects that define the sharded collections and their shard keys.
sharding.collections._id string The namespace of the sharded collection. The namespace is the combination of the database name and the name of the collection. For example, testdb.testcoll.
sharding.collections.key array of arrays The collection’s shard keys. This “array of arrays” contains a single array if there is a single shard key and contains multiple arrays if there is a compound shard key.
sharding.collections.unique boolean If set to true, MongoDB enforces uniqueness for the shard key. For more information, see the sh.shardCollection() method in the MongoDB manual.
sharding.shards array of objects Objects that define the cluster’s shards.
sharding.shards._id string The name of the shard.
sharding.shards.rs string The name of the shard’s replica set, as specified in the replicaSets._id field.
sharding.shards.tags array of strings If you use zoned sharding, the zones assigned to the shard.
sharding.tags array of objects If you use zoned sharding, this array defines the zones. Each object in this array defines a zone and configures the shard key range for that zone.
sharding.tags.ns string The namespace of the collection that uses zoned sharding. The namespace is the combination of the database name and the name of the collection. For example, testdb.testcoll.
sharding.tags.min array

The minimum value of the shard key range.

Specify the field name, field type, and value in a document of the following form.

{
  "field" : <string>,
  "fieldType" : <string>,
  "value" : <string>
}

fieldType must be one of the following:

  • string
  • integer
  • long
  • double
  • decimal
  • date
  • timestamp
  • oid
  • minKey
  • maxKey

value must be passed in as a string value.

To use a compound shard key, specify each field in a separate document, as shown in the example after this table. For more information on shard keys, see Shard Keys in the MongoDB manual.

sharding.tags.max array

The maximum value of the shard key range.

Specify the field name, field type, and value in a document of the following form.

{
  "field" : <string>,
  "fieldType" : <string>,
  "value" : <string>
}

fieldType must be one of the following:

  • string
  • integer
  • long
  • double
  • decimal
  • date
  • timestamp
  • oid
  • minKey
  • maxKey

value must be passed in as a string value.

To use a compound shard key, specify each field in a separate document, as shown in the example after this table. For more information on shard keys, see Shard Keys in the MongoDB manual.

sharding.tags.tag string The name of the zone associated with the shard key range specified by sharding.tags.min and sharding.tags.max.

Example

The sharding.tags Array with Compound Shard Key

The following example configuration defines a compound shard key range with a min value of { a : 1, b : ab } and a max value of { a : 100, b : fg }. The example defines the range on the testdb.test1 collection and assigns it to zone zone1.

"tags" : [
    {
        "ns" : "testdb.test1",
        "min" : [
            {
                "field" : "a",
                "fieldType" : "integer",
                "value" : "1"
            },
            {
                "field" : "b",
                "fieldType" : "string",
                "value" : "ab"
            }
        ],
        "max" : [
            {
                "field" : "a",
                "fieldType" : "integer",
                "value" : "100"
            },
            {
                "field" : "b",
                "fieldType" : "string",
                "value" : "fg"
            }
        ],
        "tag" : "zone1"
    }
]

Cluster Balancer

The balancer object is optional and defines balancer settings for each cluster.

"balancer": {
    "<clusterName1>": <object>,
    "<clusterName2>": <object>,
    ...
}
Name Type Description
balancer object Optional. This object contains fields named according to clusters, each field containing an object with the desired balancer settings for the cluster. The object uses the stopped and activeWindow fields, as described in the procedure to schedule the balancing window in this tutorial in the MongoDB manual.

Authentication

The auth object is optional and defines authentication-related settings.

"auth" : {
    "autoUser": <string>,
    "autoPwd": <string>,
    "disabled": <Boolean>,
    "deploymentAuthMechanisms": [ <string>, <string>, ... ],
    "key" : <string>,
    "keyfile" : <string>,
    "usersDeleted" : [
        {
            "user" : <string>,
            "dbs" : [ <string>, ... ]
        }
    ],
    "usersWanted" : [
        {
            "db" : <string>,
            "user" : <string>,
            "roles" : [ <string>, ... ],
            "pwd" : <32-character hex string>,
            "initPwd" : <string>,
            "userSource" : <string>,
            "otherDBRoles" : {
                <string> : [ <string>, ... ]
            }
        }
    ]
}
Name Type Description
auth object Optional. Defines authentication-related settings.
auth.autoUser string The username that the Automation agent uses when connecting to an instance.
auth.autoPwd string The password that the Automation agent uses when connecting to an instance.
auth.disabled Boolean Specifies whether authentication is enabled or disabled. Set to true to disable authentication, or false to enable authentication.
auth.deploymentAuthMechanisms array

Lists the supported authentication mechanisms for the processes in the deployment. Specify:

Value Authentication Mechanism
MONGODB-CR MONGODB-CR / SCRAM-SHA-1
MONGODB-X509 x.509 Client Certificate
PLAIN LDAP
GSSAPI Kerberos
auth.disabled boolean Optional. Indicates if auth is disabled. If not specified, disabled defaults to false.
auth.key string

The contents of the key file that Ops Manager uses to authenticate to the MongoDB processes. The key is not required if auth.disabled is true.

Note

If you change the auth.key value, you must change the auth.keyfile value.

auth.keyfile string

The path and name of the key file that Ops Manager uses to authenticate to the MongoDB processes. The keyfile is not required if auth.disabled is true.

Note

If you change the auth.keyfile value, you must change the auth.key value.

auth.usersDeleted array of objects Optional. Objects that define the authenticated users to be deleted from specified databases or from all databases. This array must contain two fields: the auth.usersDeleted.user field and the auth.usersDeleted.dbs field.
auth.usersDeleted.user string The user’s name.
auth.usersDeleted.dbs array String values that list the names of the databases from which the authenticated user is to be deleted.
auth.usersWanted array of objects Optional. Contains objects that define authenticated users to add to specified databases. Each object must have the auth.usersWanted.db, auth.usersWanted.user, and auth.usersWanted.roles fields, and then have exactly one of the following fields: auth.usersWanted.pwd, auth.usersWanted.initPwd, or auth.usersWanted.userSource.
auth.usersWanted.db string The database to which to add the user.
auth.usersWanted.user string The name of the user.
auth.usersWanted.roles array String values that list the roles to be assigned the user from the user’s database, which is specified in auth.usersWanted.db.
auth.usersWanted.pwd 32-character hex string The MONGODB-CR hash of the password assigned to the user. If you set this field, do not set the auth.usersWanted.initPwd or auth.usersWanted.userSource fields.
auth.usersWanted.initPwd string An initial cleartext password assigned to the user. If you set this field, do not set the auth.usersWanted.pwd or auth.usersWanted.userSource fields.
auth.usersWanted.userSource string If you use MongoDB version 2.4, you can use this field to specify the database that contains the user’s credentials. See the Privilege Documents page in the MongoDB 2.4 manual. If you set this field, do not set the auth.usersWanted.pwd or auth.usersWanted.initPwd fields.
auth.usersWanted.otherDBRoles object Optional. If the auth.usersWanted.db field specifies admin as the user’s database, then this object can assign to the user roles from other databases as well. The object contains key-value pairs where the key is the name of the database and the value is an array of string values that list the roles be assigned from that database.

SSL

The ssl object is optional and enables SSL for encrypting connections.

"ssl" : {
    "CAFilePath" : <string>
}
Name Type Description
ssl object

Optional. Enables SSL for encrypting connections. To use SSL, be sure to choose a package that supports SSL.

Starting in MongoDB 3.0, most MongoDB distributions now include support for SSL.

All MongoDB Enterprise supported platforms include SSL support.

ssl.CAFilePath string The path to the certificate used to authenticate through SSL.

MongoDB Roles

The roles array is optional and describes user-defined roles.

"roles" : [
    {
        "role" : <string>,
        "db" : <string>,
        "privileges" : [
            {
                "resource" : { ... },
                "actions" : [ <string>, ... ]
            },
            ...
        ],
        "roles" : [
            {
                "role" : <string>,
                "db" : <string>
            }
        ]

    },
    ...
]
Name Type Description
roles array of objects Optional. The roles array contains objects that describe the cluster’s user-defined roles. Each object describes a different user-defined role. Objects in this array contain the same fields as documents in the :manual:` system roles collection </reference/system-roles-collection>`, except for the _id field, which is not included here.

Kerberos

The kerberos object is optional and defines a kerberos service name used in authentication.

"kerberos": {
    "serviceName": <string>
}
Name Type Description
kerberos object Optional. A key-value pair that defines the kerberos service name agents use to authenticate via kerberos.
kerberos.serviceName string The service name agents use to authenticate to a mongod or mongos via kerberos. This name is also used to set the saslServiceName option in a MongoDB configuration, as described on the MongoDB Server Parameters page in the MongoDB manual.

Indexes

The indexConfigs array is optional and defines indexes to be built for specific replica sets.

"indexConfigs" : [
    {
        "key" : [
            [ <string> , <val> ],
            ...
        ],
        "rsName" : <string>,
        "dbName" : <string>,
        "collectionName" : <string>
        "collation" : {
            locale : <string>,
            caseLevel : <boolean>,
            caseFirst : <string>,
            strength : <number>,
            numericOrdering : <boolean>,
            alternate : <string>,
            maxVariable : <string>,
            normalization : <boolean>,
            backwards : <boolean>
        },
        "options" : { <key> : <value>, ... }
    },
    ...
]
Name Type Description
indexConfigs array of objects Optional. Objects that define specific indexes to be built for specific replica sets.
indexConfigs.key array of arrays The index’s keys. This “array of arrays” contains a single array if the index has just one key.
indexConfigs.rsName string The replica set that the index is built on.
indexConfigs.dbName string The database the index applies to.
indexConfigs.collectionName string The collection the index applies to.
indexConfigs.collation object

Optional. If the index uses collation (available beginning with MongoDB 3.4), this specifies the language-specific rules to use when sorting and matching strings.

If you specify the indexConfigs.collation object, you must specify the indexConfigs.collation.locale field. All other fields are optional.

If you do not specify the indexConfigs.collation object, the index will not include collation.

indexConfigs.collation.locale string The ICU locale. For a list of supported locales, see Collation Locales and Default Parameters in the MongoDB manual. To specify simple binary comparison, specify a value of simple.
indexConfigs.collation.caseLevel boolean Optional. If set to true, the index uses case comparison. This field applies only if the strength level is set to 1 or 2. See Collation in the MongoDB manual for details.
indexConfigs.collation.caseFirst string Optional. Determines the sort order of case differences during tertiary level comparisons. For possible values, see Collation in the MongoDB manual.
indexConfigs.collation.strength number Optional. The level of comparison to perform. Corresponds to ICU Comparison Levels. For possible values, see Collation in the MongoDB manual.
indexConfigs.collation.numericOrdering boolean

Optional. If set to true, collation compares numeric strings as numbers; i.e. 10 is greater than 2. If false, collation compares numeric strings as strings; i.e. 10 is less than 2.

The default is false. See Collation in the MongoDB manual for more information.

indexConfigs.collation.alternate string Optional. Determines whether collation should consider whitespace and punctuation as base characters during comparisons. For possible values, see Collation in the MongoDB manual.
indexConfigs.collation.maxVariable string Optional. Determines which characters are are considered ignorable. This field applies only if indexConfigs.collation.alternate is set to shifted. For possible values, see Collation in the MongoDB manual.
indexConfigs.collation.normalization boolean

Optional. If true, collation checks if text requires normalization and performs normalization to compare text.

The default is false. See Collation in the MongoDB manual for more information.

indexConfigs.collation.backwards boolean

Optional. If true, strings with diacritics sort from the back to the front of the string.

The default is false. See Collation in the MongoDB manual for more information.

indexConfigs.options document The index options. Currently supports only those options supported by the mgo driver.

Examples

Get the Automation Configuration

Request

curl -u "{username}:{apiKey}" --digest -i "https://{opsManagerHost}:{port}/api/public/v1.0/groups/533c5895b91030606f21033a/automationConfig"

Response

HTTP/1.1 200 OK
{
  <automation configuration>
}

Update the Automation Configuration

Request

The following replaces the automation configuration with the updated configuration saved in Users/admin/updated-conf.json. For an example of an updated configuration document, see Example Automation Configuration.

curl -u "{username}:{apiKey}" -H "Content-Type: application/json" --digest -i -X PUT "https://{opsManagerHost}:{port}/api/public/v1.0/groups/533c5895b91030606f21033a/automationConfig" --data @/Users/admin/updated-conf.json

Response

HTTP/1.1 200 OK
{}

Example Automation Configuration

The following is an example entity passed through the --data @<configuration> option. The exact fields included in an automation configuration depend on the Ops Manager group.

The example uses ... when a field has multiple entries and also in place of some field values. For detailed information on a field, see the Automation Configuration Entity section on this page.

{
  "options" : {
    "downloadBase" : "/var/lib/mongodb-mms-automation",
    "downloadBaseWindows" : "C :\\MMSAutomation\\versions"
  },
  "mongoDbVersions" : [
    {
      "name" : "3.2.0",
      "builds" : [
        {
          "platform" : "windows",
          "url" : "https ://fastdl.mongodb.org/win32/mongodb-win32-x86_64-2008plus-3.2.0.zip",
          "gitVersion" : "45d947729a0315accb6d4f15a6b06be6d9c19fe7",
          "architecture" : "amd64",
          "bits" : 64,
          "win2008plus" : true
        },
        ...
      ],
    },
    ...
  ],
  "agentVersion" : {
  "directoryUrl" : "https://s3.amazonaws.com/mongodb-mms-build-agent/releases/prod/",
  "name" : "2.6.4.1612-1"
  },
  "monitoringVersions" : [
    {
      "name" : "4.1.0.251-1",
      "hostname" : "example.net",
      "baseUrl" : null
    },
    ...
  ],
  "backupVersions" : [
    {
      "name" : "4.1.0.347-1",
      "hostname" : "example.net",
      "baseUrl" : null
    },
    ...
  ],
  "processes" : [
    {
      "name" : "MyCLUSTER_MySHARD_0_0",
      "processType" : "mongod",
      "version" : "2.6.7",
      "hostname" : "testAutoAPI-0.dns.placeholder",
      "logRotate" : {
        "sizeThresholdMB" : 1000,
        "timeThresholdHrs" : 24
      },
      "authSchemaVersion" : 1,
      "args2_6" : {
        "net" : {
          "port" : 27017
        },
        "storage" : {
          "dbPath" : "/data/MyCLUSTER_MySHARD_0_0"
        },
        "systemLog" : {
          "path" : "/data/MyCLUSTER_MySHARD_0_0/mongodb.log",
          "destination" : "file"
        },
        "replication" : {
          "replSetName" : "MySHARD_0"
        },
        "operationProfiling" : {}
      }
    },
    ...
  ],
  "replicaSets" : [
    {
      "_id" : "MySHARD_0",
      "members" : [
        {
          "_id" : 0,
          "host" : "MyCLUSTER_MySHARD_0_0",
          "priority" : 1,
          "votes" : 1,
          "slaveDelay" : 0,
          "hidden" : false,
          "arbiterOnly" : false
        },
        {
          "_id" : 1,
          "host" : "MyCLUSTER_MySHARD_0_1",
          "priority" : 1,
          "votes" : 1,
          "slaveDelay" : 0,
          "hidden" : false,
          "arbiterOnly" : false
        },
        {
          "_id" : 2,
          "host" : "MyCLUSTER_MySHARD_0_2",
          "priority" : 1,
          "votes" : 1,
          "slaveDelay" : 0,
          "hidden" : false,
          "arbiterOnly" : false
        }
      ]
    },
    ...
  ],
  "sharding" : [
    {
      "name" : "myShardedCluster",
      "configServer" : [
        "MyCLUSTER_MyCONFIG_SERVER_6",
        "MyCLUSTER_MyCONFIG_SERVER_7",
        "MyCLUSTER_MyCONFIG_SERVER_8"
      ],
      "shards" : [
        {
          "_id" : "MySHARD_0",
          "rs" : "MySHARD_0"
        },
        {
          "_id" : "MySHARD_1",
          "rs" : "MySHARD_1"
        }
      ]
    }
  ],
  "balancer" : { ... },
  "auth" : {
    "authoritativeSet" : false,
    "disabled" : true
    "usersDeleted" : [ ],
    "usersWanted" : [ ]
  },
  "ssl" : { ... },
  "roles" : [
    {
      "role" : ... ,
      "db" : ... ,
      "privileges" : [ ... ],
      "roles" : [ ... ]
    },
    ...
  ],
  "kerberos" : {
    "serviceName" : ...
  },
  "indexConfigs" : [ ]
}

Update the Monitoring Agent

Request

curl -u "{username}:{apiKey}" -H "Content-Type: application/json" --digest -i -X PUT https://{opsManagerHost}:{port}/api/public/v1.0/groups/533c5895b91030606f21033a/automationConfig/monitoringAgentConfig --data '
{
  "logPath": "/var/log/mongodb-mms-automation/monitoring-agent.log",
  "logRotate": {
    "sizeThresholdMB": 1000,
    "timeThresholdHrs": 12
  }
}'

Response

HTTP/1.1 200 OK
{}

Update the Backup Agent

Request

curl -u "{username}:{apiKey}" -H "Content-Type: application/json" --digest -i -X PUT https://{opsManagerHost}:{port}/api/public/v1.0/groups/533c5895b91030606f21033a/automationConfig/backupAgentConfig --data '
{
  "logPath": "/var/log/mongodb-mms-automation/backup-agent.log",
  "logRotate": {
    "sizeThresholdMB": 1000,
    "timeThresholdHrs": 36
  }
}'

Response

HTTP/1.1 200 OK
{}