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.

Hosts

On this page

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.

Operations

  • GET /api/public/v1.0/groups/GROUP-ID/hosts - 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.
  • GET /api/public/v1.0/groups/GROUP-ID/hosts/HOST-ID - Get a single host by ID.
  • GET /api/public/v1.0/groups/GROUP-ID/hosts/byName/HOSTNAME:PORT - Get a single host by its hostname and port combination. You can specify either the primary hostname or an alias.
  • POST /api/public/v1.0/groups/GROUP-ID/hosts - Create a new host in the group. Note that after a new host is created, Ops Manager will not know much about it except what is provided. Thus, the document returned in the response will be missing many values until they are discovered, which could take several minutes. Only these fields may be specified when creating a host:
    • hostname - Required.
    • port - Required.
    • username - Required if authMechanismName is MONGODB_CR.Otherwise it’s illegal.
    • password - Required if authMechanismName is MONGODB_CR. Otherwise it’s illegal.
    • sslEnabled - 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.
  • PATCH /api/public/v1.0/groups/GROUP-ID/hosts/HOST-ID - Update an existing host using the fields provided. Unspecified fields will preserve their current values.
    • Only these fields may be specified: username password sslEnabled logsEnabled alertsEnabled profilerEnabled muninPort authMechanismName
    • If authMechanismName is NONE then any existing value for username and password will be cleared out. For MONGODB_CR you must provide both username and password.
  • DELETE /api/public/v1.0/groups/GROUP-ID/hosts/HOST-ID - Remove a host.

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",
  "deactivated": false,
  "hasStartupWarnings": true,
  "sslEnabled": false,
  "logsEnabled": false,
  "lastReactivated": "2013-12-15T09:17:23Z",
  "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" ],
  "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 integer Port that MongoDB process (mongod or mongos) listens on.
typeName enum

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.
deactivated boolean Has this host been deactivated by Ops Manager? A host will be marked as deactivated when Ops Manager hasn’t received a ping from it in several days.
hasStartupWarnings boolean Are there startup warnings for this host?
sslEnabled boolean Is SSL enabled for this host?
logsEnabled boolean Is Ops Manager collecting logs for this host?
lastReactivated date The last time this has was manually reactivated.
uptimeMsec long 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 enum 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?
hidden boolean Is this host currently hidden? When Ops Manager deactivates a host, it will also mark it as hidden.
profilerEnabled boolean Is Ops Manager collecting profile information from this host?
lowUlimit boolean Does this host have a low ulimit setting?
muninPort integer What port should be used to collect Munin stats from this host?
authMechanismName enum

The authentication mechanism used to connect to this host. Possible values are:

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

Examples

Create a New Host

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

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

{
  "id" : "4059580c20c4581872ef24d0b8f5dca0",
  "groupId" : "5196d3628d022db4cbc26d9e",
  "hostname" : "localhost",
  "port" : 27017,
  "deactivated" : false,
  "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://mms.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,
  "deactivated" : false,
  "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://mms.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,
  "deactivated" : false,
  "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" ]
  "links" : [ ... ]
}

Get All Hosts

copy 
curl -u "username:apiKey" --digest -i "https://mms.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,
      "deactivated" : false,
      "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" ]
      "links" : [ ... ]
    },
    {
      ...
    }
  ]
}

Delete a Host

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

HTTP/1.1 200 OK
←   Root Metrics  →

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