1 # <a id="icinga2-api"></a> Icinga 2 API
3 ## <a id="icinga2-api-introduction"></a> Introduction
5 The Icinga 2 API allows you to manage configuration objects
6 and resources in a simple, programmatic way using HTTP requests.
8 The URL endpoints are logically separated allowing you to easily
11 * run [actions](9-icinga2-api.md#icinga2-api-actions) (reschedule checks, etc.)
12 * query, create, modify and delete [config objects](9-icinga2-api.md#icinga2-api-config-objects)
13 * [manage configuration packages](9-icinga2-api.md#icinga2-api-config-management)
14 * subscribe to [event streams](9-icinga2-api.md#icinga2-api-event-streams)
16 This chapter will start with a general overview followed by
17 detailed information about specific URL endpoints.
19 ### <a id="icinga2-api-requests"></a> Requests
21 Any tool capable of making HTTP requests can communicate with
22 the API, for example [curl](http://curl.haxx.se).
24 Requests are only allowed to use the HTTPS protocol so that
25 traffic remains encrypted.
27 By default the Icinga 2 API listens on port `5665` which is shared with
28 the cluster stack. The port can be changed by setting the `bind_port` attribute
29 in the [ApiListener](6-object-types.md#objecttype-apilistener)
30 configuration object in the `/etc/icinga2/features-available/api.conf`
33 Supported request methods:
37 GET | Retrieve information about configuration objects. Any request using the GET method is read-only and does not affect any objects.
38 POST | Update attributes of a specified configuration object.
39 PUT | Create a new object. The PUT request must include all attributes required to create a new object.
40 DELETE | Remove an object created by the API. The DELETE method is idempotent and does not require any check if the object actually exists.
42 Each URL contains the version string as prefix (currently "/v1").
44 Be prepared to see additional fields being added in future versions. New fields could be added even with minor releases.
45 Modifications to existing fields are considered backward-compatibility-breaking and will only take place in new API versions.
47 The request and response bodies contain a JSON-encoded object.
49 ### <a id="icinga2-api-http-statuses"></a> HTTP Statuses
51 The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt)
52 including error codes.
54 When an error occurs, the response body will contain additional information
55 about the problem and its source.
57 A status code between 200 and 299 generally means that the request was
60 Return codes within the 400 range indicate that there was a problem with the
61 request. Either you did not authenticate correctly, you are missing the authorization
62 for your requested action, the requested object does not exist or the request
65 A status in the range of 500 generally means that there was a server-side problem
66 and Icinga 2 is unable to process your request currently.
69 ### <a id="icinga2-api-responses"></a> Responses
71 Succesful requests will send back a response body containing a `results`
72 list. Depending on the number of affected objects in your request, the
73 results may contain one or more entries.
75 The [output](9-icinga2-api.md#icinga2-api-output-format) will be sent back as a JSON object:
82 "status": "Object was created."
88 ### <a id="icinga2-api-authentication"></a> Authentication
90 There are two different ways for authenticating against the Icinga 2 API:
92 * username and password using HTTP basic auth
95 In order to configure a new API user you'll need to add a new [ApiUser](6-object-types.md#objecttype-apiuser)
96 configuration object. In this example `root` will be the basic auth username
97 and the `password` attribute contains the basic auth password.
99 # vim /etc/icinga2/conf.d/api-users.conf
101 object ApiUser "root" {
105 Alternatively you can use X.509 client certificates by specifying the `client_cn`
106 the API should trust. The X.509 certificate has to be signed by the CA certificate
107 that is configured in the [ApiListener](6-object-types.md#objecttype-apilistener) object.
109 # vim /etc/icinga2/conf.d/api-users.conf
111 object ApiUser "api-clientcn" {
112 password = "CertificateCommonName"
115 An `ApiUser` object can have both methods configured. Sensitive information
116 such as the password will not be exposed through the API itself.
118 New installations of Icinga 2 will automatically set up a new `ApiUser`
119 named `root` with an auto-generated password in the `/etc/icinga2/conf.d/api-users.conf`
122 You can manually invoke the CLI command `icinga2 api setup` which will generate
123 a new local CA, self-signed certificate and a new API user configuration.
125 Once the API user is configured make sure to restart Icinga 2:
127 # service icinga2 restart
129 You can test authentication by sending a GET request to the API:
131 $ curl -u root:icinga -k -s 'https://localhost:5665/v1'
133 In case you get an error message make sure to check the API user credentials.
136 ### <a id="icinga2-api-permissions"></a> Permissions
138 By default an API user does not have any permissions to perform
139 actions on the [URL endpoints](9-icinga2-api.md#icinga2-api-url-endpoints).
141 Permissions for API users must be specified in the `permissions` attribute
142 as array. The array items can be a list of permission strings with wildcard
145 Example for an API user with all permissions:
147 permissions = [ "*" ]
149 A yet more sophisticated approach is to specify additional permissions
150 and their filters. The latter must be defined as [lamdba function](20-language-reference.md#nullary-lambdas)
151 returning a boolean expression.
153 The `permission` attribute contains the action and the specific capitalized
154 object type name. Instead of the type name it is also possible to use a wildcard
157 The following example allows the API user to query all hosts and services with
158 the custom host attribute `os` matching the regular expression `^Linux`.
162 permission = "objects/query/Host"
163 filter = {{ regex("^Linux", host.vars.os) }}
166 permission = "objects/query/Service"
167 filter = {{ regex("^Linux", host.vars.os) }}
172 Available permissions for specific URL endpoints:
174 Permissions | URL Endpoint
175 ------------------------------|---------------
176 actions/<action> | /v1/actions
177 config/query | /v1/config
178 config/modify | /v1/config
179 objects/query/<type> | /v1/objects
180 objects/create/<type> | /v1/objects
181 objects/modify/<type> | /v1/objects
182 objects/delete/<type> | /v1/objects
183 status/query | /v1/status
184 events/<type> | /v1/events
186 The required actions or types can be replaced by using a wildcard match ("*").
189 ### <a id="icinga2-api-parameters"></a> Parameters
191 Depending on the request method there are two ways of
192 passing parameters to the request:
194 * JSON body (`POST`, `PUT`)
195 * Query string (`GET`, `DELETE`)
197 Reserved characters by the HTTP protocol must be passed url-encoded as query string, e.g. a
200 Example for a query string:
202 /v1/objects/hosts?filter=match(%22nbmif*%22,host.name)&attrs=host.name&attrs=host.state
204 Example for a JSON body:
206 { "attrs": { "address": "8.8.4.4", "vars.os" : "Windows" } }
209 #### <a id="icinga2-api-filters"></a> Filters
211 Uses the same syntax as apply rule expressions for filtering specific objects.
213 Example for a filter matching all services in NOT-OK state:
215 https://localhost:5665/v1/objects/services?filter=service.state!=ServiceOK
217 Example for a filter matching all hosts by name (**Note**: `"` are url-encoded as `%22`):
219 https://localhost:5665/v1/objects/hosts?filter=match(%22nbmif*%22,host.name)
221 ### <a id="icinga2-api-url-endpoints"></a> URL Endpoints
223 The Icinga 2 API provides multiple URL endpoints:
225 URL Endpoints | Description
226 --------------|--------------
227 /v1/actions | Endpoint for running specific [API actions](9-icinga2-api.md#icinga2-api-actions).
228 /v1/events | Endpoint for subscribing to [API events](9-icinga2-api.md#icinga2-api-actions).
229 /v1/status | Endpoint for receiving the global Icinga 2 [status and statistics](9-icinga2-api.md#icinga2-api-status).
230 /v1/objects | Endpoint for querying, creating, modifying and deleting [config objects](9-icinga2-api.md#icinga2-api-config-objects).
231 /v1/types | Endpoint for listing Icinga 2 configuration object types and their attributes.
232 /v1/config | Endpoint for [managing configuration modules](9-icinga2-api.md#icinga2-api-config-management).
234 Please check the respective sections for detailed URL information and parameters.
236 ## <a id="icinga2-api-actions"></a> Actions
238 There are several actions available for Icinga 2 provided by the `actions`
239 URL endpoint `/v1/actions`. You can run actions by sending a `POST` request.
241 In case you have been using the [external commands](5-advanced-topics.md#external-commands)
242 in the past, the API actions provide a similar interface with filter
243 capabilities for some of the more common targets which do not directly change
246 Some actions require specific target types (e.g. `type=Host`) and a
247 [filter expression](9-icinga2-api.md#icinga2-api-filters).
248 For each object matching the filter the action in question is performed once.
250 These parameters may either be passed as an URL query string (e.g. url/actions/action-name?list=of¶meters)
251 or as key-value pairs in a JSON-formatted payload or a mix of both.
253 All actions return a 200 `OK` or an appropriate error code for each
254 action performed on each object matching the supplied filter.
256 ### <a id="icinga2-api-actions-process-check-result"></a> process-check-result
258 Send a `POST` request to the URL endpoint `/v1/actions/process-check-result`.
260 Parameter | Type | Description
261 ------------------|--------------|--------------
262 type | string | **Required.** `Host` or `Service`.
263 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
264 exit\_status | integer | **Required.** For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=OK, 1=CRITICAL.
265 plugin\_output | string | **Required.** The plugins main output, i.e. the text before the `|`. Does **not** contain the perfomance data.
266 performance\_data | string array | **Optional.** One array entry per `;` separated block.
267 check\_command | string 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.
268 check\_source | string | **Optional.** Usually the name of the `command_endpoint`
270 This is used to submit a passive check result for a service or host. Passive
271 checks need to be enabled for the check result to be processed.
275 $ curl -u root:icinga -k -X POST "https://localhost:5665/v1/actions/process-check-result?type=Service&filter=service.name==%22ping6%22" -d \
276 "{\"exit_status\":2,\"plugin_output\":\"IMAGINARY CHECK\",\"performance_data\":[\"This is just\", \"a drill\"],\"check_command\":[\"some/path\", \"--argument\", \"words\"]}" \
281 "code":200.0,"status":"Successfully processed check result for object icinga!ping6."
286 ### <a id="icinga2-api-actions-reschedule-check"></a> reschedule-check
288 Send a `POST` request to the URL endpoint `/v1/actions/reschedule-check`.
290 Parameter | Type | Description
291 -------------|-----------|--------------
292 type | string | **Required.** `Host` or `Service`.
293 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
294 next\_check | timestamp | **Optional.** The next check will be run at this timestamp. Defaults to `now`.
295 force\_check | boolean | **Optional.** Defaults to `false`. See blow for further information.
297 If the `forced_check` flag is set the checks are performed regardless of what
298 time it is (i.e. time period restrictions are ignored) and whether or not active
299 checks are enabled on a host/service-specific or program-wide basis.
303 $ curl -u root:icinga -k -X POST "https://localhost:5665/v1/actions/reschedule-check?type=Service&filter=service.name==%22ping6%22" -d \
304 "{\"force_check\":true}"
309 "code":200.0,"status":"Successfully rescheduled check for icinga!ping6."
314 This will reschedule all services with the name "ping6" to perform a check now
315 (`next_check` default), ignoring any time periods or whether active checks are
316 allowed for the service (`force_check=true`).
318 ### <a id="icinga2-api-actions-send-custom-notification"></a> send-custom-notification
320 Send a `POST` request to the URL endpoint `/v1/actions/send-custom-notification`.
322 Parameter | Type | Description
323 ----------|---------|--------------
324 type | string | **Required.** `Host` or `Service`.
325 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
326 author | string | **Required.** Name of the author, may be empty.
327 comment | string | **Required.** Comment text, may be empty.
328 force | boolean | **Optional.** Default: false. If true, the notification is sent regardless of downtimes or whether notifications are enabled or not.
330 ### <a id="icinga2-api-actions-delay-notification"></a> delay-notification
332 Send a `POST` request to the URL endpoint `/v1/actions/delay-notification`.
334 Parameter | Type | Description
335 ----------|-----------|--------------
336 type | string | **Required.** `Host` or `Service`.
337 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
338 timestamp | timestamp | **Required.** Delay notifications until this timestamp.
340 Note that this will only have an effect if the service stays in the same problem
341 state that it is currently in. If the service changes to another state, a new
342 notification may go out before the time you specify in the `timestamp` argument.
344 ### <a id="icinga2-api-actions-acknowledge-problem"></a> acknowledge-problem
346 Send a `POST` request to the URL endpoint `/v1/actions/acknowledge-problem`.
348 Parameter | Type | Description
349 ----------|-----------|--------------
350 type | string | **Required.** `Host` or `Service`.
351 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
352 author | string | **Required.** Name of the author, may be empty.
353 comment | string | **Required.** Comment text, may be empty.
354 expiry | timestamp | **Optional.** If set the acknowledgement will vanish after this timestamp.
355 sticky | boolean | **Optional.** If `true`, the default, the acknowledgement will remain until the service or host fully recovers.
356 notify | boolean | **Optional.** If `true` a notification will be sent out to contacts to indicate this problem has been acknowledged. The default is false.
358 Allows you to acknowledge the current problem for hosts or services. By
359 acknowledging the current problem, future notifications (for the same state)
362 The following example acknowledges all services which are in a hard critical state and sends out
363 a notification for them:
365 $ curl -u root:icinga -k -X POST "https://localhost:5665/v1/actions/acknowledge-problem?type=Service&filter=service.state==2&service.state_type=1" -d \
366 "{\"author\":\"J. D. Salinger\",\"comment\":\"I thought what I'd do was I'd pretend I was one of those deaf-mutes\",\"notify\":true }"
370 {"code":200.0,"name":"icinga!down","status":"Attributes updated.","type":"Service"},
371 {"code":200.0,"name":"icinga!ssh","status":"Attributes updated.","type":"Service"}
375 ### <a id="icinga2-api-actions-remove-acknowledgement"></a> remove-acknowledgement
377 Send a `POST` request to the URL endpoint `/v1/actions/remove-acknowledgement`.
379 parameter | type | description
380 ----------|--------|--------------
381 type | string | **Required.** `Host` or `Service`.
382 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
384 Remove the acknowledgements for services or hosts. Once the acknowledgement has
385 been removed notifications will be sent out again.
387 ### <a id="icinga2-api-actions-add-comment"></a> add-comment
389 Send a `POST` request to the URL endpoint `/v1/actions/add-comment`.
391 parameter | type | description
392 ----------|--------|--------------
393 type | string | **Required.** `Host` or `Service`.
394 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
395 author | string | **Required.** name of the author, may be empty.
396 comment | string | **Required.** Comment text, may be empty.
398 Adds a `comment` by `author` to services or hosts.
400 ### <a id="icinga2-api-actions-remove-all-comments"></a> remove-all-comments
402 Send a `POST` request to the URL endpoint `/v1/actions/remove-all-comments`.
404 parameter | type | description
405 ------------|---------|--------------
406 type | string | **Required.** `Host` or `Service`.
407 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
409 Removes all comments for services or hosts.
411 ### <a id="icinga2-api-actions-remove-comment-by-id"></a> remove-comment-by-id
413 Send a `POST` request to the URL endpoint `/v1/actions/remove-comment-by-id`.
415 parameter | type | description
416 ------------|---------|--------------
417 comment\_id | integer | **Required.** ID of the comment to remove.
419 Does not support a target type or filters.
421 Tries to remove the comment with the ID `comment_id`, returns `OK` if the
422 comment did not exist.
423 **Note**: This is **not** the legacy ID but the comment ID returned by Icinga 2 itself.
425 ### <a id="icinga2-api-actions-schedule-downtime"></a> schedule-downtime
427 Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`.
429 parameter | type | description
430 ------------|-----------|--------------
431 type | string | **Required.** `Host` or `Service`.
432 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
433 start\_time | timestamp | **Required.** Timestamp marking the begining of the downtime.
434 end\_time | timestamp | **Required.** Timestamp marking the end of the downtime.
435 duration | integer | **Required.** Duration of the downtime in seconds if `fixed` is set to false.
436 fixed | boolean | **Optional.** Defaults to `false`. If true the downtime is `fixed` otherwise `flexible`. See [downtimes](5-advanced-topics.md#Downtimes) for more information.
437 trigger\_id | integer | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](5-advanced-topics.md#Downtimes) for more information on triggered downtimes.
441 $ curl -u root:icinga -k -X POST "https://localhost:5665/v1/actions/schedule-downtime?type=Host&filter=host.name=%22icinga2b%22" -d \
442 "{\"start_time\":`date "+%s"`, \"end_time\":`date --date="next monday" "+%s"`,\"duration\":0,\"author\":\"Lazy admin\",\"comment\":\"Don't care until next monday\"}"
448 "downtime_id":"icinga2b-1445861488-1",
450 "status":"Successfully scheduled downtime with id 39 for object icinga2b."
456 ### <a id="icinga2-api-actions-remove-downtime"></a> remove-downtime
458 Send a `POST` request to the URL endpoint `/v1/actions/remove-all-downtimes`.
460 parameter | type | description
461 ----------|--------|--------------
462 type | string | **Required.** `Host` or `Service`.
463 filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api#icinga2-api-filters).
465 Removes all downtimes for services or hosts.
467 ### <a id="icinga2-api-actions-remove-downtime-by-id"></a> remove-downtime-by-id
469 Send a `POST` request to the URL endpoint `/v1/actions/remove-downtime-by-id`.
471 parameter | type | description
472 -------------|---------|--------------
473 downtime\_id | integer | **Required.** ID of the downtime to remove.
475 Does not support a target type or filter.
477 Tries to remove the downtime with the ID `downtime_id`, returns `OK` if the
478 downtime did not exist.
479 **Note**: This is **not** the legacy ID but the downtime ID returned by Icinga 2 itself.
481 ### <a id="icinga2-api-actions-shutdown-process"></a> shutdown-process
483 Send a `POST` request to the URL endpoint `/v1/actions/shutdown-process`.
485 This action does not support a target type or filter.
487 Shuts down Icinga2. May or may not return.
489 ### <a id="icinga2-api-actions-restart-process"></a> restart-process
491 Send a `POST` request to the URL endpoint `/v1/actions/restart-process`.
493 This action does not support a target type or filter.
495 Restarts Icinga2. May or may not return.
498 ## <a id="icinga2-api-event-streams"></a> Event Streams
500 You can subscribe to event streams by sending a `POST` request to the URL endpoint `/v1/events`.
501 The following parameters need to be passed as URL parameters:
503 Parameters | Description
504 -----------|--------------
505 types | **Required.** Event type(s). Multiple types as URL parameters are supported.
506 queue | **Required.** Unique queue name. Multiple HTTP clients can use the same queue with existing filters.
507 filter | **Optional.** Filter for specific event attributes using [filter expressions](9-icinga2-api.md#icinga2-api-filters).
510 ### <a id="icinga2-api-event-streams-types"></a> Event Stream Types
512 The following event stream types are available:
515 -----------------------|--------------
516 CheckResult | Check results for hosts and services.
517 StateChange | Host/service state changes.
518 Notification | Notification events including notified users for hosts and services.
519 AcknowledgementSet | Acknowledgement set on hosts and services.
520 AcknowledgementCleared | Acknowledgement cleared on hosts and services.
521 CommentAdded | Comment added for hosts and services.
522 CommentRemoved | Comment removed for hosts and services.
523 DowntimeAdded | Downtime added for hosts and services.
524 DowntimeRemoved | Downtime removed for hosts and services.
525 DowntimeTriggered | Downtime triggered for hosts and services.
527 Note: Each type requires [api permissions](9-icinga2-api.md#icinga2-api-permissions)
530 Example for all downtime events:
532 &types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered
535 ### <a id="icinga2-api-event-streams-filter"></a> Event Stream Filter
537 Event streams can be filtered by attributes using the prefix `event.`.
539 Example for the `CheckResult` type with the `exit_code` set to `2`:
541 &types=CheckResult&filter=event.check_result.exit_status==2
543 Example for the `CheckResult` type with the service matching the string "random":
545 &types=CheckResult&filter=match%28%22random*%22,event.service%29
548 ### <a id="icinga2-api-event-streams-response"></a> Event Stream Response
550 The event stream response is separated with new lines. The HTTP client
551 must support long-polling and HTTP/1.1. HTTP/1.0 is not supported.
555 $ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=michi&types=CheckResult&filter=event.check_result.exit_status==2'
557 {"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421319.7226390839,"type":"CheckResult"}
558 {"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421324.7226390839,"type":"CheckResult"}
559 {"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421329.7226390839,"type":"CheckResult"}
562 ## <a id="icinga2-api-status"></a> Status and Statistics
564 Send a `POST` request to the URL endpoint `/v1/status` for retrieving the
565 global status and statistics.
567 Contains a list of sub URL endpoints which provide the status and statistics
568 of available and enabled features. Any filters are ignored.
570 Example for the main URL endpoint `/v1/status`:
572 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status' | python -m json.tool
576 "name": "ApiListener",
582 "name": "IcingaAplication",
590 `/v1/status` is always available as virtual status URL endpoint.
591 It provides all feature status information in a collected overview.
593 Example for the icinga application URL endpoint `/v1/status/IcingaApplication`:
595 $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication' | python -m json.tool
601 "icingaapplication": {
603 "enable_event_handlers": true,
604 "enable_flapping": true,
605 "enable_host_checks": true,
606 "enable_notifications": true,
607 "enable_perfdata": true,
608 "enable_service_checks": true,
609 "node_name": "icinga.org",
611 "program_start": 1443019345.093372,
612 "version": "v2.3.0-573-g380a131"
621 ## <a id="icinga2-api-config-objects"></a> Config Objects
623 Provides functionality for all configuration object URL endpoints
624 provided by [config object types](6-object-types.md#object-types):
626 URL Endpoints | Description
627 ---------------------------------|--------------
628 /v1/objects/hosts | Endpoint for retrieving and updating [Host](6-object-types.md#objecttype-host) objects.
629 /v1/objects/services | Endpoint for retrieving and updating [Service](6-object-types.md#objecttype-service) objects.
630 /v1/objects/notifications | Endpoint for retrieving and updating [Notification](6-object-types.md#objecttype-notification) objects.
631 /v1/objects/dependencies | Endpoint for retrieving and updating [Dependency](6-object-types.md#objecttype-dependency) objects.
632 /v1/objects/users | Endpoint for retrieving and updating [User](6-object-types.md#objecttype-user) objects.
633 /v1/objects/checkcommands | Endpoint for retrieving and updating [CheckCommand](6-object-types.md#objecttype-checkcommand) objects.
634 /v1/objects/eventcommands | Endpoint for retrieving and updating [EventCommand](6-object-types.md#objecttype-eventcommand) objects.
635 /v1/objects/notificationcommands | Endpoint for retrieving and updating [NotificationCommand](6-object-types.md#objecttype-notificationcommand) objects.
636 /v1/objects/hostgroups | Endpoint for retrieving and updating [HostGroup](6-object-types.md#objecttype-hostgroup) objects.
637 /v1/objects/servicegroups | Endpoint for retrieving and updating [ServiceGroup](6-object-types.md#objecttype-servicegroup) objects.
638 /v1/objects/usergroups | Endpoint for retrieving and updating [UserGroup](6-object-types.md#objecttype-usergroup) objects.
639 /v1/objects/zones | Endpoint for retrieving and updating [Zone](6-object-types.md#objecttype-zone) objects.
640 /v1/objects/endpoints | Endpoint for retrieving and updating [Endpoint](6-object-types.md#objecttype-endpoint) objects.
641 /v1/objects/timeperiods | Endpoint for retrieving and updating [TimePeriod](6-object-types.md#objecttype-timeperiod) objects.
643 All object attributes are prefixed with their respective object type.
649 Output listing and url parameters use the same syntax.
652 ### <a id="icinga2-api-config-objects-joins"></a> API Objects and Joins
654 Icinga 2 knows about object relations, i.e. when querying a service object
655 the query handler will automatically add the referenced host object and its
656 attributes to the result set. If the object reference is null (e.g. when no
657 event\_command is defined), the joined results not added to the result set.
659 **Note**: Select your required attributes beforehand by passing them to your
660 request. The default result set might get huge.
662 Each joined object will use its own attribute name as prefix for the attribute.
663 There is an exception for multiple objects used in dependencies and zones.
665 Objects with optional relations (e.g. host notifications without a service)
668 Object Type | Object Relations (prefix name)
669 -------------|---------------------------------
670 Service | host, notification, check\_command, event\_command
671 Host | notification, check\_command, event\_command
672 Notification | host, service, command, period
673 Dependency | child\_host, child\_service, parent\_host, parent\_service, period
678 ### <a id="icinga2-api-config-objects-cluster-sync"></a> API Objects and Cluster Config Sync
680 Newly created or updated objects can be synced throughout your
681 Icinga 2 cluster. Set the `zone` attribute to the zone this object
682 belongs to and let the API and cluster handle the rest.
683 Objects without zone attribute are only synced in the same (HA) zone.
687 > Cluster nodes must accept configuration for creating, modifying
688 > and deleting objects. Ensure that `accept_config` is set to `true`
689 > in the [ApiListener](6-object-types.md#objecttype-apilistener) object
692 If you add a new cluster instance, or boot an instance which has been offline
693 for a while, Icinga 2 takes care of the initial object sync for all objects
696 More information about distributed monitoring, cluster and its
697 configuration can be found [here](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability).
700 ### <a id="icinga2-api-config-objects-list"></a> List All Objects
702 Send a `GET` request to `/v1/objects/hosts` to list all host objects and
705 $ curl -u root:icinga -k -s 'https://localhost:5665/v1/objects/hosts'
707 This works in a similar fashion for other [config objects](9-icinga2-api.md#icinga2-api-config-objects).
710 #### <a id="icinga2-api-objects-create"></a> Create New Config Object
712 New objects must be created by sending a PUT request. The following
713 parameters need to be passed inside the JSON body:
715 Parameters | Description
716 -----------|--------------
717 name | **Required.** Name of the newly created config object.
718 templates | **Optional.** Import existing configuration templates for this object type.
719 attrs | **Required.** Set specific object attributes for this [object type](6-object-types.md#object-types).
722 If attributes are of the Dictionary type, you can also use the indexer format:
724 "attrs": { "vars.os": "Linux" }
726 Example fo creating the new host object `google.com`:
728 $ curl -u root:icinga -k -s 'https://localhost:5665/v1/objects/hosts/google.com' \
730 -d '{ "templates": [ "generic-host" ], "attrs": { "address": "8.8.8.8", "check_command": "hostalive", "vars.os" : "Linux" } }' \
731 | python -m json.tool
736 "status": "Object was created."
741 **Note**: Host objects require the `check_command` attribute.
743 If the configuration validation fails, the new object will not be created and the response body
744 contains a detailed error message. The following example omits the `check_command` attribute required
747 $ curl -u root:icinga -k -s 'https://localhost:5665/v1/objects/hosts/google.com' \
749 -d '{ "attrs": { "address": "8.8.8.8", "vars.os" : "Linux" } }' \
750 | python -m json.tool
756 "Error: Validation failed for object 'google.com' of type 'Host'; Attribute 'check_command': Attribute must not be empty."
758 "status": "Object could not be created."
764 #### <a id="icinga2-api-object-query"></a> Query Object
766 Send a `GET` request including the object name inside the URL.
768 Example for the host `google.com`:
770 $ curl -u root:icinga -k -s 'https://localhost:5665/v1/objects/hosts/google.com'
772 You can select specific attributes by adding them as url parameters using `?attrs=...`. Multiple
773 attributes must be added one by one, e.g. `?attrs=host.address&attrs=host.name`.
775 $ curl -u root:icinga -k -s 'https://localhost:5665/v1/objects/hosts/google.com?attrs=host.name&attrs=host.address' | python -m json.tool
780 "host.address": "8.8.8.8",
781 "host.name": "google.com"
788 #### <a id="icinga2-api-objects-modify"></a> Modify Object
790 Existing objects must be modified by sending a `POST` request. The following
791 parameters need to be passed inside the JSON body:
793 Parameters | Description
794 -----------|--------------
795 name | **Optional.** If not specified inside the url, this is **Required.**.
796 templates | **Optional.** Import existing object configuration templates.
797 attrs | **Required.** Set specific object attributes for this [object type](6-object-types.md#object-types).
800 If attributes are of the Dictionary type, you can also use the indexer format:
802 "attrs": { "vars.os": "Linux" }
805 Example for existing object `google.com`:
807 $ curl -u root:icinga -k -s 'https://localhost:5665/v1/objects/hosts/google.com' \
809 -d '{ "attrs": { "address": "8.8.4.4", "vars.os" : "Windows" } }' \
810 | python -m json.tool
815 "name": "google.com",
816 "status": "Attributes updated.",
823 #### <a id="icinga2-api-hosts-delete"></a> Delete Host
825 You can delete objects created using the API by sending a `DELETE`
826 request. Specify the object name inside the url.
828 Parameters | Description
829 -----------|--------------
830 cascade | **Optional.** Delete objects depending on the deleted objects (e.g. services on a host).
832 **Note**: Objects created by apply rules (services, notifications, etc) will implicitely require
833 to pass the `cascade` parameter on host object deletion.
835 Example for deleting the host object `google.com`:
837 $ curl -u root:icinga -k -s 'https://localhost:5665/v1/objects/hosts/google.com?cascade=1' -X DELETE | python -m json.tool
842 "name": "google.com",
843 "status": "Object was deleted.",
850 ## <a id="icinga2-api-config-management"></a> Configuration Management
852 The main idea behind configuration management is to allow external applications
853 creating configuration packages and stages based on configuration files and
854 directory trees. This replaces any additional SSH connection and whatnot to
855 dump configuration files to Icinga 2 directly.
856 In case you are pushing a new configuration stage to a package, Icinga 2 will
857 validate the configuration asynchronously and populate a status log which
858 can be fetched in a separated request.
861 ### <a id="icinga2-api-config-management-create-package"></a> Create Config Package
863 Send a `POST` request to a new config package called `puppet` in this example. This
864 will create a new empty configuration package.
866 $ curl -k -s -u root:icinga -X POST https://localhost:5665/v1/config/packages/puppet | python -m json.tool
872 "status": "Created package."
878 ### <a id="icinga2-api-config-management-create-config-stage"></a> Create Configuration to Package Stage
880 Send a `POST` request to the URL endpoint `/v1/config/stages` including an existing
881 configuration package, e.g. `puppet`.
882 The request body must contain the `files` attribute with the value being
883 a dictionary of file targets and their content.
885 The example below will create a new file called `test.conf` underneath the `conf.d`
886 directory populated by the sent configuration.
887 The Icinga 2 API returns the `package` name this stage was created for, and also
888 generates a unique name for the `package` attribute you'll need for later requests.
890 Note: This example contains an error (`chec_command`), do not blindly copy paste it.
892 $ curl -k -s -u root:icinga -X POST -d '{ "files": { "conf.d/test.conf": "object Host \"cfg-mgmt\" { chec_command = \"dummy\" }" } }' https://localhost:5665/v1/config/stages/puppet | python -m json.tool
898 "stage": "nbmif-1441625839-0",
899 "status": "Created stage."
904 If the configuration fails, the old active stage will remain active.
905 If everything is successful, the new config stage is activated and live.
906 Older stages will still be available in order to have some sort of revision
909 Icinga 2 automatically creates the following files in the main configuration package
913 ------------|--------------
914 status | Contains the [configuration validation](8-cli-commands.md#config-validation) exit code (everything else than 0 indicates an error).
915 startup.log | Contains the [configuration validation](8-cli-commands.md#config-validation) output.
917 You can [fetch these files](9-icinga2-api.md#icinga2-api-config-management-fetch-config-package-stage-files) via API call
918 after creating a new stage.
921 ### <a id="icinga2-api-config-management-list-config-packages"></a> List Configuration Packages and their Stages
923 List all config packages, their active stage and other stages.
924 That way you may iterate of all of them programmatically for
925 older revisions and their requests.
927 The following example contains one configuration package `puppet`.
928 The latter already has a stage created, but it is not active.
930 $ curl -k -s -u root:icinga https://localhost:5665/v1/config/packages | python -m json.tool
944 ### <a id="icinga2-api-config-management-list-config-package-stage-files"></a> List Configuration Packages and their Stages
946 Sent a `GET` request to the URL endpoint `/v1/config/stages` including the package
947 (`puppet`) and stage (`nbmif-1441625839-0`) name.
949 $ curl -k -s -u root:icinga https://localhost:5665/v1/config/stages/puppet/nbmif-1441625839-0 | python -m json.tool
954 "name": "startup.log",
970 "name": "conf.d/test.conf",
977 ### <a id="icinga2-api-config-management-fetch-config-package-stage-files"></a> Fetch Configuration Package Stage Files
979 Send a `GET` request to the URL endpoint `/v1/config/files` including
980 the package name, the stage name and the relative path to the file.
981 Note: You cannot use dots in paths.
983 You can fetch a [list of existing files](9-icinga2-api.md#icinga2-api-config-management-list-config-package-stage-files)
984 in a configuration stage and then specifically request their content.
986 The following example fetches the faulty configuration inside `conf.d/test.conf`
987 for further analysis.
989 $ curl -k -s -u root:icinga https://localhost:5665/v1/config/files/puppet/nbmif-1441625839-0/conf.d/test.conf
990 object Host "cfg-mgmt" { chec_command = "dummy" }
992 Note: The returned files are plain-text instead of JSON-encoded.
995 ### <a id="icinga2-api-config-management-config-package-stage-errors"></a> Configuration Package Stage Errors
997 Now that we don’t have an active stage for `puppet` yet seen [here](9-icinga2-api.md#icinga2-api-config-management-list-config-packages),
998 there must have been an error.
1000 Fetch the `startup.log` file and check the config validation errors:
1002 $ curl -k -s -u root:icinga https://localhost:5665/v1/config/files/puppet/imagine-1441133065-1/startup.log
1005 critical/config: Error: Attribute 'chec_command' does not exist.
1007 /var/lib/icinga2/api/packages/puppet/imagine-1441133065-1/conf.d/test.conf(1): object Host "cfg-mgmt" { chec_command = "dummy" }
1008 ^^^^^^^^^^^^^^^^^^^^^^
1010 critical/config: 1 error
1012 The output is similar to the manual [configuration validation](8-cli-commands.md#config-validation).