# REST API ` URL endpoint. `` has
to be replaced with the plural name of the object type you are interested
in:
```bash
curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/hosts'
```
A list of all available configuration types is available in the
[object types](09-object-types.md#object-types) chapter.
The following URL parameters are available:
Parameters | Type | Description
-----------|--------------|----------------------------
attrs | Array | **Optional.** Limited attribute list in the output.
joins | Array | **Optional.** Join related object types and their attributes specified as list (`?joins=host` for the entire set, or selectively by `?joins=host.name`).
meta | Array | **Optional.** Enable meta information using `?meta=used_by` (references from other objects) and/or `?meta=location` (location information) specified as list. Defaults to disabled.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) may be provided.
Instead of using a filter you can optionally specify the object name in the
URL path when querying a single object. For objects with composite names
(e.g. services) the full name (e.g. `example.localdomain!http`) must be specified:
```bash
curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/services/example.localdomain!http'
```
You can limit the output to specific attributes using the `attrs` URL parameter:
```bash
curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/hosts/example.localdomain?attrs=name&attrs=address&pretty=1'
```
```json
{
"results": [
{
"attrs": {
"name": "example.localdomain",
"address": "192.168.1.1"
},
"joins": {},
"meta": {},
"name": "example.localdomain",
"type": "Host"
}
]
}
```
#### Object Queries Result `
where the following joins are available:
Object Type | Object Relations (`joins` prefix name)
-------------|------------------------------------------
Service | host, check\_command, check\_period, event\_command, command\_endpoint
Host | check\_command, check\_period, event\_command, command\_endpoint
Notification | host, service, command, period
Dependency | child\_host, child\_service, parent\_host, parent\_service, period
User | period
Zones | parent
Here's an example that retrieves all service objects for hosts which have had their `os`
custom variable set to `Linux`. The result set contains the `display_name` and `check_command`
attributes for the service. The query also returns the host's `name` and `address` attribute
via a join:
```bash
curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/services?attrs=display_name&attrs=check_command&joins=host.name&joins=host.address&filter=host.vars.os==%22Linux%22&pretty=1'
```
```json
{
"results": [
{
"attrs": {
"check_command": "ping4",
"display_name": "ping4"
},
"joins": {
"host": {
"address": "192.168.1.1",
"name": "example.localdomain"
}
},
"meta": {},
"name": "example.localdomain!ping4",
"type": "Service"
},
{
"attrs": {
"check_command": "ssh",
"display_name": "ssh"
},
"joins": {
"host": {
"address": "192.168.1.1",
"name": "example.localdomain"
}
},
"meta": {},
"name": "example.localdomain!ssh",
"type": "Service"
}
]
}
```
> **Tip**
>
> Use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
> and pass everything in the request body like this:
```bash
curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5665/v1/objects/services' \
-d '{ "attrs": [ "display_name", "check_command" ], "joins": [ "host.name", "host.address" ], "filter": "host.vars.os==\"Linux\"", "pretty": true }'
```
In case you want to fetch all [comments](09-object-types.md#objecttype-comment)
for hosts and services, you can use the following query URL (similar example
for downtimes):
```
https://localhost:5665/v1/objects/comments?joins=host&joins=service
```
This is another example for listing all service objects which are unhandled problems (state is not OK
and no downtime or acknowledgement set). We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
here because we want to pass all query attributes in the request body.
```bash
curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \
'https://127.0.0.1:5665/v1/objects/services' \
-d '{ "joins": [ "host.name", "host.address" ], "attrs": [ "name", "state", "downtime_depth", "acknowledgement" ], "filter": "service.state != ServiceOK && service.downtime_depth == 0.0 && service.acknowledgement == 0.0", "pretty": true }'
```
```json
{
"results": [
{
"attrs": {
"acknowledgement": 0.0,
"downtime_depth": 0.0,
"name": "10807-service",
"state": 3.0
},
"joins": {
"host": {
"address": "",
"name": "10807-host"
}
},
"meta": {},
"name": "10807-host!10807-service",
"type": "Service"
}
]
}
```
In order to list all acknowledgements without expire time, you query the `/v1/objects/comments`
URL endpoint with `joins` and `filter` request parameters using the [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
method:
```bash
curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5665/v1/objects/comments' \
-d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0", "pretty": true }'
```
```json
{
"results": [
{
"attrs": {
"author": "icingaadmin",
"text": "maintenance work"
},
"joins": {
"service": {
"__name": "example.localdomain!disk /",
"acknowledgement": 1.0,
"acknowledgement_expiry": 0.0
}
},
"meta": {},
"name": "example.localdomain!disk /!example.localdomain-1495457222-0",
"type": "Comment"
}
]
}
```
### Creating Config Objects |String | **Optional.** The performance data as array of strings. The raw performance data string can be used too.
check\_command | Array|String | **Optional.** The first entry should be the check commands path, then one entry for each command line option followed by an entry for each of its argument. Alternativly a single string can be used.
check\_source | String | **Optional.** Usually the name of the `command_endpoint`
execution\_start | Timestamp | **Optional.** The timestamp where a script/process started its execution.
execution\_end | Timestamp | **Optional.** The timestamp where a script/process ended its execution. This timestamp is used in features to determine e.g. the metric timestamp.
ttl | Number | **Optional.** Time-to-live duration in seconds for this check result. The next expected check result is `now + ttl` where freshness checks are executed.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
Example for the service `passive-ping`:
```bash
curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/process-check-result' \
-d '{ "type": "Service", "filter": "host.name==\"icinga2-master1.localdomain\" && service.name==\"passive-ping\"", "exit_status": 2, "plugin_output": "PING CRITICAL - Packet loss = 100%", "performance_data": [ "rta=5000.000000ms;3000.000000;5000.000000;0.000000", "pl=100%;80;100;0" ], "check_source": "example.localdomain", "pretty": true }'
```
```json
{
"results": [
{
"code": 200.0,
"status": "Successfully processed check result for object 'icinga2-master1.localdomain!passive-ping'."
}
]
}
```
You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body.
Example for using the `Host` type and filter by the host name:
```bash
curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/process-check-result' \
-d '{ "filter": "host.name==\"example.localdomain\"", "type": "Host", "exit_status": 1, "plugin_output": "Host is not available." }'
```
> **Note**
>
> Multi-line plugin output requires the following format: The first line is treated as `short` plugin output corresponding
> to the first line of the plugin output. Subsequent lines are treated as `long` plugin output. Please note that the
> performance data is separated from the plugin output and has to be passed as `performance_data` attribute.
### reschedule-check ` URL endpoint. `` has
to be replaced with the plural name of the object type you are interested
in:
```bash
curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/templates/hosts'
```
A list of all available configuration types is available in the
[object types](09-object-types.md#object-types) chapter.
A [filter](12-icinga2-api.md#icinga2-api-filters) may be provided for this query type. The
template object can be accessed in the filter using the `tmpl` variable. In this
example the [match function](18-library-reference.md#global-functions-match) is used to
check a wildcard string pattern against `tmpl.name`.
The `filter` attribute is passed inside the request body thus requiring to use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
here.
```bash
curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5661/v1/templates/hosts' \
-d '{ "filter": "match(\"g*\", tmpl.name)" }'
```
Instead of using a filter you can optionally specify the template name in the
URL path when querying a single object:
```bash
curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/templates/hosts/generic-host'
```
The result set contains the type, name as well as the location of the template.
## Variables
```
## API Clients :5665" too.
$cert64=@"
-----BEGIN CERTIFICATE-----
MIIE5TCCAs2gAwIBAgIBAjANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDDAlJY2lu
Z2EgQ0EwHhcNMTYwNzA3MDYxOTM4WhcNMzEwNzA0MDYxOTM4WjAiMSAwHgYDVQQD
DBdpY2luZ2EuZXh0ZXJuMS56bXQuaW5mbzCCAiIwDQYJKoZIhvcNAQEBBQADggIP
ADCCAgoCggIBAJ2/ufxCb1m8PbUCxLkZqZNLxZ/vpulOcKmOGYm6VBWbOXQA50on
IewnMRUDGF9DHajLk1nyUu1TyKxGzBbja+06/kVd/8Muv0MUNF6iC1U3F3h0W9da
kk5rK1L+A534csHCFcG3dZkbdOMrh5hy4kMf9c2FEpviL54Fo4e+b3ZJFA6rv5D9
7LzaxfLcsMwXIZ/WRnxjjfnA+RenHeYLlNM8Uk3vqI6tBc1qpFzFeRWMbclFzSLN
5x+J6cuyFjVi+Vv8c6SU6W3ykw8Vvq1QQUixl9lwxqNJNsWWfGR8ycmFiv1ZYxiu
HpmuLslExZ2qxdGe/raMBEOGgVsUTDZNyTm/9TxgOa3m9cv3R0YIFUmfoBQ3d51S
wburJG2eC0ETpnt0TptwMdTfL+HYVWB71djg2Pb8R3vldnhFVpy9vyx3FyHoN7ZQ
h7+r6HK2jpwWo7/jK9ExpglVoV8vUbNYqXiA/lZGEkT3YLwTyUhqXKei3Xu2CGGR
UId6fAj6OWk9TLW+OaR9BcS74mpiTWNDlbEP+/LQnUhte8scX5cSqBzy4vpuG1G+
NGDbYcG4xn6Pc6qt/QddKU/pB/GbJv9SlHU8SjSt09oG9GtuXVjPoZX5msi3NmMy
DpAcab5Lx4MgOS/GwRLRI3IjZ3ZK+UkLvRgesSH5/JPUIgfTdr/Eg5dVAgMBAAGj
NDAyMAwGA1UdEwEB/wQCMAAwIgYDVR0RBBswGYIXaWNpbmdhLmV4dGVybjEuem10
LmluZm8wDQYJKoZIhvcNAQELBQADggIBAEpEJt35KZuvDzU/xrVaVC3ct6CHmXOh
DDj5PdwkYtO0vw9WE7aVc88Fs6uhW2BxFkLvm7TpJ6g05egtBozHYrhTEir/fPna
rVAD9wEQU6KuSayeToXlgWhKDRAAv1lrQwU4xAAdJP8faxQGc7nAwN/h0g14UTmU
LSkyJU4a+1SkEUOs2YCq9vChS3MowO+6I35e98dIA1swHLeQ/QJowspODQvi6pGX
VH8FaaqfGwhv+gMwDoAW9hB74VZXO8I3mueZUccPiJXlaojx5hpaHRNRvpdBPclA
HHLRQniEOkai2Wg2cft/wq6/fYLE/yv5ej15MNyt3Wjj41DEK5B/bvmN/chOrZlv
8rh3ek12ngVtXF+Jcmfsij8+hj/IOM6SeELtW+c0KRaPoVR7oR9o6ce/dyfiw6Hv
iQsAV6x//kytpRnUY3VAH4QTJzQ5bgz1Cwr6H+cWE2ca4MHCtPYaZnDiOv4b/Yz7
97Nrc7QPGewMl0hYeykpLP2hBJldw01NXhztuq1j38vYY38lKCN6v1INUujEUZg7
NwgfHUvJmGIE/fwLAvP7do8gf+1MGPEimsgvias5YtDtrEOz7K/oF3Qgk3sepwAz
XXlNLnJAY4p0d/sgCCFQnstQMM95X0Y6cfITzkz3HIUcNF2sbvVnn8xHi0TSH/8J
tPLHO1xOLz7N
-----END CERTIFICATE-----
"@
# register callback for comparing the certificate
function set-SSLCertificate {
param(
$Cert
)
if (-not("validateCert" -as [type])) {
add-type -TypeDefinition @"
using System.Net.Security;
using System.Security.Cryptography.X509Certificates;
public static class ValidateCert {
static X509Certificate2 MyCert;
public static bool Validate(object sender,
X509Certificate cert,
X509Chain chain,
SslPolicyErrors sslPolicyErrors) {
if (MyCert.Equals(cert)) {
return true;
} else {
return false;
}
}
public static RemoteCertificateValidationCallback GetDelegate(X509Certificate2 Cert) {
MyCert = Cert;
return new RemoteCertificateValidationCallback(ValidateCert.Validate);
}
}
"@
}
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = [validateCert]::GetDelegate($Cert)
}
# convert base64 based certificate to X509 certificate
function get-x509 {
param(
[string]
$Cert64
)
$CertBin=[System.Convert]::FromBase64String(($Cert64.Trim(" ") -replace "-.*-",""))
Write-Host ($Cert64.Trim(" ") -replace "-.*-","")
[System.Security.Cryptography.X509Certificates.X509Certificate2]$CertBin
}
# Allow TLS 1.2. Old powershell (.net) uses TLS 1.0 only. Icinga2 >2.10 needs TLS 1.2
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Ssl3,Tls,Tls11,Tls12'
$SecPass = ConvertTo-SecureString $icingaApiPassword -AsPlainText -Force
$Cred = New-Object System.Management.Automation.PSCredential($icingaApiUser, $SecPass)
$Cert = get-x509 $Cert64
set-SSLCertificate $Cert
$httpHeaders = @{
"X-HTTP-Method-Override" = "GET"
"accept" = "application/json"
}
$attrs = @( "name", "state", "last_check_result" )
$joins = @( "host.name", "host.state", "host.last_check_result")
$filter = 'match("ping*", service.name)'
$data = @{
"attrs" = $attrs
"joins" = $joins
"filter" = $filter
}
$result = Invoke-RestMethod -Uri $requestUrl -Method "POST" -Body (ConvertTo-Json -InputObject $data) -Credential $Cred -ContentType "application/json" -Headers $httpHeaders
foreach ($s in $result.results) {
Write-Host "Service " $s.attrs.name " on Host " $s.joins.host.name "State " $s.attrs.state " Output: " $s.attrs.last_check_result.output
# Debug
Write-Host "Debug: Attributes " $s.attrs | ConvertTo-Json
Write-Host "Debug: Joins Host" $s.joins.host | ConvertTo-Json
Write-Host "`n"
}
```
Run the Powershell ISE as administrator, and execute the script as you change it.
Alternatively, save the code and run it in Powershell:
```
.\icinga.ps1
```