The admin/host resource can be used to manage hosts in M/Monit.

Note: A create operation is currently not supported as hosts are created automatically when Monit sends a message to M/Monit.

Available methods:

GET /api/2/admin/hosts/list The Hosts List
GET /api/2/admin/hosts/get Details for a specific host
POST /api/2/admin/hosts/update Update host settings
POST /api/2/admin/hosts/delete Delete a host/hosts
GETPOST /api/2/admin/hosts/test Test connection to a host
POST /api/2/admin/hosts/action Perform a service action

list

Returns a list of the hosts registered in M/Monit. Without arguments all hosts are returned. The hosts can be filtered by name, host group and LED, and the result can be paginated and sorted.

Arguments

hostpattern string optional Show only hosts whose name contains the specified substring. Only one hostpattern argument can be used
hostgroupid number optional Show only hosts which are member of the given hostgroupid. The argument can be used multiple times to select multiple host groups
led number optional Show only hosts with matching led. Possible values: 0=red, 1=orange, 2=green, 3=gray. The argument can be used multiple times to select multiple leds
results number optional The maximum number of hosts to return (page size). If not set, all hosts which match the selection are returned
startindex number optional The index of the first host to return in the selection, starts from 0. Default: 0
sort string optional The sort key. Possible values: "hostname", "ipaddr", "led", "status", "monitversion". Default: "hostname". Hosts with the same sort key value are sorted by host name
dir string optional The sort direction. Possible values: "asc" (ascending), "desc" (descending). Default: "asc"
curl -b ~/.mmonit/cookie \
 http://127.0.0.1:8080/api/2/admin/hosts/list

Return the first page of 15 hosts with a red or orange LED in the host group 7, sorted by the Monit version:

curl -b ~/.mmonit/cookie \
 "http://127.0.0.1:8080/api/2/admin/hosts/list?hostgroupid=7&led=0&led=1&results=15&startindex=0&sort=monitversion&dir=asc"

Output

totalRecords The total number of hosts which match the selection. If the totalRecords exceeds the pageSize value, the result is paginated
recordsReturned The number of hosts in the result set
pageSize The maximum number of hosts to return (page size)
startIndex The page index (position) in the selection
sort The sort key. Possible values: "hostname", "ipaddr", "led", "status", "monitversion"
dir The sort direction. Possible values: "asc" (ascending), "desc" (descending)
inactive The number of inactive hosts among all hosts, regardless of the hostpattern, hostgroupid and led arguments
records
id The internal id assigned by M/Monit to the host when a new entry is created
hostname Host name
ipaddr The custom IP-Address/hostname set by the user (ipaddrout) or an automatic IP-Address/hostname reported by Monit (ipaddrin) if the ipaddrout is not defined
description The host description
monitversion The Monit version
led The status LED. Possible values: 0=red, 1=orange, 2=green, 3=gray
status The host status. Possible values: "Active", "Inactive", "Ignored". The "Ignored" state is manually set by the user to suppress all events from this host. A host which stopped reporting to M/Monit is "Inactive"
{
    "records": [
        {
            "id": 4,
            "hostname": "myhost1",
            "ipaddr": "10.2.2.2",
            "description": "application server",
            "monitversion": "5.36.0",
            "led": 2,
            "status": "Active"
        }
    ],
    "pageSize": 15,
    "recordsReturned": 1,
    "totalRecords": 1,
    "startIndex": 0,
    "sort": "hostname",
    "dir": "asc",
    "inactive": 0
}

get

Returns details for the given host id.

Arguments

id number required The id of the host to get
curl -b ~/.mmonit/cookie \
 http://127.0.0.1:8080/api/2/admin/hosts/get?id=4

Output

id The internal id assigned by M/Monit to the host when a new entry is created
hostname The host name
keepname Automatic hostname updates flag. Possible values: 0=hostname is automatically updated on change, 1=hostname settings is persistent.
ipaddrin The IP-Address of the Monit http interface reported by Monit. If no ipaddrout is defined, this address is used to contact Monit. This attribute is automatically updated by Monit (read-only)
ipaddrout The optional IP-Address which overrides the automatically managed ipaddrin address
portin The port number of the Monit http interface reported by Monit. If no portout is defined, this port is used to contact Monit. This attribute is automatically updated by Monit (read-only)
portout The optional port number which overrides the automatically managed portin value. -1 if undefined
sslin The SSL flag for the Monit http interface reported by Monit. If no sslout is defined, this flag is used to enable the SSL when talking to Monit. This attribute is automatically updated by Monit (read-only). Possible values: 0=disabled, 1=enabled
sslout The optional SSL flag which overrides the automatically managed sslin value. Possible values: -1=undefined, 0=disabled, 1=enabled
monitversion The Monit version. This attribute is automatically updated by Monit (read-only)
monitid The unique ID of the Monit instance used to pair the messages with the host entry (read-only)
monituser The username used when talking to Monit.
monitpassword "........" if a password for talking to Monit is set, otherwise empty: the password is not returned. An update with "........" keeps the stored one
description The optional user-defined description of the host
status The host status. Possible values: 0=Active, 1=Inactive, 2=Ignored. The "Ignored" state is manually set by the user to suppress all events from this host
led The status LED. Possible values: 0=red, 1=orange, 2=green, 3=gray
skew Monit has to send the status update within a certain timeframe. The skew specifies the number of Monit cycles M/Monit will wait before reporting the Host as down, at most maxreportlimit seconds. The default value is 3 Monit poll cycles
defaultskew The default skew (cycles)
poll The Monit poll time (cycle length) [seconds]. This attribute is automatically updated by Monit (read-only)
reportlimit How long M/Monit waits for a status update before reporting the Host as down [seconds]: poll times skew, at most maxreportlimit (read-only)
maxreportlimit The longest M/Monit waits for a status update [seconds]: 3600 (one hour), or for Monit before 6.0.0, which sends a status update once per poll cycle, two poll cycles if that is longer (read-only)
lastmodified The timestamp of the last message received from Monit. This attribute is automatically updated by M/Monit (read-only)
created_at The timestamp when the host was created in M/Monit, by the first message from Monit (read-only)
{
    "id": 4,
    "hostname": "myhost1",
    "keepname": 0,
    "ipaddrin": "10.2.2.2",
    "ipaddrout": "",
    "portin": 2812,
    "portout": -1,
    "sslin": 1,
    "sslout": -1,
    "monitversion": "5.36.0",
    "monitid": "a1d1601725765f10881a49d62ce685f9",
    "monituser": "monit",
    "monitpassword": "........",
    "description": "lorem ipsum dolores sit...",
    "status": 0,
    "led": 2,
    "skew": 3,
    "defaultskew": 3,
    "poll": 5,
    "reportlimit": 15,
    "maxreportlimit": 3600,
    "lastmodified": 1373295008,
    "created_at": 1370044800
}

update

Updates the host settings in the M/Monit database. Parameters with space in them must be URL encoded (space=%20) as curl won’t do this

Arguments

id number required The id of the host to update
hostname string required The host name
keepname number optional Automatic hostname updates flag. Possible values: 0=hostname is automatically updated on change, 1=hostname settings is persistent.
description string optional The host description
status number optional The host status. Possible values: 0=Active, 1=Inactive, 2=Ignored. The "Ignored" state is manually set by user to suppress all events from this host
ipaddrout string optional The optional IP-Address which overrides the automatically managed ipaddrin address
portout number optional The optional port number which overrides the automatically managed portin value. -1 if undefined
sslout number optional The optional SSL flag which overrides the automatically managed sslin value. Possible values: -1=undefined, 0=disabled, 1=enabled
monituser string required The username used when talking to Monit
monitpassword string required The password used when talking to Monit
skew number optional Monit has to send the status update within a certain timeframe. The skew specifies the number of Monit cycles M/Monit will wait before reporting the Host as down, at most maxreportlimit seconds (see get). If the skew is missing, below 1, or gives the Host the same reportlimit as the default skew, the Host gets the default skew and follows changes to it
curl -b ~/.mmonit/cookie \
 -d id=5891 \
 -d monituser=monit \
 -d monitpassword=monit \
 -d hostname=Holo%20Deck%20Controller \
 http://127.0.0.1:8080/api/2/admin/hosts/update

delete

Hosts can be deleted either by id (specific host), in bulk by specifying an inactive number of seconds (for example to bulk delete temporary cloud/virtual hosts), or in bulk by a filter (all hosts which the list method returns with the same hostpattern, hostgroupid and led arguments). One of id, inactive or a filter argument is required.

To delete a host with a given id:

Arguments

id number required The id of the host to delete
curl -b ~/.mmonit/cookie \
 -d "id=4" \
 http://127.0.0.1:8080/api/2/admin/hosts/delete

Delete all hosts that are inactive for the given number of seconds. With inactive hosts we mean both hosts where Monit has been gracefully shutdown or hosts that have been turned-off and now reports a heart-beat failure to M/Monit (because Monit was not gracefully stopped). Such hosts are typical virtual host which you spin-up in the cloud with Monit installed and then take down later. In this example we delete all hosts which have been inactive for the past 24 hours (= 86400 seconds)

Arguments

inactive number required Delete all hosts that are inactive for the given number of seconds
curl -b ~/.mmonit/cookie \
 -d "inactive=86400" \
 http://127.0.0.1:8080/api/2/admin/hosts/delete

Delete all hosts which match a filter, as the list method selects them. The filter arguments can be combined; at least one of them must be set to a non-empty value. Note that all matching hosts are deleted, not just one page of the list.

Arguments

hostpattern string optional Delete only hosts whose name contains the specified substring
hostgroupid number optional Delete only hosts which are member of the given hostgroupid. The argument can be used multiple times to select multiple host groups
led number optional Delete only hosts with matching led. Possible values: 0=red, 1=orange, 2=green, 3=gray. The argument can be used multiple times to select multiple leds
curl -b ~/.mmonit/cookie \
 -d "hostpattern=test-vm" \
 -d "led=0" \
 http://127.0.0.1:8080/api/2/admin/hosts/delete

Output

deleted Number of deleted hosts
{
    "deleted": 2
}

test

Checks that M/Monit can connect to the host.

Arguments

id number required The M/Monit hostid to test.
curl -b ~/.mmonit/cookie \
 -d id=7352 \
 http://127.0.0.1:8080/api/2/admin/hosts/test

Output

status The connection status. Possible values: green=OK, red=error
description The description of the connection test result
{
    "status": "green",
    "description": "Connection to Monit OK"
}

action

Performs the specified action for the selected host services.

Arguments

id number required The host id
action string required The action. Possible values: "start", "stop", "restart", "monitor", "unmonitor"
service string required The service name. The argument can be used multiple times to perform the action for several services at once
curl -b ~/.mmonit/cookie \
 -d id=185 \
 -d action=unmonitor \
 -d service=mysql \
 http://127.0.0.1:8080/api/2/admin/hosts/action