Admin Hosts
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