Automation¶
It is possible to issue command actions without a browser. To do so, a form needs to be submitted by a tool such as curl. This is also used in the example below.
Request Format¶
The request is required to be an Icinga Web API request. For this it is necessary to transmit the Accept HTTP header
and set it to application/json. In addition to this, the request must be authenticated using the Basic schema.
The HTTP request method is POST if not documented otherwise and it might be necessary to manually configure this
(e.g. -X POST for curl).
All endpoints support filters. To issue commands only for specific items, define a filter in the request’s query string. If this filter is omitted, all items are affected.
The options need to be transmitted in the request body as multipart/form-data.
Response Format¶
If the request succeeds, the HTTP response code is 200 and the response body contains a JSON object such as this:
{
"status": "success",
"data": [
{
"type": "success",
"message": "Added comment successfully"
}
]
}
If there’s something wrong with the options, the HTTP response code is 422 and the response body contains a JSON
object such as this:
{
"status": "fail",
"data": {
"comment": [],
"expire": [],
"expire_time": ["The expire time must not be in the past"]
}
}
Example¶
USER="icingaadmin"
PASSWORD="icinga"
BASEURL="http://localhost/icingaweb2"
FILTER="host.name=docker-master"
curl -H "Accept: application/json" -u $USER:$PASSWORD "$BASEURL/icingadb/hosts/add-comment?$FILTER" \
-F "comment=kaput" -F "expire_time=2023-10-05T20:00:00" -F "expire=y"
USER="icingaadmin"
PASSWORD="icinga"
BASEURL="http://localhost/icingaweb2"
FILTER="host.name=docker-master"
curl -H "Accept: application/json" -u $USER:$PASSWORD -X POST "$BASEURL/icingadb/hosts/delete-comment?$FILTER"
Option Types¶
Text¶
A simple text message. May contain newlines.
Number¶
An integer value.
BoolEnum¶
A string with the value of y for true and n for false.
DateTime¶
A date time string in the following format: Y-m-d\TH:i:s
The timezone this is interpreted in depends on the user who’s transmitting the request. To change this, log in as this user and change its preference setting.
State¶
| Value | Description | Applicable To |
|---|---|---|
| 0 | UP / OK | Host / Service |
| 1 | DOWN / WARNING | Host / Service |
| 2 | CRITICAL | Service |
| 3 | UNKNOWN | Service |
PerfData¶
Please have a look at the Monitoring Plugins Development Guidelines.
ChildOption¶
| Value | Description |
|---|---|
| 0 | Do nothing with child hosts |
| 1 | Schedule triggered downtime for all child hosts |
| 2 | Schedule non-triggered downtime for all child hosts |
Endpoints¶
Info
Some of the endpoints support configuration options. These are explained in the Configuration section.
Acknowledge Problem¶
Routes¶
- icingadb/hosts/acknowledge
- icingadb/services/acknowledge
Options¶
| Option | Required | Type | Depends On | Default | Configuration Option |
|---|---|---|---|---|---|
| comment | y | Text | - | - | acknowledge_comment_text |
| persistent | n | BoolEnum | - | n | acknowledge_persistent |
| notify | n | BoolEnum | - | y | acknowledge_notify |
| sticky | n | BoolEnum | - | n | acknowledge_sticky |
| expire | n | BoolEnum | - | n | acknowledge_expire |
| expire_time | y | DateTime | expire | now + 1 hour | acknowledge_expire_time |
Add Comment¶
Routes¶
- icingadb/hosts/add-comment
- icingadb/services/add-comment
Options¶
| Option | Required | Type | Depends On | Default | Configuration Option |
|---|---|---|---|---|---|
| comment | y | Text | - | - | - |
| expire | n | BoolEnum | - | n | comment_expire |
| expire_time | y | DateTime | expire | now + 1 hour | comment_expire_time |
Delete Comments¶
Routes¶
- icingadb/comments/delete
Options¶
None.
Check Now¶
Routes¶
- icingadb/hosts/check-now
- icingadb/services/check-now
Options¶
None.
Process Check Result¶
Routes¶
- icingadb/hosts/process-checkresult
- icingadb/services/process-checkresult
Options¶
| Option | Required | Type |
|---|---|---|
| status | y | State |
| output | y | Text |
| perfdata | n | PerfData |
Remove Acknowledgement¶
Routes¶
- icingadb/hosts/remove-acknowledgement
- icingadb/services/remove-acknowledgement
Options¶
None.
Schedule Check¶
Routes¶
- icingadb/hosts/schedule-check
- icingadb/services/schedule-check
Options¶
| Option | Required | Type | Default |
|---|---|---|---|
| check_time | y | DateTime | now + 1 hour |
| force_check | n | BoolEnum | - |
Schedule Host Downtime¶
Routes¶
- icingadb/hosts/schedule-downtime
Options¶
| Option | Required | Type | Depends On | Default | Configuration Option |
|---|---|---|---|---|---|
| comment | y | Text | - | - | hostdowntime_comment_text |
| start | y | DateTime | - | now | - |
| end | y | DateTime | - | now + 1 hour (fixed), now + 2 hours (flexible) | hostdowntime_end_fixed, hostdowntime_end_flexible |
| flexible | n | BoolEnum | - | n | - |
| hours | y | Number | flexible | 2 | hostdowntime_flexible_duration |
| minutes | y | Number | flexible | 0 | hostdowntime_flexible_duration |
| all_services | n | BoolEnum | - | n | hostdowntime_all_services |
| child_options | n | ChildOption | - | - | - |
Schedule Service Downtime¶
Routes¶
- icingadb/services/schedule-downtime
Options¶
| Option | Required | Type | Depends On | Default | Configuration Option |
|---|---|---|---|---|---|
| comment | y | Text | - | - | servicedowntime_comment_text |
| start | y | DateTime | - | now | - |
| end | y | DateTime | - | now + 1 hour (fixed), now + 2 hours (flexible) | servicedowntime_end_fixed, servicedowntime_end_flexible |
| flexible | n | BoolEnum | - | n | - |
| hours | y | Number | flexible | 2 | servicedowntime_flexible_duration |
| minutes | y | Number | flexible | 0 | servicedowntime_flexible_duration |
Delete Downtimes¶
Routes¶
- icingadb/downtimes/delete
Options¶
None.
Send Custom Notification¶
Routes¶
- icingadb/hosts/send-custom-notification
- icingadb/services/send-custom-notification
Options¶
| Option | Required | Type | Default | Configuration Option |
|---|---|---|---|---|
| comment | y | Text | - | - |
| forced | n | BoolEnum | n | custom_notification_forced |