Hosts¶

On this page

Overview
Endpoints
Sample Entity
Entity Fields
Links
Examples

Overview¶

You can typically access a host using a variety of names. DNS records and entries in the /etc/hosts file determine what names you can use to access a given host.

When you add a host to Ops Manager, Ops Manager automatically discovers various valid hostname and port combinations for each monitored mongod and mongos process. Ops Manager then ranks the hostnames to choose a “primary” hostname. Hostnames with the most periods are ranked highest, while the loopback address (127.0.0.1) and localhost lowest. Ops Manager treats the “losing” hostnames as host aliases.

When Ops Manager processes a ping from the Monitoring agent, the algorithm for assigning a primary hostname repeats. As a result, the primary hostname may change over time. You can also specify preferred hostnames in Ops Manager’s group settings to override the hostname algorithm.

Endpoints¶

Get All Hosts in a Group¶

Get all hosts in a group. Use the clusterId query parameter to only get the hosts that belong to the specified cluster. The resulting list is sorted alphabetically by hostname:port.

copy

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

Get a Host by ID¶

copy

GET /api/public/v1.0/groups/GROUP-ID/hosts/HOST-ID

Get a Host By Name and Port¶

Get a single host by its hostname and port combination. You can specify either the primary hostname or an alias.

copy

GET /api/public/v1.0/groups/GROUP-ID/hosts/byName/HOSTNAME:PORT

Create a Host¶

Create a new host in the group. When you create a new host, Ops Manager only knows the information that you provided. Thus, the document returned in the response document will include blank values while Ops Manager discovers the missing values.

copy

POST /api/public/v1.0/groups/GROUP-ID/hosts

You may specify the following fields when creating a host:

hostname - Required.
port - Required.
username - Required if authMechanismName is MONGODB_CR. Otherwise illegal.
password - Required if authMechanismName is MONGODB_CR. Otherwise illegal.
sslEnabled - Must be true if the authMechanismName is MONGODB_X509. Default is false if omitted.
logsEnabled - Default is false if omitted.
alertsEnabled - Default is true if omitted.
profilerEnabled - Default is false if omitted.
muninPort - Default is 0 and Munin stats are not collected if omitted.
authMechanismName - Default is NONE if omitted. If set to MONGODB_CR then you must provide the username and password.

Update a Host¶

copy

PATCH /api/public/v1.0/groups/GROUP-ID/hosts/HOST-ID

You can specify the following fields:

username
password
sslEnabled
logsEnabled
alertsEnabled
profilerEnabled
muninPort
authMechanismName

If authMechanismName is NONE then any existing value for username and password will be cleared out. If authMechanismName is MONGODB_CR, then you must provide both the username and password.

Delete a Host¶

copy

DELETE /api/public/v1.0/groups/GROUP-ID/hosts/HOST-ID

Sample Entity¶

copy

{
  "id": "680ab316473d6b28f966364b947134fc",
  "groupId": "2847387cd717dabc348a",
  "hostname": "localhost",
  "port": 27017,
  "typeName": "SHARD_SECONDARY",
  "lastPing": "2014-02-15T16:03:47Z",
  "ipAddress": "127.0.0.1",
  "version": "2.4.3",
  "hasStartupWarnings": true,
  "sslEnabled": false,
  "logsEnabled": false,
  "uptimeMsec": 48918394,
  "lastRestart": "2014-01-16T12:34:01Z",
  "shardName": "sh1",
  "replicaSetName": "rs1",
  "replicaStateName": "RECOVERING",
  "created": "2013-11-05T03:04:05Z",
  "hostEnabled": true,
  "journalingEnabled": false,
  "alertsEnabled": true,
  "hidden": false,
  "muninEnabled": false,
  "profilerEnabled": false,
  "lowUlimit": false,
  "muninPort": 4949,
  "authMechanismName": "MONGODB_CR",
  "username": "mongo",
  "aliases": [ "127.0.0.1:27017" ],
  "displayName": "Newton",
  "links": [ ... ]
}

Entity Fields¶

Name	Type	Description
`id`	string	Unique identifier.
`groupId`	string	ID of the group that owns this host.
`hostname`	string	Primary hostname. A host typically has several aliases, so the primary is the best available name as decided by Ops Manager.
`port`	number	Port that MongoDB process (`mongod` or `mongos`) listens on.
`typeName`	string	Type for this host. Possible values are: `STANDALONE` `REPLICA_PRIMARY` `REPLICA_SECONDARY` `REPLICA_ARBITER` `RECOVERING` `MASTER` `SLAVE` `SHARD_MONGOS` `SHARD_CONFIG` `SHARD_STANDALONE` `SHARD_PRIMARY` `SHARD_SECONDARY` `NO_DATA` The host’s type for new hosts added to Ops Manager will be `NO_DATA` until the Monitoring Agent receives its first ping.
`lastPing`	date	When the last ping for this host was received.
`ipAddress`	string	IP address of this host.
`version`	string	Version of MongoDB running on this host.
`hasStartupWarnings`	boolean	Are there startup warnings for this host?
`sslEnabled`	boolean	Is SSL enabled for this host? Must be `true` if the `authMechanismName` is `MONGODB_X509`.
`logsEnabled`	boolean	Is Ops Manager collecting logs for this host?
`uptimeMsec`	number	Number of milliseconds since this host’s last restart.
`lastRestart`	date	Date this host was last restarted.
`shardName`	string	Name of the shard this host belongs to. Only present if the host is part of a sharded cluster.
`replicaSetName`	string	Name of the replica set this host belongs to. Only present if this host is part of a replica set.
`replicaStateName`	string	Current state of this host within a replica set. Only present if this host is part of a replica set. See Replica Set Member States for possible values.
`created`	date	Date this host was created or first discovered by Ops Manager.
`hostEnabled`	boolean	Is this host currently enabled? Hosts can be manually disabled in the Ops Manager UI.
`journalingEnabled`	boolean	Is journaling enabled for this host?
`alertsEnabled`	boolean	Are alerts enabled for this host?
`muninEnabled`	boolean	Are Munin stats being collected for this host?
`profilerEnabled`	boolean	Is Ops Manager collecting profile information from this host?
`lowUlimit`	boolean	Does this host have a low `ulimit` setting?
`muninPort`	number	What port should be used to collect Munin stats from this host?
`authMechanismName`	string	The authentication mechanism used to connect to this host. Possible values are: `MONGODB_CR` `GSSAPI` `PLAIN` `MONGODB_X509` `NONE`
`username`	string	Username for connecting to this host. Only present when the `authMechanismName` is `MONGODB_CR`.
`password`	string	Password for connecting to this host. If a host’s `authMechanismName` is `MONGODB_CR`, then you must include this field when creating the host or updating its credentials. However, it will never be exposed when a host entity is returned.
`aliases`	array of strings	A list of alternate hostname:port combinations that Ops Manager has discovered for the host.
`displayName`	string	The host’s display name in Ops Manager. If this is not set, Ops Manager displays the hostname instead. To unset this, use an empty string (`""`) as the value of this field.

Links¶

Relation	Description
`self`	Me
`http://mms.mongodb.com/cluster`	The cluster this host belongs to. Only present if the host is part of a replica set or master/slave.
`http://mms.mongodb.com/parentCluster`	The parent cluster. Only present if the host is part of a sharded cluster.
`http://mms.mongodb.com/group`	The group that this host belongs to.
`http://mms.mongodb.com/metrics`	All available metrics for the host.
`http://mms.mongodb.com/snapshots`	All snapshots for the config server. Only present if the host is a config server and if the config server is running as a standalone, not as a replica set.
`http://mms.mongodb.com/restoreJobs`	All restore jobs for the config server. Only present if the host is a config server and if the config server is running as a standalone, not as a replica set.

Examples¶

Create a New Host¶

copy

curl -u "username:apiKey" -H "Content-Type: application/json" --digest -X POST "https://cloud.mongodb.com/api/public/v1.0/groups/5196d3628d022db4cbc26d9e/hosts" --data '
{
  "hostname": "localhost",
  "port": 27017
}'

HTTP/1.1 201 Created
Location: https://cloud.mongodb.com/api/public/v1.0/groups/5196d3628d022db4cbc26d9e/hosts/680ab316473d6b28f966364b947134fc

{
  "id" : "4059580c20c4581872ef24d0b8f5dca0",
  "groupId" : "5196d3628d022db4cbc26d9e",
  "hostname" : "localhost",
  "port" : 27017,
  "hasStartupWarnings" : false,
  "sslEnabled" : false,
  "logsEnabled" : false,
  "created" : "2014-04-22T19:56:50Z",
  "hostEnabled" : true,
  "journalingEnabled" : false,
  "alertsEnabled" : true,
  "hidden" : false,
  "muninEnabled" : false,
  "profilerEnabled" : false,
  "lowUlimit" : false,
  "authMechanismName" : "NONE",
  "links" : [ ... ]
}

Update a Host¶

copy

curl -u "username:apiKey" -H "Content-Type: application/json" --digest -i -X PATCH "https://cloud.mongodb.com/api/public/v1.0/groups/533c5895b91030606f21033a/hosts/680ab316473d6b28f966364b947134fc" --data '
{
  "sslEnabled": true,
  "username": "mongo",
  "password": "M0ng0DB!:)"
}'

HTTP/1.1 200 OK

{
  "id" : "680ab316473d6b28f966364b947134fc",
  "groupId" : "533c5895b91030606f21033a",
  "hostname" : "localhost",
  "port" : 26000,
  "hasStartupWarnings" : false,
  "sslEnabled" : true,
  "logsEnabled" : false,
  "created" : "2014-04-22T19:56:50Z",
  "hostEnabled" : true,
  "journalingEnabled" : false,
  "alertsEnabled" : true,
  "hidden" : false,
  "muninEnabled" : false,
  "profilerEnabled" : false,
  "lowUlimit" : false,
  "authMechanismName" : "MONGODB_CR",
  "username" : "mongo",
  "links" : [ ... ]
}

Get One Host¶

copy

curl -u "username:apiKey" --digest -i "https://cloud.mongodb.com/api/public/v1.0/groups/533c5895b91030606f21033a/hosts/56e9378f601dc49360a40949c8a6df6c"

HTTP/1.1 200 OK

{
  "id" : "56e9378f601dc49360a40949c8a6df6c",
  "groupId" : "533c5895b91030606f21033a",
  "hostname" : "mymongo.test.com",
  "port" : 26000,
  "hasStartupWarnings" : false,
  "sslEnabled" : true,
  "logsEnabled" : false,
  "created" : "2014-04-22T19:56:50Z",
  "hostEnabled" : true,
  "journalingEnabled" : false,
  "alertsEnabled" : true,
  "hidden" : false,
  "muninEnabled" : false,
  "profilerEnabled" : false,
  "lowUlimit" : false,
  "authMechanismName" : "MONGODB_CR",
  "username" : "mongo",
  "aliases": [ "mymongo:26000", "12.34.56.78:26000" ],
  "displayName": "Leibniz",
  "links" : [ ... ]
}

Get All Hosts¶

copy

curl -u "username:apiKey" --digest -i "https://cloud.mongodb.com/api/public/v1.0/groups/533c5895b91030606f21033a/hosts"

HTTP/1.1 200 OK

{
  "totalCount" : 2,
  "results" : [
    {
      "id" : "56e9378f601dc49360a40949c8a6df6c",
      "groupId" : "533c5895b91030606f21033a",
      "hostname" : "mymongo.test.com",
      "port" : 26000,
      "hasStartupWarnings" : false,
      "sslEnabled" : true,
      "logsEnabled" : false,
      "created" : "2014-04-22T19:56:50Z",
      "hostEnabled" : true,
      "journalingEnabled" : false,
      "alertsEnabled" : true,
      "hidden" : false,
      "muninEnabled" : false,
      "profilerEnabled" : false,
      "lowUlimit" : false,
      "authMechanismName" : "MONGODB_CR",
      "username" : "mongo",
      "aliases": [ "mymongo:26000", "12.34.56.78:26000" ],
      "displayName": "Leibniz",
      "links" : [ ... ]
    },
    {
      ...
    }
  ]
}

Delete a Host¶

copy

curl -u "username:apiKey" --digest -i -X DELETE "https://cloud.mongodb.com/api/public/v1.0/groups/533c5895b91030606f21033a/hosts/680ab316473d6b28f966364b947134fc"

HTTP/1.1 200 OK

← Root Agents →