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 all hosts registered in M/Monit.

Arguments

none 
curl -b ~/.mmonit/cookie \
 https://127.0.0.1:8080/api/2/admin/hosts/list

Output

totalRecords The total hosts count
inactive The number of inactive hosts
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
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 
{
    "totalRecords": 1,
    "records": [
        {
            "id": 4,
            "hostname": "myhost1",
            "ipaddr": "10.2.2.2",
            "description": "application server",
            "monitversion": "5.6",
            "status": "Active"
        }
    ]
}

get

Returns details for the given host id.

Arguments

id number required The id of the host to get 
curl -b ~/.mmonit/cookie \
 https://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
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. Initialy set by Monit
monitpassword The password used when talking to Monit. Initialy set by Monit
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
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. 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)
lastmodified The timestamp of the last message received from Monit. This attribute is automatically updated by M/Monit (read-only) 
{
    "id": 4,
    "hostname": "myhost1",
    "keepname": 0,
    "ipaddrin": "10.2.2.2",
    "ipaddrout": "",
    "portin": 2812,
    "portout": -1,
    "sslin": 1,
    "sslout": -1,
    "monitid": "a1d1601725765f10881a49d62ce685f9",
    "monituser": "monit",
    "monitpassword": "secret123",
    "description": "lorem ipsum dolores sit...",
    "status": 0,
    "skew": 3,
    "defaultskew": 3,
    "poll": 5,
    "lastmodified": 1373295008
}

update

Updates the host settings in the M/Monit database. Parametes 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 
curl -b ~/.mmonit/cookie \
 -d id=5891 \
 -d monituser=monit \
 -d monitpassword=monit \
 -d hostname=Holo%20Deck%20Controller \
 https://127.0.0.1:8080/api/2/admin/hosts/update

delete

Hosts can be deleted either by id (specific host) or in bulk by specifying an inactive number of seconds (for example to bulk delete temporary cloud/virtual hosts).

To delete a host with a given id:

Arguments

id number either id or inactive is required The id of the host to delete 
curl -b ~/.mmonit/cookie \
 -d "id=4" \
 https://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" \
 https://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 with the given network settings.

Arguments

ipaddr string required The Monit http interface IP-Address or hostname
port number required The Monit http interface port number
ssl number required The SSL flag. Possible values: 0=disable, 1=enable
monituser string required The Monit http interface username
monitpassword string required The Monit http interface password 
curl -b ~/.mmonit/cookie \
 -d ipaddr=10.1.2.3 \
 -d port=2812 \
 -d ssl=1 \
 -d monituser=aaa \
 -d monitpassword=bbb \
 https://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 \
 https://127.0.0.1:8080/api/2/admin/hosts/action