1 # Icinga 2 API <a id="icinga2-api"></a>
3 ## Setting up the API <a id="icinga2-api-setup"></a>
5 You can run the CLI command `icinga2 api setup` to enable the
6 `api` [feature](11-cli-commands.md#enable-features) and set up
7 certificates as well as a new API user `root` with an auto-generated password in the
8 `/etc/icinga2/conf.d/api-users.conf` configuration file:
12 Make sure to restart Icinga 2 to enable the changes you just made:
14 # service icinga2 restart
16 If you prefer to set up the API manually, you will have to perform the following steps:
18 * Set up X.509 certificates for Icinga 2
19 * Enable the `api` feature (`icinga2 feature enable api`)
20 * Create an `ApiUser` object for authentication
22 The next chapter provides a quick overview of how you can use the API.
24 ## Introduction <a id="icinga2-api-introduction"></a>
26 The Icinga 2 API allows you to manage configuration objects
27 and resources in a simple, programmatic way using HTTP requests.
29 The URL endpoints are logically separated allowing you to easily
32 * query, create, modify and delete [config objects](12-icinga2-api.md#icinga2-api-config-objects)
33 * perform [actions](12-icinga2-api.md#icinga2-api-actions) (reschedule checks, etc.)
34 * subscribe to [event streams](12-icinga2-api.md#icinga2-api-event-streams)
35 * [manage configuration packages](12-icinga2-api.md#icinga2-api-config-management)
36 * evaluate [script expressions](12-icinga2-api.md#icinga2-api-console)
38 ### Requests <a id="icinga2-api-requests"></a>
40 Any tool capable of making HTTP requests can communicate with
41 the API, for example [curl](https://curl.haxx.se/).
43 Requests are only allowed to use the HTTPS protocol so that
44 traffic remains encrypted.
46 By default the Icinga 2 API listens on port `5665` which is shared with
47 the cluster stack. The port can be changed by setting the `bind_port` attribute
48 for the [ApiListener](09-object-types.md#objecttype-apilistener)
49 object in the `/etc/icinga2/features-available/api.conf`
52 Supported request methods:
56 GET | Retrieve information about configuration objects. Any request using the GET method is read-only and does not affect any objects.
57 POST | Update attributes of a specified configuration object.
58 PUT | Create a new object. The PUT request must include all attributes required to create a new object.
59 DELETE | Remove an object created by the API. The DELETE method is idempotent and does not require any check if the object actually exists.
61 All requests apart from `GET` require that the following `Accept` header is set:
63 Accept: application/json
65 Each URL is prefixed with the API version (currently "/v1").
67 ### Responses <a id="icinga2-api-responses"></a>
69 Successful requests will send back a response body containing a `results`
70 list. Depending on the number of affected objects in your request, the
71 `results` list may contain more than one entry.
73 The output will be sent back as a JSON object:
80 "status": "Object was created."
85 Tip: If you are working on the CLI with curl you can also use [jq](https://stedolan.github.io/jq/)
86 to format the returned JSON output in a readable manner. The documentation
87 prefers `python -m json.tool` as Python is available nearly everywhere.
91 > Future versions of Icinga 2 might set additional fields. Your application
92 > should gracefully handle fields it is not familiar with, for example by
95 ### HTTP Statuses <a id="icinga2-api-http-statuses"></a>
97 The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt)
98 including error codes.
100 When an error occurs, the response body will contain additional information
101 about the problem and its source.
103 A status code between 200 and 299 generally means that the request was
106 Return codes within the 400 range indicate that there was a problem with the
107 request. Either you did not authenticate correctly, you are missing the authorization
108 for your requested action, the requested object does not exist or the request
111 A status in the range of 500 generally means that there was a server-side problem
112 and Icinga 2 is unable to process your request.
114 ### Authentication <a id="icinga2-api-authentication"></a>
116 There are two different ways for authenticating against the Icinga 2 API:
118 * username and password using HTTP basic auth
121 In order to configure a new API user you'll need to add a new [ApiUser](09-object-types.md#objecttype-apiuser)
122 configuration object. In this example `root` will be the basic auth username
123 and the `password` attribute contains the basic auth password.
125 # vim /etc/icinga2/conf.d/api-users.conf
127 object ApiUser "root" {
131 Alternatively you can use X.509 client certificates by specifying the `client_cn`
132 the API should trust. The X.509 certificate has to be signed by the CA certificate
133 that is configured in the [ApiListener](09-object-types.md#objecttype-apilistener) object.
135 # vim /etc/icinga2/conf.d/api-users.conf
137 object ApiUser "root" {
138 client_cn = "CertificateCommonName"
141 An `ApiUser` object can have both authentication methods configured.
143 You can test authentication by sending a GET request to the API:
145 $ curl -k -s -u root:icinga 'https://localhost:5665/v1'
147 In case you get an error message make sure to check the API user credentials.
149 When using client certificates for authentication you'll need to pass your client certificate
150 and private key to the curl call:
152 $ curl -k --cert example.localdomain.crt --key example.localdomain.key 'https://example.localdomain:5665/v1/status'
154 In case of an error make sure to verify the client certificate and CA.
156 The curl parameter `-k` disables certificate verification and should therefore
157 only be used for testing. In order to securely check each connection you'll need to
158 specify the trusted CA certificate using the curl parameter`--cacert`:
160 $ curl -u root:icinga --cacert ca.crt 'icinga2.node1.localdomain:5665/v1'
162 Read the next chapter on [API permissions](12-icinga2-api.md#icinga2-api-permissions)
163 in order to configure authorization settings for your newly created API user.
165 ### Permissions <a id="icinga2-api-permissions"></a>
167 By default an API user does not have any permissions to perform
168 actions on the URL endpoints.
170 Permissions for API users must be specified in the `permissions` attribute
171 as array. The array items can be a list of permission strings with wildcard
174 Example for an API user with all permissions:
176 permissions = [ "*" ]
178 Note that you can use wildcards. Here's another example that only allows the user
179 to perform read-only object queries for hosts and services:
181 permissions = [ "objects/query/Host", "objects/query/Service" ]
183 You can also further restrict permissions by specifying a filter expression. The
184 filter expression has to be a [lambda function](17-language-reference.md#nullary-lambdas)
185 which must return a boolean value.
187 The following example allows the API user to query all hosts and services which have a
188 custom attribute `os` that matches the regular expression `^Linux`.
189 The [regex function](18-library-reference.md#global-functions-regex) is available as global function.
193 permission = "objects/query/Host"
194 filter = {{ regex("^Linux", host.vars.os) }}
197 permission = "objects/query/Service"
198 filter = {{ regex("^Linux", service.vars.os) }}
202 More information about filters can be found in the [filters](12-icinga2-api.md#icinga2-api-filters) chapter.
204 Available permissions for specific URL endpoints:
206 Permissions | URL Endpoint | Supports Filters
207 ------------------------------|---------------|-----------------
208 actions/<action> | /v1/actions | Yes
209 config/query | /v1/config | No
210 config/modify | /v1/config | No
211 console | /v1/console | No
212 events/<type> | /v1/events | No
213 objects/query/<type> | /v1/objects | Yes
214 objects/create/<type> | /v1/objects | No
215 objects/modify/<type> | /v1/objects | Yes
216 objects/delete/<type> | /v1/objects | Yes
217 status/query | /v1/status | Yes
218 templates/<type> | /v1/templates | Yes
219 types | /v1/types | Yes
220 variables | /v1/variables | Yes
222 The required actions or types can be replaced by using a wildcard match ("\*").
224 ### Parameters <a id="icinga2-api-parameters"></a>
226 Depending on the request method there are two ways of
227 passing parameters to the request:
229 * JSON object as request body (all request methods other than `GET`)
230 * Query string as URL parameter (all request methods)
232 Reserved characters by the HTTP protocol must be [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding)
233 as query string, e.g. a space character becomes `%20`.
235 Example for a URL-encoded query string:
237 /v1/objects/hosts?filter=match(%22example.localdomain*%22,host.name)&attrs=name&attrs=state
239 Here are the exact same query parameters as a JSON object:
241 { "filter": "match(\"example.localdomain*\",host.name)", "attrs": [ "host.name", "host.state" ] }
243 The [match function](18-library-reference.md#global-functions-match) is available as global function
246 ### Request Method Override <a id="icinga2-api-requests-method-override"></a>
248 `GET` requests do not allow you to send a request body. In case you cannot pass everything as URL
249 parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the `X-HTTP-Method-Override`
250 header. This comes in handy when you are using HTTP proxies disallowing `PUT` or `DELETE` requests too.
252 Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header:
254 $ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -X POST -H 'X-HTTP-Method-Override: GET' 'https://localhost:5665/v1/objects/hosts'
256 Delete an existing object by sending a `POST` request with `X-HTTP-Method-Override: DELETE` as request header:
258 $ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -X POST -H 'X-HTTP-Method-Override: DELETE' 'https://localhost:5665/v1/objects/hosts/example.localdomain'
260 ### Filters <a id="icinga2-api-filters"></a>
262 #### Simple Filters <a id="icinga2-api-simple-filters"></a>
264 By default actions and queries operate on all objects unless further restricted by the user. For
265 example, the following query returns all `Host` objects:
267 https://localhost:5665/v1/objects/hosts
269 If you're only interested in a single object, you can limit the output to that object by specifying its name:
271 https://localhost:5665/v1/objects/hosts?host=localhost
273 **The name of the URL parameter is the lower-case version of the type the query applies to.** For
274 example, for `Host` objects the URL parameter therefore is `host`, for `Service` objects it is
277 You can also specify multiple objects:
279 https://localhost:5665/v1/objects/hosts?hosts=first-host&hosts=second-host
281 Again -- like in the previous example -- the name of the URL parameter is the lower-case version of the type. However, because we're specifying multiple objects here the **plural form** of the type is used.
283 When specifying names for objects which have composite names like for example services the
284 full name has to be used:
286 https://localhost:5665/v1/objects/services?service=localhost!ping6
288 The full name of an object can be obtained by looking at the `__name` attribute.
290 #### Advanced Filters <a id="icinga2-api-advanced-filters"></a>
292 Most of the information provided in this chapter applies to both permission filters (as used when
293 configuring `ApiUser` objects) and filters specified in queries.
295 Advanced filters allow users to filter objects using lambda expressions. The syntax for these filters is the same like for [apply rule expressions](03-monitoring-basics.md#using-apply-expressions).
299 > Filters used as URL parameter must be URL-encoded. The following examples
300 > are **not URL-encoded** for better readability.
302 Example matching all services in NOT-OK state:
304 https://localhost:5665/v1/objects/services?filter=service.state!=ServiceOK
306 Example [matching](18-library-reference.md#global-functions-match) all hosts by a name string pattern:
308 https://localhost:5665/v1/objects/hosts?filter=match("example.localdomain*",host.name)
310 Example for all hosts which are in the host group `linux-servers`:
312 https://localhost:5665/v1/objects/hosts?filter="linux-servers" in host.groups
314 User-specified filters are run in a sandbox environment which ensures that filters cannot
315 modify Icinga's state, for example object attributes or global variables.
317 When querying objects of a specific type the filter expression is evaluated for each object
318 of that type. The object is made available to the filter expression as a variable whose name
319 is the lower-case version of the object's type name.
321 For example when querying objects of type `Host` the variable in the filter expression is named
322 `host`. Additionally related objects such as the host's check command are also made available
323 (e.g., via the `check_command` variable). The variable names are the exact same as for the `joins`
324 query parameter; see [object query joins](12-icinga2-api.md#icinga2-api-config-objects-query-joins)
327 The object is also made available via the `obj` variable. This makes it easier to build
328 filters which can be used for more than one object type (e.g., for permissions).
330 Some queries can be performed for more than just one object type. One example is the 'reschedule-check'
331 action which can be used for both hosts and services. When using advanced filters you will also have to specify the
332 type using the `type` parameter:
334 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/reschedule-check' \
335 -d '{ "type": "Service", "filter": "service.name==\"ping6\"" }' | python -m json.tool
337 When building filters you have to ensure that values such as
338 `"linux-servers"` are escaped properly according to the rules of the Icinga 2 configuration
341 To make using the API in scripts easier you can use the `filter_vars` attribute to specify
342 variables which should be made available to your filter expression. This way you don't have
343 to worry about escaping values:
345 $ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/hosts' \
346 -d '{ "filter": "host.vars.os == os", "filter_vars": { "os": "Linux" } }'
348 We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) here because
349 the HTTP specification does not allow message bodies for GET requests.
351 The `filters_vars` attribute can only be used inside the request body, but not as
352 a URL parameter because there is no way to specify a dictionary in a URL.
354 ## Config Objects <a id="icinga2-api-config-objects"></a>
356 Provides methods to manage configuration objects:
358 * [creating objects](12-icinga2-api.md#icinga2-api-config-objects-create)
359 * [querying objects](12-icinga2-api.md#icinga2-api-config-objects-query)
360 * [modifying objects](12-icinga2-api.md#icinga2-api-config-objects-modify)
361 * [deleting objects](12-icinga2-api.md#icinga2-api-config-objects-delete)
363 ### API Objects and Cluster Config Sync <a id="icinga2-api-config-objects-cluster-sync"></a>
365 Newly created or updated objects can be synced throughout your
366 Icinga 2 cluster. Set the `zone` attribute to the zone this object
367 belongs to and let the API and cluster handle the rest.
369 Objects without a zone attribute are only synced in the same zone the Icinga instance belongs to.
373 > Cluster nodes must accept configuration for creating, modifying
374 > and deleting objects. Ensure that `accept_config` is set to `true`
375 > in the [ApiListener](09-object-types.md#objecttype-apilistener) object
378 If you add a new cluster instance, or reconnect an instance which has been offline
379 for a while, Icinga 2 takes care of the initial object sync for all objects
382 ### Querying Objects <a id="icinga2-api-config-objects-query"></a>
384 You can request information about configuration objects by sending
385 a `GET` query to the `/v1/objects/<type>` URL endpoint. `<type` has
386 to be replaced with the plural name of the object type you are interested
389 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/hosts'
391 A list of all available configuration types is available in the
392 [object types](09-object-types.md#object-types) chapter.
394 The following URL parameters are available:
396 Parameters | Type | Description
397 -----------|--------------|----------------------------
398 attrs | Array | **Optional.** Limited attribute list in the output.
399 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`).
400 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.
402 In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) may be provided.
404 Instead of using a filter you can optionally specify the object name in the
405 URL path when querying a single object. For objects with composite names
406 (e.g. services) the full name (e.g. `example.localdomain!http`) must be specified:
408 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/services/example.localdomain!http'
410 You can limit the output to specific attributes using the `attrs` URL parameter:
412 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/hosts/example.localdomain?attrs=name&attrs=address' | python -m json.tool
417 "name": "example.localdomain"
418 "address": "192.168.1.1"
422 "name": "example.localdomain",
428 #### Object Queries Result <a id="icinga2-api-config-objects-query-result"></a>
430 Each response entry in the results array contains the following attributes:
432 Attribute | Type | Description
433 -----------|------------|--------------
434 name | String | Full object name.
435 type | String | Object type.
436 attrs | Dictionary | Object attributes (can be filtered using the URL parameter `attrs`).
437 joins | Dictionary | [Joined object types](12-icinga2-api.md#icinga2-api-config-objects-query-joins) as key, attributes as nested dictionary. Disabled by default.
438 meta | Dictionary | Contains `used_by` object references. Disabled by default, enable it using `?meta=used_by` as URL parameter.
440 #### Object Query Joins <a id="icinga2-api-config-objects-query-joins"></a>
442 Icinga 2 knows about object relations. For example it can optionally return
443 information about the host when querying service objects.
445 The following query retrieves all host attributes:
447 https://localhost:5665/v1/objects/services?joins=host
449 Instead of requesting all host attributes you can also limit the output to specific
452 https://localhost:5665/v1/objects/services?joins=host.name&joins=host.address
454 You can request that all available joins are returned in the result set by using
455 the `all_joins` query parameter.
457 https://localhost:5665/v1/objects/services?all_joins=1
461 > For performance reasons you should only request attributes which your application
464 The following joins are available:
466 Object Type | Object Relations (`joins` prefix name)
467 -------------|------------------------------------------
468 Service | host, check\_command, check\_period, event\_command, command\_endpoint
469 Host | check\_command, check\_period, event\_command, command\_endpoint
470 Notification | host, service, command, period
471 Dependency | child\_host, child\_service, parent\_host, parent\_service, period
475 Here's an example that retrieves all service objects for hosts which have had their `os`
476 custom attribute set to `Linux`. The result set contains the `display_name` and `check_command`
477 attributes for the service. The query also returns the host's `name` and `address` attribute
480 $ curl -k -s -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' | python -m json.tool
486 "check_command": "ping4",
487 "display_name": "ping4"
491 "address": "192.168.1.1",
492 "name": "example.localdomain"
496 "name": "example.localdomain!ping4",
501 "check_command": "ssh",
502 "display_name": "ssh"
506 "address": "192.168.1.1",
507 "name": "example.localdomain"
511 "name": "example.localdomain!ssh",
517 In case you want to fetch all [comments](09-object-types.md#objecttype-comment)
518 for hosts and services, you can use the following query URL (similar example
521 https://localhost:5665/v1/objects/comments?joins=host&joins=service
523 This is another example for listing all service objects which are unhandled problems (state is not OK
524 and no downtime or acknowledgement set). We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
525 here because we want to pass all query attributes in the request body.
527 $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://127.0.0.1:5665/v1/objects/services' \
528 -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" }' | python -m json.tool
534 "acknowledgement": 0.0,
535 "downtime_depth": 0.0,
536 "name": "10807-service",
546 "name": "10807-host!10807-service",
552 In order to list all acknowledgements without expire time, you query the `/v1/objects/comments`
553 URL endpoint with `joins` and `filter` request parameters using the [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
556 $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/comments' \
557 -d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0" }' | python -m json.tool
563 "author": "icingaadmin",
564 "text": "maintenance work"
568 "__name": "example.localdomain!disk /",
569 "acknowledgement": 1.0,
570 "acknowledgement_expiry": 0.0
574 "name": "example.localdomain!disk /!example.localdomain-1495457222-0",
580 ### Creating Config Objects <a id="icinga2-api-config-objects-create"></a>
582 New objects must be created by sending a PUT request. The following
583 parameters need to be passed inside the JSON body:
585 Parameters | Type | Description
586 -----------|--------------|--------------------------
587 templates | Array | **Optional.** Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in [config packages](12-icinga2-api.md#icinga2-api-config-management)-
588 attrs | Dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
590 The object name must be specified as part of the URL path. For objects with composite names (e.g. services)
591 the full name (e.g. `example.localdomain!http`) must be specified.
593 If attributes are of the Dictionary type, you can also use the indexer format. This might be necessary to only override specific custom variables and keep all other existing custom variables (e.g. from templates):
595 "attrs": { "vars.os": "Linux" }
597 Example for creating the new host object `example.localdomain`:
599 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
600 -d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" } }' \
601 | python -m json.tool
606 "status": "Object was created."
611 If the configuration validation fails, the new object will not be created and the response body
612 contains a detailed error message. The following example is missing the `check_command` attribute
613 which is required for host objects:
615 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
616 -d '{ "attrs": { "address": "192.168.1.1", "vars.os" : "Linux" } }' \
617 | python -m json.tool
623 "Error: Validation failed for object 'example.localdomain' of type 'Host'; Attribute 'check_command': Attribute must not be empty."
625 "status": "Object could not be created."
630 Service objects must be created using their full name ("hostname!servicename") referencing an existing host object:
632 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/services/example.localdomain!realtime-load' \
633 -d '{ "templates": [ "generic-service" ], "attrs": { "check_command": "load", "check_interval": 1,"retry_interval": 1 } }'
636 Example for a new CheckCommand object:
638 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/checkcommands/mytest' \
639 -d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }'
642 ### Modifying Objects <a id="icinga2-api-config-objects-modify"></a>
644 Existing objects must be modified by sending a `POST` request. The following
645 parameters need to be passed inside the JSON body:
647 Parameters | Type | Description
648 -----------|------------|---------------------------
649 attrs | Dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
651 In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided.
655 > Modified attributes do not trigger a re-evaluation of existing
656 > static [apply rules](03-monitoring-basics.md#using-apply) and [group assignments](03-monitoring-basics.md#group-assign-intro).
657 > Delete and re-create the objects if you require such changes.
659 > Furthermore you cannot modify templates which have already been resolved
660 > during [object creation](12-icinga2-api.md#icinga2-api-config-objects-create).
661 > There are attributes which can only be set for [PUT requests](12-icinga2-api.md#icinga2-api-config-objects-create) such as `groups`
662 > or `zone`. A complete list of `no_user_modify` attributes can be fetched from the [types](12-icinga2-api.md#icinga2-api-types) URL endpoint.
664 If attributes are of the Dictionary type, you can also use the indexer format:
666 "attrs": { "vars.os": "Linux" }
668 The following example updates the `address` attribute and the custom attribute `os` for the `example.localdomain` host:
670 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
671 -d '{ "attrs": { "address": "192.168.1.2", "vars.os" : "Windows" } }' \
672 | python -m json.tool
677 "name": "example.localdomain",
678 "status": "Attributes updated.",
685 ### Deleting Objects <a id="icinga2-api-config-objects-delete"></a>
687 You can delete objects created using the API by sending a `DELETE`
690 Parameters | Type | Description
691 -----------|---------|---------------
692 cascade | Boolean | **Optional.** Delete objects depending on the deleted objects (e.g. services on a host).
694 In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided.
696 Example for deleting the host object `example.localdomain`:
698 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE 'https://localhost:5665/v1/objects/hosts/example.localdomain?cascade=1' | python -m json.tool
703 "name": "example.localdomain",
704 "status": "Object was deleted.",
710 ## Config Templates <a id="icinga2-api-config-templates"></a>
712 Provides methods to manage configuration templates:
714 * [querying templates](12-icinga2-api.md#icinga2-api-config-templates-query)
716 Creation, modification and deletion of templates at runtime is not supported.
718 ### Querying Templates <a id="icinga2-api-config-templates-query"></a>
720 You can request information about configuration templates by sending
721 a `GET` query to the `/v1/templates/<type>` URL endpoint. `<type` has
722 to be replaced with the plural name of the object type you are interested
725 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/templates/hosts'
727 A list of all available configuration types is available in the
728 [object types](09-object-types.md#object-types) chapter.
730 A [filter](12-icinga2-api.md#icinga2-api-filters) may be provided for this query type. The
731 template object can be accessed in the filter using the `tmpl` variable. In this
732 example the [match function](18-library-reference.md#global-functions-match) is used to
733 check a wildcard string pattern against `tmpl.name`.
734 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)
737 $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5661/v1/templates/hosts' \
738 -d '{ "filter": "match(\"g*\", tmpl.name)" }'
740 Instead of using a filter you can optionally specify the template name in the
741 URL path when querying a single object:
743 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/templates/hosts/generic-host'
745 The result set contains the type, name as well as the location of the template.
747 ## Variables <a id="icinga2-api-variables"></a>
749 Provides methods to manage global variables:
751 * [querying variables](12-icinga2-api.md#icinga2-api-variables-query)
753 ### Querying Variables <a id="icinga2-api-variables-query"></a>
755 You can request information about global variables by sending
756 a `GET` query to the `/v1/variables/` URL endpoint:
758 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/variables'
760 A [filter](12-icinga2-api.md#icinga2-api-filters) may be provided for this query type. The
761 variable information object can be accessed in the filter using the `variable` variable.
762 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)
765 $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5661/v1/variables' \
766 -d '{ "filter": "variable.type in [ \"String\", \"Number\" ]" }'
768 Instead of using a filter you can optionally specify the variable name in the
769 URL path when querying a single variable:
771 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/variables/PrefixDir'
773 The result set contains the type, name and value of the global variable.
775 ## Actions <a id="icinga2-api-actions"></a>
777 There are several actions available for Icinga 2 provided by the `/v1/actions`
778 URL endpoint. You can run actions by sending a `POST` request.
780 In case you have been using the [external commands](14-features.md#external-commands)
781 in the past, the API actions provide a similar interface with filter
782 capabilities for some of the more common targets which do not directly change
785 All actions return a 200 `OK` or an appropriate error code for each
786 action performed on each object matching the supplied filter.
788 Actions which affect the Icinga Application itself such as disabling
789 notification on a program-wide basis must be applied by updating the
790 [IcingaApplication object](12-icinga2-api.md#icinga2-api-config-objects)
793 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' -d '{ "attrs": { "enable_notifications": false } }'
795 ### process-check-result <a id="icinga2-api-actions-process-check-result"></a>
797 Process a check result for a host or a service.
799 Send a `POST` request to the URL endpoint `/v1/actions/process-check-result`.
801 Parameter | Type | Description
802 ------------------|--------------|--------------
803 exit\_status | Number | **Required.** For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=OK, 1=CRITICAL.
804 plugin\_output | String | **Required.** One or more lines of the plugin main output. Does **not** contain the performance data.
805 performance\_data | Array | **Optional.** The performance data.
806 check\_command | Array | **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.
807 check\_source | String | **Optional.** Usually the name of the `command_endpoint`
808 execution\_start | Timestamp | **Optional.** The timestamp where a script/process started its execution.
809 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.
811 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`.
813 Example for the service `passive-ping6`:
815 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result?service=example.localdomain!passive-ping6' \
816 -d '{ "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" }' | python -m json.tool
822 "status": "Successfully processed check result for object 'localdomain!passive-ping6'."
827 Example for using the `Host` type and filter by the host name:
829 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result' \
830 -d '{ "filter": "host.name==\"example.localdomain\"", "type": "Host", "exit_status": 1, "plugin_output": "Host is not available." }'
832 You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body.
836 > Multi-line plugin output requires the following format: The first line is treated as `short` plugin output corresponding
837 > to the first line of the plugin output. Subsequent lines are treated as `long` plugin output. Please note that the
838 > performance data is separated from the plugin output and has to be passed as `performance_data` attribute.
840 ### reschedule-check <a id="icinga2-api-actions-reschedule-check"></a>
842 Reschedule a check for hosts and services. The check can be forced if required.
844 Send a `POST` request to the URL endpoint `/v1/actions/reschedule-check`.
846 Parameter | Type | Description
847 -------------|-----------|--------------
848 next\_check | Timestamp | **Optional.** The next check will be run at this time. If omitted, the current time is used.
849 force\_check | Boolean | **Optional.** Defaults to `false`. If enabled, the checks are executed regardless of time period restrictions and checks being disabled per object or on a global basis.
851 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`.
853 The example reschedules all services with the name "ping6" to immediately perform a check
854 (`next_check` default), ignoring any time periods or whether active checks are
855 allowed for the service (`force_check=true`).
857 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/reschedule-check' \
858 -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force_check": true }' | python -m json.tool
864 "status": "Successfully rescheduled check for object 'example.localdomain!ping6'."
870 ### send-custom-notification <a id="icinga2-api-actions-send-custom-notification"></a>
872 Send a custom notification for hosts and services. This notification
873 type can be forced being sent to all users.
875 Send a `POST` request to the URL endpoint `/v1/actions/send-custom-notification`.
877 Parameter | Type | Description
878 ----------|---------|--------------
879 author | String | **Required.** Name of the author, may be empty.
880 comment | String | **Required.** Comment text, may be empty.
881 force | Boolean | **Optional.** Default: false. If true, the notification is sent regardless of downtimes or whether notifications are enabled or not.
883 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`.
885 Example for a custom host notification announcing a global maintenance to
888 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/send-custom-notification' \
889 -d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true }' | python -m json.tool
895 "status": "Successfully sent custom notification for object 'host0'."
899 "status": "Successfully sent custom notification for object 'host1'."
903 ### delay-notification <a id="icinga2-api-actions-delay-notification"></a>
905 Delay notifications for a host or a service.
906 Note that this will only have an effect if the service stays in the same problem
907 state that it is currently in. If the service changes to another state, a new
908 notification may go out before the time you specify in the `timestamp` argument.
910 Send a `POST` request to the URL endpoint `/v1/actions/delay-notification`.
912 Parameter | Type | Description
913 ----------|-----------|--------------
914 timestamp | Timestamp | **Required.** Delay notifications until this timestamp.
916 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`.
920 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/delay-notification' \
921 -d '{ "type": "Service", "timestamp": 1446389894 }' | python -m json.tool
927 "status": "Successfully delayed notifications for object 'host0!service0'."
931 "status": "Successfully delayed notifications for object 'host1!service1'."
935 ### acknowledge-problem <a id="icinga2-api-actions-acknowledge-problem"></a>
937 Allows you to acknowledge the current problem for hosts or services. By
938 acknowledging the current problem, future notifications (for the same state if `sticky` is set to `false`)
941 Send a `POST` request to the URL endpoint `/v1/actions/acknowledge-problem`.
943 Parameter | Type | Description
944 ---------------------|-----------|--------------
945 author | String | **Required.** Name of the author, may be empty.
946 comment | String | **Required.** Comment text, may be empty.
947 expiry | Timestamp | **Optional.** Whether the acknowledgement will be removed at the timestamp.
948 sticky | Boolean | **Optional.** Whether the acknowledgement will be set until the service or host fully recovers. Defaults to `false`.
949 notify | Boolean | **Optional.** Whether a notification of the `Acknowledgement` type will be sent. Defaults to `false`.
950 persistent | Boolean | **Optional.** When the comment is of type `Acknowledgement` and this is set to `true`, the comment will remain after the acknowledgement recovers or expires. Defaults to `false`.
952 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`.
954 The following example acknowledges all services which are in a hard critical state and sends out
955 a notification for them:
957 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/acknowledge-problem?type=Service&filter=service.state==2&service.state_type=1' \
958 -d '{ "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true }' | python -m json.tool
964 "status": "Successfully acknowledged problem for object 'example2.localdomain!ping4'."
968 "status": "Successfully acknowledged problem for object 'example.localdomain!ping4'."
973 ### remove-acknowledgement <a id="icinga2-api-actions-remove-acknowledgement"></a>
975 Removes the acknowledgements for services or hosts. Once the acknowledgement has
976 been removed notifications will be sent out again.
978 Send a `POST` request to the URL endpoint `/v1/actions/remove-acknowledgement`.
980 A [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
982 The example removes all service acknowledgements:
984 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-acknowledgement?type=Service' | python -m json.tool
990 "status": "Successfully removed acknowledgement for object 'host0!service0'."
994 "status": "Successfully removed acknowledgement for object 'example2.localdomain!aws-health'."
998 ### add-comment <a id="icinga2-api-actions-add-comment"></a>
1000 Adds a `comment` from an `author` to services or hosts.
1002 Send a `POST` request to the URL endpoint `/v1/actions/add-comment`.
1004 Parameter | Type | Description
1005 ----------|--------|--------------
1006 author | string | **Required.** Name of the author, may be empty.
1007 comment | string | **Required.** Comment text, may be empty.
1009 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`.
1011 The following example adds a comment for all `ping4` services:
1013 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/add-comment?type=Service&filter=service.name==%22ping4%22' -d '{ "author": "icingaadmin", "comment": "Troubleticket #123456789 opened." }' | python -m json.tool
1019 "name": "example.localdomain!ping4!example.localdomain-1446824161-0",
1020 "status": "Successfully added comment 'example.localdomain!ping4!example.localdomain-1446824161-0' for object 'example.localdomain!ping4'."
1025 "name": "example2.localdomain!ping4!example.localdomain-1446824161-1",
1026 "status": "Successfully added comment 'example2.localdomain!ping4!example.localdomain-1446824161-1' for object 'example2.localdomain!ping4'."
1031 ### remove-comment <a id="icinga2-api-actions-remove-comment"></a>
1033 Remove the comment using its `name` attribute , returns `OK` if the
1034 comment did not exist.
1035 **Note**: This is **not** the legacy ID but the comment name returned by
1036 Icinga 2 when [adding a comment](12-icinga2-api.md#icinga2-api-actions-add-comment).
1038 Send a `POST` request to the URL endpoint `/v1/actions/remove-comment`.
1040 A [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host`, `Service` and `Comment`.
1042 Example for a simple filter using the `comment` URL parameter:
1044 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-comment?comment=example2.localdomain!ping4!mbmif.local-1446986367-0' | python -m json.tool
1049 "status": "Successfully removed comment 'example2.localdomain!ping4!mbmif.local-1446986367-0'."
1054 Example for removing all service comments using a service name filter for `ping4`:
1056 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-comment?filter=service.name==%22ping4%22&type=Service' | python -m json.tool
1061 "status": "Successfully removed all comments for object 'example2.localdomain!ping4'."
1065 "status": "Successfully removed all comments for object 'example.localdomain!ping4'."
1071 ### schedule-downtime <a id="icinga2-api-actions-schedule-downtime"></a>
1073 Schedule a downtime for hosts and services.
1075 Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`.
1077 Parameter | Type | Description
1078 --------------|-----------|--------------
1079 author | String | **Required.** Name of the author.
1080 comment | String | **Required.** Comment text.
1081 start\_time | Timestamp | **Required.** Timestamp marking the beginning of the downtime.
1082 end\_time | Timestamp | **Required.** Timestamp marking the end of the downtime.
1083 fixed | Boolean | **Optional.** Defaults to `true`. If true, the downtime is `fixed` otherwise `flexible`. See [downtimes](08-advanced-topics.md#downtimes) for more information.
1084 duration | Number | **Required for flexible downtimes.** Duration of the downtime in seconds if `fixed` is set to false.
1085 trigger\_name | String | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](08-advanced-topics.md#downtimes) for more information on triggered downtimes.
1086 child\_options | Number | **Optional.** Schedule child downtimes. `0` does not do anything, `1` schedules child downtimes triggered by this downtime, `2` schedules non-triggered downtimes. Defaults to `0`.
1088 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`.
1092 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/schedule-downtime?type=Service&filter=service.name==%22ping4%22' -d '{ "start_time": 1446388806, "end_time": 1446389806, "duration": 1000, "author": "icingaadmin", "comment": "IPv4 network maintenance" }' | python -m json.tool
1098 "name": "example2.localdomain!ping4!example.localdomain-1446822004-0",
1099 "status": "Successfully scheduled downtime 'example2.localdomain!ping4!example.localdomain-1446822004-0' for object 'example2.localdomain!ping4'."
1104 "name": "example.localdomain!ping4!example.localdomain-1446822004-1",
1105 "status": "Successfully scheduled downtime 'example.localdomain!ping4!example.localdomain-1446822004-1' for object 'example.localdomain!ping4'."
1110 ### remove-downtime <a id="icinga2-api-actions-remove-downtime"></a>
1112 Remove the downtime using its `name` attribute , returns `OK` if the
1113 downtime did not exist.
1114 **Note**: This is **not** the legacy ID but the downtime name returned by
1115 Icinga 2 when [scheduling a downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime).
1117 Send a `POST` request to the URL endpoint `/v1/actions/remove-downtime`.
1119 A [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host`, `Service` and `Downtime`.
1121 Example for a simple filter using the `downtime` URL parameter:
1123 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime?downtime=example.localdomain!ping4!mbmif.local-1446979168-6' | python -m json.tool
1128 "status": "Successfully removed downtime 'example.localdomain!ping4!mbmif.local-1446979168-6'."
1133 Example for removing all host downtimes using a host name filter for `example.localdomain`:
1135 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime?filter=host.name==%22example.localdomain%22&type=Host' | python -m json.tool
1140 "status": "Successfully removed all downtimes for object 'example.localdomain'."
1145 Example for removing a downtime from a host but not the services filtered by the author name. This example uses
1146 filter variables explained in the [advanced filters](12-icinga2-api.md#icinga2-api-advanced-filters) chapter.
1148 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime' \
1151 "filter": "host.name == filterHost && !service && downtime.author == filterAuthor",
1153 "filterHost": "example.localdomain",
1154 "filterAuthor": "icingaadmin"
1156 }' | python -m json.tool
1162 "status": "Successfully removed downtime 'example.localdomain!mbmif.local-1463043129-3'."
1167 ### shutdown-process <a id="icinga2-api-actions-shutdown-process"></a>
1169 Shuts down Icinga2. May or may not return.
1171 Send a `POST` request to the URL endpoint `/v1/actions/shutdown-process`.
1173 This action does not support a target type or filter.
1177 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/shutdown-process' | python -m json.tool
1183 "status": "Shutting down Icinga 2."
1188 ### restart-process <a id="icinga2-api-actions-restart-process"></a>
1190 Restarts Icinga2. May or may not return.
1192 Send a `POST` request to the URL endpoint `/v1/actions/restart-process`.
1194 This action does not support a target type or filter.
1198 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/restart-process' | python -m json.tool
1204 "status": "Restarting Icinga 2."
1209 ### generate-ticket <a id="icinga2-api-actions-generate-ticket"></a>
1211 Generates a PKI ticket for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing).
1212 This can be used in combination with satellite/client setups requesting this ticket number.
1214 Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`.
1216 Parameter | Type | Description
1217 --------------|-----------|--------------
1218 cn | String | **Required.** The host's common name for which the ticket should be geenerated.
1222 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/generate-ticket' \
1223 -d '{ "cn": "icinga2-client1.localdomain" }' | python -m json.tool
1228 "status": "Generated PKI ticket '4f75d2ecd253575fe9180938ebff7cbca262f96e' for common name 'icinga2-client1.localdomain'.",
1229 "ticket": "4f75d2ecd253575fe9180938ebff7cbca262f96e"
1235 ## Event Streams <a id="icinga2-api-event-streams"></a>
1237 You can subscribe to event streams by sending a `POST` request to the URL endpoint `/v1/events`.
1238 The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body):
1240 Parameter | Type | Description
1241 -----------|--------------|-------------
1242 types | Array | **Required.** Event type(s). Multiple types as URL parameters are supported.
1243 queue | String | **Required.** Unique queue name. Multiple HTTP clients can use the same queue as long as they use the same event types and filter.
1244 filter | String | **Optional.** Filter for specific event attributes using [filter expressions](12-icinga2-api.md#icinga2-api-filters).
1246 ### Event Stream Types <a id="icinga2-api-event-streams-types"></a>
1248 The following event stream types are available:
1251 -----------------------|--------------
1252 CheckResult | Check results for hosts and services.
1253 StateChange | Host/service state changes.
1254 Notification | Notification events including notified users for hosts and services.
1255 AcknowledgementSet | Acknowledgement set on hosts and services.
1256 AcknowledgementCleared | Acknowledgement cleared on hosts and services.
1257 CommentAdded | Comment added for hosts and services.
1258 CommentRemoved | Comment removed for hosts and services.
1259 DowntimeAdded | Downtime added for hosts and services.
1260 DowntimeRemoved | Downtime removed for hosts and services.
1261 DowntimeStarted | Downtime started for hosts and services.
1262 DowntimeTriggered | Downtime triggered for hosts and services.
1264 Note: Each type requires [API permissions](12-icinga2-api.md#icinga2-api-permissions)
1267 Example for all downtime events:
1269 &types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered
1271 #### <a id="icinga2-api-event-streams-type-checkresult"></a> Event Stream Type: CheckResult
1273 Name | Type | Description
1274 --------------|---------------|--------------------------
1275 type | String | Event type `CheckResult`.
1276 timestamp | Timestamp | Unix timestamp when the event happened.
1277 host | String | [Host](09-object-types.md#objecttype-host) name.
1278 service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host check result.
1279 check\_result | CheckResult | Serialized [CheckResult](08-advanced-topics.md#advanced-value-types-checkresult) value type.
1281 #### <a id="icinga2-api-event-streams-type-statechange"></a> Event Stream Type: StateChange
1283 Name | Type | Description
1284 --------------|---------------|--------------------------
1285 type | String | Event type `StateChange`.
1286 timestamp | Timestamp | Unix timestamp when the event happened.
1287 host | String | [Host](09-object-types.md#objecttype-host) name.
1288 service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host state change.
1289 state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
1290 state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
1291 check\_result | CheckResult | Serialized [CheckResult](08-advanced-topics.md#advanced-value-types-checkresult) value type.
1293 #### <a id="icinga2-api-event-streams-type-notification"></a> Event Stream Type: Notification
1295 Name | Type | Description
1296 --------------|---------------|--------------------------
1297 type | String | Event type `Notification`.
1298 timestamp | Timestamp | Unix timestamp when the event happened.
1299 host | String | [Host](09-object-types.md#objecttype-host) name.
1300 service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host notification.
1301 users | Array | List of notified [user](09-object-types.md#objecttype-user) names.
1302 notification\_type | String | [$notification.type$](03-monitoring-basics.md#notification-runtime-macros) runtime macro value.
1303 author | String | [$notification.author$](03-monitoring-basics.md#notification-runtime-macros) runtime macro value.
1304 text | String | [$notification.comment$](03-monitoring-basics.md#notification-runtime-macros) runtime macro value.
1305 check\_result | CheckResult | Serialized [CheckResult](08-advanced-topics.md#advanced-value-types-checkresult) value type.
1307 #### <a id="icinga2-api-event-streams-type-flapping"></a> Event Stream Type: Flapping
1309 Name | Type | Description
1310 ------------------|---------------|--------------------------
1311 type | String | Event type `Flapping`.
1312 timestamp | Timestamp | Unix timestamp when the event happened.
1313 host | String | [Host](09-object-types.md#objecttype-host) name.
1314 service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host flapping event.
1315 state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
1316 state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
1317 is\_flapping | Boolean | Whether this object is flapping.
1318 current\_flapping | Number | Current flapping value in percent (added in 2.8).
1319 threshold\_low | Number | Low threshold in percent (added in 2.8).
1320 threshold\_high | Number | High threshold in percent (added in 2.8).
1322 #### <a id="icinga2-api-event-streams-type-acknowledgementset"></a> Event Stream Type: AcknowledgementSet
1324 Name | Type | Description
1325 --------------|---------------|--------------------------
1326 type | String | Event type `AcknowledgementSet`.
1327 timestamp | Timestamp | Unix timestamp when the event happened.
1328 host | String | [Host](09-object-types.md#objecttype-host) name.
1329 service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host acknowledgement.
1330 state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
1331 state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
1332 author | String | Acknowledgement author set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
1333 comment | String | Acknowledgement comment set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
1334 acknowledgement\_type | Number | 0 = None, 1 = Normal, 2 = Sticky. `sticky` can be set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
1335 notify | Boolean | Notifications were enabled via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
1336 expiry | Timestamp | Acknowledgement expire time set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
1338 #### <a id="icinga2-api-event-streams-type-acknowledgementcleared"></a> Event Stream Type: AcknowledgementCleared
1340 Name | Type | Description
1341 --------------|---------------|--------------------------
1342 type | String | Event type `AcknowledgementCleared`.
1343 timestamp | Timestamp | Unix timestamp when the event happened.
1344 host | String | [Host](09-object-types.md#objecttype-host) name.
1345 service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host acknowledgement.
1346 state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
1347 state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
1349 #### <a id="icinga2-api-event-streams-type-commentadded"></a> Event Stream Type: CommentAdded
1351 Name | Type | Description
1352 --------------|---------------|--------------------------
1353 type | String | Event type `CommentAdded`.
1354 timestamp | Timestamp | Unix timestamp when the event happened.
1355 comment | Dictionary | Serialized [Comment](09-object-types.md#objecttype-comment) object.
1357 #### <a id="icinga2-api-event-streams-type-commentremoved"></a> Event Stream Type: CommentRemoved
1359 Name | Type | Description
1360 --------------|---------------|--------------------------
1361 type | String | Event type `CommentRemoved`.
1362 timestamp | Timestamp | Unix timestamp when the event happened.
1363 comment | Dictionary | Serialized [Comment](09-object-types.md#objecttype-comment) object.
1365 #### <a id="icinga2-api-event-streams-type-downtimeadded"></a> Event Stream Type: DowntimeAdded
1367 Name | Type | Description
1368 --------------|---------------|--------------------------
1369 type | String | Event type `DowntimeAdded`.
1370 timestamp | Timestamp | Unix timestamp when the event happened.
1371 downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
1373 #### <a id="icinga2-api-event-streams-type-downtimeremoved"></a> Event Stream Type: DowntimeRemoved
1375 Name | Type | Description
1376 --------------|---------------|--------------------------
1377 type | String | Event type `DowntimeRemoved`.
1378 timestamp | Timestamp | Unix timestamp when the event happened.
1379 downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
1382 #### <a id="icinga2-api-event-streams-type-downtimestarted"></a> Event Stream Type: DowntimeStarted
1384 Name | Type | Description
1385 --------------|---------------|--------------------------
1386 type | String | Event type `DowntimeStarted`.
1387 timestamp | Timestamp | Unix timestamp when the event happened.
1388 downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
1391 #### <a id="icinga2-api-event-streams-type-downtimetriggered"></a> Event Stream Type: DowntimeTriggered
1393 Name | Type | Description
1394 --------------|---------------|--------------------------
1395 type | String | Event type `DowntimeTriggered`.
1396 timestamp | Timestamp | Unix timestamp when the event happened.
1397 downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
1400 ### Event Stream Filter <a id="icinga2-api-event-streams-filter"></a>
1402 Event streams can be filtered by attributes using the prefix `event.`.
1404 Example for the `CheckResult` type with the `exit_code` set to `2`:
1406 &types=CheckResult&filter=event.check_result.exit_status==2
1408 Example for the `CheckResult` type with the service [matching](18-library-reference.md#global-functions-match)
1409 the string pattern "random\*":
1411 &types=CheckResult&filter=match%28%22random*%22,event.service%29
1414 ### Event Stream Response <a id="icinga2-api-event-streams-response"></a>
1416 The event stream response is separated with new lines. The HTTP client
1417 must support long-polling and HTTP/1.1. HTTP/1.0 is not supported.
1421 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/events?queue=michi&types=CheckResult&filter=event.check_result.exit_status==2'
1423 {"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421319.7226390839,"type":"CheckResult"}
1424 {"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421324.7226390839,"type":"CheckResult"}
1425 {"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421329.7226390839,"type":"CheckResult"}
1428 ## Status and Statistics <a id="icinga2-api-status"></a>
1430 Send a `GET` request to the URL endpoint `/v1/status` to retrieve status information and statistics for Icinga 2.
1434 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status' | python -m json.tool
1438 "name": "ApiListener",
1439 "perfdata": [ ... ],
1444 "name": "IcingaAplication",
1445 "perfdata": [ ... ],
1452 You can limit the output by specifying a status type in the URL, e.g. `IcingaApplication`:
1454 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication' | python -m json.tool
1460 "icingaapplication": {
1462 "enable_event_handlers": true,
1463 "enable_flapping": true,
1464 "enable_host_checks": true,
1465 "enable_notifications": true,
1466 "enable_perfdata": true,
1467 "enable_service_checks": true,
1468 "node_name": "example.localdomain",
1470 "program_start": 1443019345.093372,
1471 "version": "v2.3.0-573-g380a131"
1480 ## Configuration Management <a id="icinga2-api-config-management"></a>
1482 The main idea behind configuration management is to allow external applications
1483 creating configuration packages and stages based on configuration files and
1484 directory trees. This replaces any additional SSH connection and whatnot to
1485 dump configuration files to Icinga 2 directly.
1486 In case you are pushing a new configuration stage to a package, Icinga 2 will
1487 validate the configuration asynchronously and populate a status log which
1488 can be fetched in a separated request.
1491 ### Creating a Config Package <a id="icinga2-api-config-management-create-package"></a>
1493 Send a `POST` request to a new config package called `example-cmdb` in this example. This
1494 will create a new empty configuration package.
1496 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
1497 'https://localhost:5665/v1/config/packages/example-cmdb' | python -m json.tool
1502 "package": "example-cmdb",
1503 "status": "Created package."
1508 Package names starting with an underscore are reserved for internal packages and must not be used.
1510 ### Uploading configuration for a Config Package <a id="icinga2-api-config-management-create-config-stage"></a>
1512 Configuration files in packages are managed in stages.
1513 Stages provide a way to maintain multiple configuration versions for a package.
1515 Send a `POST` request to the URL endpoint `/v1/config/stages` and add the name of an existing
1516 configuration package to the URL path (e.g. `example-cmdb`).
1517 The request body must contain the `files` attribute with the value being
1518 a dictionary of file targets and their content. You can also specify an optional `reload` attribute
1519 that will tell icinga2 to reload after stage config validation. By default this is set to `true`.
1521 The file path requires one of these two directories inside its path:
1523 Directory | Description
1524 ------------|------------------------------------
1525 conf.d | Local configuration directory.
1526 zones.d | Configuration directory for cluster zones, each zone must be put into its own zone directory underneath. Supports the [cluster config sync](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync).
1528 Example for a local configuration in the `conf.d` directory:
1530 "files": { "conf.d/host1.conf": "object Host \"local-host\" { address = \"127.0.0.1\", check_command = \"hostalive\" }" }
1532 Example for a host configuration inside the `satellite` zone in the `zones.d` directory:
1534 "files": { "zones.d/satellite/host2.conf": "object Host \"satellite-host\" { address = \"192.168.1.100\", check_command = \"hostalive\" }" }
1537 The example below will create a new file called `test.conf` in the `conf.d`
1538 directory. Note: This example contains an error (`chec_command`). This is
1541 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
1542 -d '{ "files": { "conf.d/test.conf": "object Host \"cmdb-host\" { chec_command = \"dummy\" }" } }' \
1543 'https://localhost:5665/v1/config/stages/example-cmdb' | python -m json.tool
1548 "package": "example-cmdb",
1549 "stage": "example.localdomain-1441625839-0",
1550 "status": "Created stage. Icinga2 will reload."
1555 The Icinga 2 API returns the `package` name this stage was created for, and also
1556 generates a unique name for the `stage` attribute you'll need for later requests.
1558 Icinga 2 automatically restarts the daemon in order to activate the new config stage. This
1559 can be disabled by setting `reload` to `false` in the request.
1560 If the validation for the new config stage failed, the old stage
1561 and its configuration objects will remain active.
1565 > Old stages are not purged automatically. You can [remove stages](12-icinga2-api.md#icinga2-api-config-management-delete-config-stage) that are no longer in use.
1567 Icinga 2 will create the following files in the configuration package
1568 stage after configuration validation:
1571 ------------|--------------
1572 status | Contains the [configuration validation](11-cli-commands.md#config-validation) exit code (everything else than 0 indicates an error).
1573 startup.log | Contains the [configuration validation](11-cli-commands.md#config-validation) output.
1575 You can [fetch these files](12-icinga2-api.md#icinga2-api-config-management-fetch-config-package-stage-files)
1576 in order to verify that the new configuration was deployed successfully.
1579 ### List Configuration Packages and their Stages <a id="icinga2-api-config-management-list-config-packages"></a>
1581 A list of packages and their stages can be retrieved by sending a `GET` request to the URL endpoint `/v1/config/packages`.
1583 The following example contains one configuration package `example-cmdb`. The package does not currently
1584 have an active stage.
1586 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/packages' | python -m json.tool
1591 "name": "example-cmdb",
1593 "example.localdomain-1441625839-0"
1600 ### List Configuration Packages and their Stages <a id="icinga2-api-config-management-list-config-package-stage-files"></a>
1602 In order to retrieve a list of files for a stage you can send a `GET` request to
1603 the URL endpoint `/v1/config/stages`. You need to include
1604 the package name (`example-cmdb`) and stage name (`example.localdomain-1441625839-0`) in the URL:
1606 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441625839-0' | python -m json.tool
1611 "name": "startup.log",
1627 "name": "conf.d/test.conf",
1633 ### Fetch Configuration Package Stage Files <a id="icinga2-api-config-management-fetch-config-package-stage-files"></a>
1635 Send a `GET` request to the URL endpoint `/v1/config/files` and add
1636 the package name, the stage name and the relative path to the file to the URL path.
1640 > The returned files are plain-text instead of JSON-encoded.
1642 The following example fetches the configuration file `conf.d/test.conf`:
1644 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441625839-0/conf.d/test.conf'
1646 object Host "cmdb-host" { chec_command = "dummy" }
1648 You can fetch a [list of existing files](12-icinga2-api.md#icinga2-api-config-management-list-config-package-stage-files)
1649 in a configuration stage and then specifically request their content.
1651 ### Configuration Package Stage Errors <a id="icinga2-api-config-management-config-package-stage-errors"></a>
1653 Now that we don't have an active stage for `example-cmdb` yet seen [here](12-icinga2-api.md#icinga2-api-config-management-list-config-packages),
1654 there must have been an error.
1656 In order to check for validation errors you can fetch the `startup.log` file
1657 by sending a `GET` request to the URL endpoint `/v1/config/files`. You must include
1658 the package name, stage name and the `startup.log` in the URL path.
1660 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441133065-1/startup.log'
1663 critical/config: Error: Attribute 'chec_command' does not exist.
1665 /var/lib/icinga2/api/packages/example-cmdb/example.localdomain-1441133065-1/conf.d/test.conf(1): object Host "cmdb-host" { chec_command = "dummy" }
1666 ^^^^^^^^^^^^^^^^^^^^^^
1668 critical/config: 1 error
1670 The output is similar to the manual [configuration validation](11-cli-commands.md#config-validation).
1674 > The returned output is plain-text instead of JSON-encoded.
1677 ### Deleting Configuration Package Stage <a id="icinga2-api-config-management-delete-config-stage"></a>
1679 You can send a `DELETE` request to the URL endpoint `/v1/config/stages`
1680 in order to purge a configuration stage. You must include the package and
1681 stage name inside the URL path.
1683 The following example removes the failed configuration stage `example.localdomain-1441133065-1`
1684 in the `example-cmdb` configuration package:
1686 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE \
1687 'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441133065-1' | python -m json.tool
1692 "status": "Stage deleted."
1698 ### Deleting Configuration Package <a id="icinga2-api-config-management-delete-config-package"></a>
1700 In order to completely purge a configuration package and its stages
1701 you can send a `DELETE` request to the URL endpoint `/v1/config/packages`
1702 with the package name in the URL path.
1704 This example entirely deletes the configuration package `example-cmdb`:
1706 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE \
1707 'https://localhost:5665/v1/config/packages/example-cmdb' | python -m json.tool
1712 "package": "example-cmdb",
1713 "status": "Deleted package."
1719 ## Types <a id="icinga2-api-types"></a>
1721 You can retrieve the configuration object types by sending a `GET` request to URL
1722 endpoint `/v1/types`.
1724 Each response entry in the results array contains the following attributes:
1726 Attribute | Type | Description
1727 ----------------|--------------|---------------------
1728 name | String | The type name.
1729 plural\_name | String | The plural type name.
1730 fields | Dictionary | Available fields including details on e.g. the type and attribute accessibility.
1731 abstract | Boolean | Whether objects can be instantiated for this type.
1732 base | Boolean | The base type (e.g. `Service` inherits fields and prototype methods from `Checkable`).
1733 prototype\_keys | Array | Available prototype methods.
1735 In order to view a specific configuration object type specify its name inside the URL path:
1737 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/types/Object' | python -m json.tool
1747 "navigation": false,
1748 "no_user_modify": false,
1749 "no_user_view": false,
1758 "plural_name": "Objects",
1769 ## Console <a id="icinga2-api-console"></a>
1771 You can inspect variables and execute other expressions by sending a `POST` request to the URL endpoint `/v1/console/execute-script`.
1772 In order to receive auto-completion suggestions, send a `POST` request to the URL endpoint `/v1/console/auto-complete-script`.
1774 The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body):
1776 Parameter | Type | Description
1777 -----------|--------------|-------------
1778 session | String | **Optional.** The session ID. Ideally this should be a GUID or some other unique identifier.
1779 command | String | **Required.** Command expression for execution or auto-completion.
1780 sandboxed | Number | **Optional.** Whether runtime changes are allowed or forbidden. Defaults to disabled.
1782 The [API permission](12-icinga2-api.md#icinga2-api-permissions) `console` is required for executing
1787 > Runtime modifications via `execute-script` calls are not validated and might cause the Icinga 2
1788 > daemon to crash or behave in an unexpected way. Use these runtime changes at your own risk.
1790 If you specify a session identifier, the same script context can be reused for multiple requests. This allows you to, for example, set a local variable in a request and use that local variable in another request. Sessions automatically expire after a set period of inactivity (currently 30 minutes).
1792 Example for fetching the command line from the local host's last check result:
1794 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/console/execute-script?command=get_host(NodeName).last_check_result.command&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756' | python -m json.tool
1800 "/usr/local/sbin/check_ping",
1808 "status": "Executed successfully."
1813 Example for fetching auto-completion suggestions for the `Host.` type. This works in a
1814 similar fashion when pressing TAB inside the [console CLI command](11-cli-commands.md#cli-command-console):
1816 $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/console/auto-complete-script?command=Host.&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756' | python -m json.tool
1821 "status": "Auto-completed successfully.",
1827 "Host.register_attribute_handler",
1829 "Host.notify_attribute",
1837 ## API Clients <a id="icinga2-api-clients"></a>
1839 There are a couple of existing clients which can be used with the Icinga 2 API:
1841 * [curl](https://curl.haxx.se/) or any other HTTP client really
1842 * [Icinga 2 console (CLI command)](12-icinga2-api.md#icinga2-api-clients-cli-console)
1843 * [Icinga Studio](12-icinga2-api.md#icinga2-api-clients-icinga-studio)
1844 * [Icinga Web 2 Director](https://www.icinga.com/products/icinga-web-2-modules/)
1848 * [Dashing](https://github.com/Icinga/dashing-icinga2)
1849 * [API examples](https://github.com/Icinga/icinga2-api-examples)
1851 Additional [programmatic examples](12-icinga2-api.md#icinga2-api-clients-programmatic-examples)
1852 will help you getting started using the Icinga 2 API in your environment.
1854 ### Icinga Studio <a id="icinga2-api-clients-icinga-studio"></a>
1856 Icinga Studio is a graphical application to query configuration objects provided by the API.
1858 ![Icinga Studio Connection](images/icinga2-api/icinga2_api_icinga_studio_connect.png)
1860 ![Icinga Studio Overview](images/icinga2-api/icinga2_api_icinga_studio_overview.png)
1862 Please check the package repository of your distribution for available
1866 > Icinga Studio does not currently support SSL certificate verification.
1868 The Windows installer already includes Icinga Studio. On Debian and Ubuntu the package
1869 `icinga2-studio` can be used to install Icinga Studio.
1871 ### Icinga 2 Console <a id="icinga2-api-clients-cli-console"></a>
1873 By default the [console CLI command](11-cli-commands.md#cli-command-console) evaluates
1874 expressions in a local interpreter, i.e. independently from your Icinga 2 daemon.
1875 Add the `--connect` parameter to debug and evaluate expressions via the API.
1877 ### API Clients Programmatic Examples <a id="icinga2-api-clients-programmatic-examples"></a>
1879 The programmatic examples use HTTP basic authentication and SSL certificate
1880 verification. The CA file is expected in `pki/icinga2-ca.crt`
1881 but you may adjust the examples for your likings.
1883 The [request method](icinga2-api-requests) is `POST` using
1884 [X-HTTP-Method-Override: GET](12-icinga2-api.md#icinga2-api-requests-method-override)
1885 which allows you to send a JSON request body. The examples request
1886 specific service attributes joined with host attributes. `attrs`
1887 and `joins` are therefore specified as array.
1888 The `filter` attribute [matches](18-library-reference.md#global-functions-match)
1889 on all services with `ping` in their name.
1891 #### Example API Client in Python <a id="icinga2-api-clients-programmatic-examples-python"></a>
1893 The following example uses **Python** and the `requests` and `json` module:
1895 # pip install requests
1898 $ vim icinga2-api-example.py
1900 #!/usr/bin/env python
1902 import requests, json
1904 # Replace 'localhost' with your FQDN and certificate CN
1905 # for SSL verification
1906 request_url = "https://localhost:5665/v1/objects/services"
1908 'Accept': 'application/json',
1909 'X-HTTP-Method-Override': 'GET'
1912 "attrs": [ "name", "state", "last_check_result" ],
1913 "joins": [ "host.name", "host.state", "host.last_check_result" ],
1914 "filter": "match(\"ping*\", service.name)",
1917 r = requests.post(request_url,
1919 auth=('root', 'icinga'),
1920 data=json.dumps(data),
1921 verify="pki/icinga2-ca.crt")
1923 print "Request URL: " + str(r.url)
1924 print "Status code: " + str(r.status_code)
1926 if (r.status_code == 200):
1927 print "Result: " + json.dumps(r.json())
1930 r.raise_for_status()
1932 $ python icinga2-api-example.py
1935 #### Example API Client in Ruby <a id="icinga2-api-clients-programmatic-examples-ruby"></a>
1937 The following example uses **Ruby** and the `rest_client` gem:
1939 # gem install rest_client
1941 $ vim icinga2-api-example.rb
1945 require 'rest_client'
1947 # Replace 'localhost' with your FQDN and certificate CN
1948 # for SSL verification
1949 request_url = "https://localhost:5665/v1/objects/services"
1951 "Accept" => "application/json",
1952 "X-HTTP-Method-Override" => "GET"
1955 "attrs" => [ "name", "state", "last_check_result" ],
1956 "joins" => [ "host.name", "host.state", "host.last_check_result" ],
1957 "filter" => "match(\"ping*\", service.name)",
1960 r = RestClient::Resource.new(
1961 URI.encode(request_url),
1962 :headers => headers,
1964 :password => "icinga",
1965 :ssl_ca_file => "pki/icinga2-ca.crt")
1968 response = r.post(data.to_json)
1970 response = e.response
1973 puts "Status: " + response.code.to_s
1974 if response.code == 200
1975 puts "Result: " + (JSON.pretty_generate JSON.parse(response.body))
1977 puts "Error: " + response
1980 $ ruby icinga2-api-example.rb
1982 A more detailed example can be found in the [Dashing demo](https://github.com/Icinga/dashing-icinga2).
1984 #### Example API Client in PHP <a id="icinga2-api-clients-programmatic-examples-php"></a>
1986 The following example uses **PHP** and its `curl` library:
1988 $ vim icinga2-api-example.php
1992 # Replace 'localhost' with your FQDN and certificate CN
1993 # for SSL verification
1994 $request_url = "https://localhost:5665/v1/objects/services";
1996 $password = "icinga";
1998 'Accept: application/json',
1999 'X-HTTP-Method-Override: GET'
2002 attrs => array('name', 'state', 'last_check_result'),
2003 joins => array('host.name', 'host.state', 'host.last_check_result'),
2004 filter => 'match("ping*", service.name)',
2008 curl_setopt_array($ch, array(
2009 CURLOPT_URL => $request_url,
2010 CURLOPT_HTTPHEADER => $headers,
2011 CURLOPT_USERPWD => $username . ":" . $password,
2012 CURLOPT_RETURNTRANSFER => true,
2013 CURLOPT_CAINFO => "pki/icinga2-ca.crt",
2014 CURLOPT_POST => count($data),
2015 CURLOPT_POSTFIELDS => json_encode($data)
2018 $response = curl_exec($ch);
2019 if ($response === false) {
2020 print "Error: " . curl_error($ch) . "(" . $response . ")\n";
2023 $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
2025 print "Status: " . $code . "\n";
2028 $response = json_decode($response, true);
2033 $ php icinga2-api-example.php
2035 #### Example API Client in Perl <a id="icinga2-api-clients-programmatic-examples-perl"></a>
2037 The following example uses **Perl** and the `Rest::Client` module:
2039 # perl -MCPAN -e 'install REST::Client'
2040 # perl -MCPAN -e 'install JSON'
2041 # perl -MCPAN -e 'install MIME::Base64'
2042 # perl -MCPAN -e 'install Data::Dumper'
2044 $ vim icinga2-api-example.pl
2055 # Replace 'localhost' with your FQDN and certificate CN
2056 # for SSL verification
2057 my $request_host = "https://localhost:5665";
2058 my $userpass = "root:icinga";
2060 my $client = REST::Client->new();
2061 $client->setHost($request_host);
2062 $client->setCa("pki/icinga2-ca.crt");
2063 $client->addHeader("Accept", "application/json");
2064 $client->addHeader("X-HTTP-Method-Override", "GET");
2065 $client->addHeader("Authorization", "Basic " . encode_base64($userpass));
2067 attrs => ['name', 'state', 'last_check_result'],
2068 joins => ['host.name', 'host.state', 'host.last_check_result'],
2069 filter => 'match("ping*", service.name)',
2071 my $data = encode_json(\%json_data);
2072 $client->POST("/v1/objects/services", $data);
2074 my $status = $client->responseCode();
2075 print "Status: " . $status . "\n";
2076 my $response = $client->responseContent();
2077 if ($status == 200) {
2078 print "Result: " . Dumper(decode_json($response)) . "\n";
2080 print "Error: " . $response . "\n";
2083 $ perl icinga2-api-example.pl