From 31170db12349f67b48b56f67342225a19e0f34e3 Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Fri, 12 Apr 2019 12:49:41 +0200 Subject: [PATCH] Improve REST API docs - Better explanation for filters and filter_vars - Update examples to use filters in the body only, don't fuck around with the URL parameters. - Better explain actions and their intent - More insights into config packages and their intention - Improve API clients and add the tables from icinga2-api-examples - Formatting for CLI requests --- doc/11-cli-commands.md | 4 +- doc/12-icinga2-api.md | 541 +++++++++++++++++++++++++---------- doc/19-technical-concepts.md | 2 +- 3 files changed, 397 insertions(+), 150 deletions(-) diff --git a/doc/11-cli-commands.md b/doc/11-cli-commands.md index 5b58c4c52..46c6e718c 100644 --- a/doc/11-cli-commands.md +++ b/doc/11-cli-commands.md @@ -22,7 +22,7 @@ Supported commands: * api setup (setup for API) * ca list (lists all certificate signing requests) * ca sign (signs an outstanding certificate request) - * console (Icinga console) + * console (Icinga debug console) * daemon (starts Icinga 2) * feature disable (disables specified feature) * feature enable (enables specified feature) @@ -272,7 +272,7 @@ are required for executing config expressions and auto-completion. > **Note** > -> The debug console does not currently support SSL certificate verification. +> The debug console does not currently support TLS certificate verification. > > Runtime modifications are not validated and might cause the Icinga 2 > daemon to crash or behave in an unexpected way. Use these runtime changes diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md index bfeca45fb..0984fb6be 100644 --- a/doc/12-icinga2-api.md +++ b/doc/12-icinga2-api.md @@ -14,12 +14,12 @@ certificates as well as a new API user `root` with an auto-generated password in Make sure to restart Icinga 2 to enable the changes you just made: ``` -# service icinga2 restart +# systemctl restart icinga2 ``` If you prefer to set up the API manually, you will have to perform the following steps: -* Set up X.509 certificates for Icinga 2 +* Set up X.509 TLS certificates for Icinga 2 * Enable the `api` feature (`icinga2 feature enable api`) * Create an `ApiUser` object for authentication @@ -62,7 +62,7 @@ Supported request methods: PUT | Create a new object. The PUT request must include all attributes required to create a new object. DELETE | Remove an object created by the API. The DELETE method is idempotent and does not require any check if the object actually exists. -All requests apart from `GET` require that the following `Accept` header is set: +All requests except `GET` require the following `Accept` header: ``` Accept: application/json @@ -70,7 +70,7 @@ Accept: application/json Each URL is prefixed with the API version (currently "/v1"). -HTTP header size is limited to 8KB. +HTTP header size is limited to 8KB per request. ### Responses @@ -93,15 +93,25 @@ The output will be sent back as a JSON object: > **Tip** > -> You can use the [pretty](12-icinga2-api.md#icinga2-api-parameters-global) parameter to beautify the JSON response with Icinga v2.9+. +> You can use the [pretty](12-icinga2-api.md#icinga2-api-parameters-global) parameter to beautify the JSON response. You can also use [jq](https://stedolan.github.io/jq/) or `python -m json.tool` in combination with curl on the CLI. ``` +curl ... | jq curl ... | python -m json.tool ``` +jq also has additional filter capabilities, as shown in [this blogpost](https://www.netways.de/blog/2018/08/24/json-in-bequem/). + +``` +curl ... |jq '{name: .results[].name}' +``` + +For programmatic examples in various languages, check the chapter +[below](12-icinga2-api.md#icinga2-api-clients). + > **Note** > > Future versions of Icinga 2 might set additional fields. Your application @@ -132,8 +142,8 @@ and Icinga 2 is unable to process your request. There are two different ways for authenticating against the Icinga 2 API: -* username and password using HTTP basic auth -* X.509 certificate +* Username and password using HTTP basic auth +* X.509 client certificate In order to configure a new API user you'll need to add a new [ApiUser](09-object-types.md#objecttype-apiuser) configuration object. In this example `root` will be the basic auth username @@ -161,6 +171,8 @@ object ApiUser "root" { An `ApiUser` object can have both authentication methods configured. +#### Authentication Test + You can test authentication by sending a GET request to the API: ``` @@ -236,6 +248,12 @@ permissions = [ More information about filters can be found in the [filters](12-icinga2-api.md#icinga2-api-filters) chapter. +Prior to setting complex permissions, ensure to always [test](12-icinga2-api.md#icinga2-api-authentication-test) +them step by step. + + +#### Overview + Permissions are tied to a maximum HTTP request size to prevent abuse, responses sent by Icinga are not limited. An API user with all permissions ("\*") may send up to 512 MB regardless of the endpoint. @@ -259,6 +277,7 @@ Available permissions for specific URL endpoints: The required actions or types can be replaced by using a wildcard match ("\*"). + ### Parameters Depending on the request method there are two ways of passing parameters to the request: @@ -284,6 +303,10 @@ Here are the exact same query parameters as a JSON object: The [match function](18-library-reference.md#global-functions-match) is available as global function in Icinga 2. +Whenever filters and other URL parameters don't work due to encoding issues, +consider passing them in the request body. For GET requests, this method is explained +[here](12-icinga2-api.md#icinga2-api-requests-method-override). + ### Global Parameters Name | Description @@ -303,8 +326,6 @@ Example as JSON object: { "pretty": true } ``` -Both parameters have been added in Icinga 2 v2.9. - ### Request Method Override `GET` requests do not allow you to send a request body. In case you cannot pass everything as URL @@ -314,13 +335,27 @@ header. This comes in handy when you are using HTTP proxies disallowing `PUT` or Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header: ``` -$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -X POST -H 'X-HTTP-Method-Override: GET' 'https://localhost:5665/v1/objects/hosts' +$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' \ + -H 'X-HTTP-Method-Override: GET' -X POST \ + 'https://localhost:5665/v1/objects/hosts' ``` Delete an existing object by sending a `POST` request with `X-HTTP-Method-Override: DELETE` as request header: ``` -$ 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' +$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' \ + -H 'X-HTTP-Method-Override: DELETE' -X POST \ + 'https://localhost:5665/v1/objects/hosts/example.localdomain' +``` + +Query objects with complex filters. For a detailed introduction into filter, please +read the [following chapter](12-icinga2-api.md#icinga2-api-filters). + +``` +curl -k -s -u 'root:icinga' -H 'Accept: application/json' \ + -H 'X-HTTP-Method-Override: GET' -X POST \ + 'https://localhost:5665/v1/objects/services' \ + -d '{ "filter": "service.state==2 && match(\"ping*\",service.name)" }' ``` ### Filters @@ -366,7 +401,11 @@ The full name of an object can be obtained by looking at the `__name` attribute. Most of the information provided in this chapter applies to both permission filters (as used when configuring `ApiUser` objects) and filters specified in queries. -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). +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). + +The `filter` parameter can only be specified once, complex filters must +be defined once in the provided string value. > **Note** > @@ -390,6 +429,11 @@ Example for all hosts which are in the host group `linux-servers`: https://localhost:5665/v1/objects/hosts?filter="linux-servers" in host.groups ``` +> **Tip** +> +> Best practice for filters is to use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) +> for GET requests and always pass them in the request body. + User-specified filters are run in a sandbox environment which ensures that filters cannot modify Icinga's state, for example object attributes or global variables. @@ -411,21 +455,40 @@ action which can be used for both hosts and services. When using advanced filter type using the `type` parameter: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/reschedule-check' \ --d '{ "type": "Service", "filter": "service.name==\"ping6\"", "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \ + 'https://localhost:5665/v1/actions/reschedule-check' \ + -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "pretty": true }' ``` -When building filters you have to ensure that values such as -`"linux-servers"` are escaped properly according to the rules of the Icinga 2 configuration -language. +##### Filter Variables -To make using the API in scripts easier you can use the `filter_vars` attribute to specify -variables which should be made available to your filter expression. This way you don't have -to worry about escaping values: +Filter values need to be escaped in the same way as in the Icinga 2 DSL. + +The example below is not valid: ``` -$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/hosts' \ --d '{ "filter": "host.vars.os == os", "filter_vars": { "os": "Linux" }, "pretty": true }' +-d '{ "type": "Host", "filter": ""linux-servers" in host.groups" }' +``` + +The double quotes need to be escaped with a preceeding backslash: + +``` +-d '{ "type": "Host", "filter": "\"linux-servers\" in host.groups" }' +``` + +You can use the `filter_vars` attribute to avoid additional escaping. +This follows the same principle as with parameter binding known from RDBMS. +Specify a placeholder variable inside the `filter` string, and actually +assign its value inside the `filter_vars` dictionary. + +That way you can also keep the `filter` string the same for different +requests with only changing the `filter_vars`. + +``` +$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' \ + -H 'X-HTTP-Method-Override: GET' -X POST \ + 'https://localhost:5665/v1/objects/hosts' \ + -d '{ "filter": "group in host.groups", "filter_vars": { "group": "linux-servers" }, "pretty": true }' ``` We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) here because @@ -434,6 +497,16 @@ the HTTP specification does not allow message bodies for GET requests. The `filters_vars` attribute can only be used inside the request body, but not as a URL parameter because there is no way to specify a dictionary in a URL. +The example from [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) +can be enhanced to avoid additional parameter value escaping. + +``` +curl -k -s -u 'root:icinga' -H 'Accept: application/json' \ + -H 'X-HTTP-Method-Override: GET' -X POST \ + 'https://localhost:5665/v1/objects/services' \ + -d '{ "filter": "service.state==state && match(pattern,service.name)", "filter_vars": { "state": 2, "pattern": "ping*" } }' +``` + ## Config Objects Provides methods to manage configuration objects: @@ -611,6 +684,18 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/services?attrs=di } ``` +> **Tip** +> +> Use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) +> and pass everything in the request body like this: + +``` +$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' \ + -H 'X-HTTP-Method-Override: GET' -X POST \ + 'https://localhost:5665/v1/objects/services' \ + -d '{ "attrs": [ "display_name", "check_command" ], "joins": [ "host.name", "host.address" ], "filter": "host.vars.os==\"Linux\"", "pretty": true }' +``` + In case you want to fetch all [comments](09-object-types.md#objecttype-comment) for hosts and services, you can use the following query URL (similar example for downtimes): @@ -624,7 +709,9 @@ and no downtime or acknowledgement set). We're using [X-HTTP-Method-Override](12 here because we want to pass all query attributes in the request body. ``` -$ 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' \ +$ 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' \ -d '{ "joins": [ "host.name", "host.address" ], "attrs": [ "name", "state", "downtime_depth", "acknowledgement" ], "filter": "service.state != ServiceOK && service.downtime_depth == 0.0 && service.acknowledgement == 0.0", "pretty": true }' { @@ -655,8 +742,10 @@ URL endpoint with `joins` and `filter` request parameters using the [X-HTTP-Meth method: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/comments' \ --d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0", "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -H 'X-HTTP-Method-Override: GET' -X POST \ + 'https://localhost:5665/v1/objects/comments' \ + -d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0", "pretty": true }' { "results": [ @@ -703,8 +792,9 @@ If attributes are of the Dictionary type, you can also use the indexer format. T Example for creating the new host object `example.localdomain`: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \ --d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" }, "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \ + -d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" }, "pretty": true }' { "results": [ { @@ -720,8 +810,9 @@ contains a detailed error message. The following example is missing the `check_c which is required for host objects: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \ --d '{ "attrs": { "address": "192.168.1.1", "vars.os" : "Linux" }, "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \ + -d '{ "attrs": { "address": "192.168.1.1", "vars.os" : "Linux" }, "pretty": true }' { "results": [ { @@ -738,15 +829,17 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localh Service objects must be created using their full name ("hostname!servicename") referencing an existing host object: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/services/example.localdomain!realtime-load' \ --d '{ "templates": [ "generic-service" ], "attrs": { "check_command": "load", "check_interval": 1,"retry_interval": 1 } }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X PUT 'https://localhost:5665/v1/objects/services/example.localdomain!realtime-load' \ + -d '{ "templates": [ "generic-service" ], "attrs": { "check_command": "load", "check_interval": 1,"retry_interval": 1 } }' ``` Example for a new CheckCommand object: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/checkcommands/mytest' \ --d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X PUT 'https://localhost:5665/v1/objects/checkcommands/mytest' \ + -d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }' ``` ### Modifying Objects @@ -758,20 +851,22 @@ parameters need to be passed inside the JSON body: -----------|------------|--------------------------- attrs | Dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types). -In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided. +In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) +parameter should be provided. > **Note**: > > Modified attributes do not trigger a re-evaluation of existing > static [apply rules](03-monitoring-basics.md#using-apply) and [group assignments](03-monitoring-basics.md#group-assign-intro). -> Delete and re-create the objects if you require such changes. +> Delete and re-create the objects if you require such changes or +> consider funding [this feature request](https://github.com/Icinga/icinga2/issues/4084). > > Furthermore you cannot modify templates which have already been resolved > during [object creation](12-icinga2-api.md#icinga2-api-config-objects-create). > There are attributes which can only be set for [PUT requests](12-icinga2-api.md#icinga2-api-config-objects-create) such as `groups` > 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. -If attributes are of the Dictionary type, you can also use the indexer format: +If attributes are of the [Dictionary](17-language-reference.md#dictionary) type, you can also use the indexer format: ``` "attrs": { "vars.os": "Linux" } @@ -780,8 +875,9 @@ If attributes are of the Dictionary type, you can also use the indexer format: The following example updates the `address` attribute and the custom attribute `os` for the `example.localdomain` host: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/hosts/example.localdomain' \ --d '{ "attrs": { "address": "192.168.1.2", "vars.os" : "Windows" }, "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/objects/hosts/example.localdomain' \ + -d '{ "attrs": { "address": "192.168.1.2", "vars.os" : "Windows" }, "pretty": true }' { "results": [ { @@ -808,7 +904,8 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters Example for deleting the host object `example.localdomain`: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE 'https://localhost:5665/v1/objects/hosts/example.localdomain?cascade=1&pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X DELETE 'https://localhost:5665/v1/objects/hosts/example.localdomain?cascade=1&pretty=1' { "results": [ { @@ -851,8 +948,10 @@ The `filter` attribute is passed inside the request body thus requiring to use [ here. ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5661/v1/templates/hosts' \ --d '{ "filter": "match(\"g*\", tmpl.name)" }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -H 'X-HTTP-Method-Override: GET' -X POST \ + 'https://localhost:5661/v1/templates/hosts' \ + -d '{ "filter": "match(\"g*\", tmpl.name)" }' ``` Instead of using a filter you can optionally specify the template name in the @@ -885,8 +984,10 @@ The `filter` attribute is passed inside the request body thus requiring to use [ here. ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5661/v1/variables' \ --d '{ "filter": "variable.type in [ \"String\", \"Number\" ]" }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -H 'X-HTTP-Method-Override: GET' -X POST \ + 'https://localhost:5661/v1/variables' \ + -d '{ "filter": "variable.type in [ \"String\", \"Number\" ]" }' ``` Instead of using a filter you can optionally specify the variable name in the @@ -903,10 +1004,12 @@ The result set contains the type, name and value of the global variable. There are several actions available for Icinga 2 provided by the `/v1/actions` URL endpoint. You can run actions by sending a `POST` request. -In case you have been using the [external commands](14-features.md#external-commands) -in the past, the API actions provide a similar interface with filter -capabilities for some of the more common targets which do not directly change -the configuration. +The following actions are also used by [Icinga Web 2](https://icinga.com/products/icinga-web-2/): + +* sending check results to Icinga from scripts, remote agents, etc. +* scheduling downtimes from external scripts or cronjobs +* acknowledging problems +* adding comments All actions return a 200 `OK` or an appropriate error code for each action performed on each object matching the supplied filter. @@ -917,7 +1020,9 @@ notification on a program-wide basis must be applied by updating the called `app`. ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' -d '{ "attrs": { "enable_notifications": false } }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' \ + -d '{ "attrs": { "enable_notifications": false } }' ``` ### process-check-result @@ -939,30 +1044,33 @@ Send a `POST` request to the URL endpoint `/v1/actions/process-check-result`. In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`. -Example for the service `passive-ping6`: +Example for the service `passive-ping`: ``` -$ 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' \ --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", "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/process-check-result' \ +-d '{ "type": "Service", "filter": "host.name==\"icinga2-master1.localdomain\" && service.name==\"passive-ping\"", "exit_status": 2, "plugin_output": "PING CRITICAL - Packet loss = 100%", "performance_data": [ "rta=5000.000000ms;3000.000000;5000.000000;0.000000", "pl=100%;80;100;0" ], "check_source": "example.localdomain", "pretty": true }' { "results": [ { "code": 200.0, - "status": "Successfully processed check result for object 'localdomain!passive-ping6'." + "status": "Successfully processed check result for object 'icinga2-master1.localdomain!passive-ping'." } ] } ``` +You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body. + Example for using the `Host` type and filter by the host name: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result' \ --d '{ "filter": "host.name==\"example.localdomain\"", "type": "Host", "exit_status": 1, "plugin_output": "Host is not available." }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/process-check-result' \ + -d '{ "filter": "host.name==\"example.localdomain\"", "type": "Host", "exit_status": 1, "plugin_output": "Host is not available." }' ``` -You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body. > **Note** > @@ -988,14 +1096,15 @@ The example reschedules all services with the name "ping6" to immediately perfor allowed for the service (`force=true`). ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/reschedule-check' \ --d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force": true, "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/reschedule-check' \ + -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force": true, "pretty": true }' { "results": [ { "code": 200.0, - "status": "Successfully rescheduled check for object 'example.localdomain!ping6'." + "status": "Successfully rescheduled check for object 'icinga2-master1.localdomain!ping6'." } ] } @@ -1020,8 +1129,9 @@ Example for a custom host notification announcing a global maintenance to host owners: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/send-custom-notification' \ --d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true, "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/send-custom-notification' \ + -d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true, "pretty": true }' { "results": [ @@ -1054,8 +1164,9 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters Example: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/delay-notification' \ --d '{ "type": "Service", "timestamp": 1446389894, "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/delay-notification' \ + -d '{ "type": "Service", "timestamp": 1446389894, "pretty": true }' { "results": [ @@ -1093,18 +1204,19 @@ The following example acknowledges all services which are in a hard critical sta a notification for them: ``` -$ 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' \ --d '{ "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true, "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/acknowledge-problem' \ + -d '{ "type": "Service", "filter": "service.state==2&service.state_type=1", "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true, "pretty": true }' { "results": [ { "code": 200.0, - "status": "Successfully acknowledged problem for object 'example2.localdomain!ping4'." + "status": "Successfully acknowledged problem for object 'icinga2-satellite1.localdomain!ping4'." }, { "code": 200.0, - "status": "Successfully acknowledged problem for object 'example.localdomain!ping4'." + "status": "Successfully acknowledged problem for object 'icinga2-satellite2.localdomain!ping4'." } } ``` @@ -1112,7 +1224,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local ### remove-acknowledgement Removes the acknowledgements for services or hosts. Once the acknowledgement has -been removed notifications will be sent out again. +been removed the next notification will be sent again. Send a `POST` request to the URL endpoint `/v1/actions/remove-acknowledgement`. @@ -1121,7 +1233,9 @@ A [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid ty The example removes all service acknowledgements: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-acknowledgement?type=Service&pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/remove-acknowledgement' \ + -d '{ "type": "Service", "pretty": true }' { "results": [ @@ -1152,20 +1266,22 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters The following example adds a comment for all `ping4` services: ``` -$ 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.", "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/add-comment' \ + -d '{ "type": "Service", "filter": "service.name==\"ping4\"", "author": "icingaadmin", "comment": "Troubleticket #123456789 opened.", "pretty": true }' { "results": [ { "code": 200.0, "legacy_id": 26.0, - "name": "example.localdomain!ping4!example.localdomain-1446824161-0", - "status": "Successfully added comment 'example.localdomain!ping4!example.localdomain-1446824161-0' for object 'example.localdomain!ping4'." + "name": "icinga2-satellite1.localdomain!ping4!7e7861c8-8008-4e8d-9910-2a0bb26921bd", + "status": "Successfully added comment 'icinga2-satellite1.localdomain!ping4!7e7861c8-8008-4e8d-9910-2a0bb26921bd' for object 'icinga2-satellite1.localdomain!ping4'." }, { "code": 200.0, "legacy_id": 27.0, - "name": "example2.localdomain!ping4!example.localdomain-1446824161-1", - "status": "Successfully added comment 'example2.localdomain!ping4!example.localdomain-1446824161-1' for object 'example2.localdomain!ping4'." + "name": "icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f", + "status": "Successfully added comment 'icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f' for object 'icinga2-satellite2.localdomain!ping4'." } ] } @@ -1185,12 +1301,14 @@ A [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid ty Example for a simple filter using the `comment` URL parameter: ``` -$ 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&pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/remove-comment' \ + -d '{ "comment": "icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f", "pretty": true }' { "results": [ { "code": 200.0, - "status": "Successfully removed comment 'example2.localdomain!ping4!mbmif.local-1446986367-0'." + "status": "Successfully removed comment 'icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f'." } ] } @@ -1199,16 +1317,18 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local Example for removing all service comments using a service name filter for `ping4`: ``` -$ 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&pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/remove-comment' + -d '{ "type": "Service", "filter": "service.name==\"ping4\"", "pretty": true }' { "results": [ { "code": 200.0, - "status": "Successfully removed all comments for object 'example2.localdomain!ping4'." + "status": "Successfully removed all comments for object 'icinga2-satellite1.localdomain!ping4'." }, { "code": 200.0, - "status": "Successfully removed all comments for object 'example.localdomain!ping4'." + "status": "Successfully removed all comments for object 'icinga2-satellite2.localdomain!ping4'." } ] } @@ -1233,28 +1353,37 @@ Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`. In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`. -Example: +Example for scheduling a downtime for all `ping4` services: ``` -$ 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", "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/schedule-downtime' \ + -d '{ "type": "Service", "filter": "service.name==\"ping4\"", "start_time": 1446388806, "end_time": 1446389806, "duration": 1000, "author": "icingaadmin", "comment": "IPv4 network maintenance", "pretty": true }' { "results": [ { "code": 200.0, "legacy_id": 2.0, - "name": "example2.localdomain!ping4!example.localdomain-1446822004-0", - "status": "Successfully scheduled downtime 'example2.localdomain!ping4!example.localdomain-1446822004-0' for object 'example2.localdomain!ping4'." + "name": "icinga2-satellite1.localdomain!ping4!ecc5fa55-a5b8-4189-a013-a5d4bb47af34", + "status": "Successfully scheduled downtime 'icinga2-satellite1.localdomain!ping4!ecc5fa55-a5b8-4189-a013-a5d4bb47af34' for object 'icinga2-satellite1.localdomain!ping4'." }, { "code": 200.0, "legacy_id": 3.0, - "name": "example.localdomain!ping4!example.localdomain-1446822004-1", - "status": "Successfully scheduled downtime 'example.localdomain!ping4!example.localdomain-1446822004-1' for object 'example.localdomain!ping4'." + "name": "icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347", + "status": "Successfully scheduled downtime 'icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347' for object 'icinga2-satellite2.localdomain!ping4'." } ] } ``` +In case you want to target just a single service on a host, modify the filter +like this: + +``` +"filter": "host.name==\"icinga2-satellite1.localdomain\" && service.name==\"ping4\"" +``` + ### remove-downtime Remove the downtime using its `name` attribute , returns `OK` if the @@ -1269,26 +1398,30 @@ A [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid ty Example for a simple filter using the `downtime` URL parameter: ``` -$ 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&pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/remove-downtime' \ + -d '{ "downtime": "icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347", "pretty": true }' { "results": [ { "code": 200.0, - "status": "Successfully removed downtime 'example.localdomain!ping4!mbmif.local-1446979168-6'." + "status": "Successfully removed downtime 'icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347'." } ] } ``` -Example for removing all host downtimes using a host name filter for `example.localdomain`: +Example for removing all host downtimes using a host name filter for `icinga2-satellite2.localdomain`: ``` -$ 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&pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/remove-downtime' \ + -d '{ "type": "Host", "filter": "host.name==\"icinga2-satellite2.localdomain\"", "pretty": true }' { "results": [ { "code": 200.0, - "status": "Successfully removed all downtimes for object 'example.localdomain'." + "status": "Successfully removed all downtimes for object 'icinga2-satellite2.localdomain'." } ] } @@ -1298,12 +1431,13 @@ Example for removing a downtime from a host but not the services filtered by the filter variables explained in the [advanced filters](12-icinga2-api.md#icinga2-api-advanced-filters) chapter. ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime' \ - -d $'{ +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/remove-downtime' \ + -d $'{ "type": "Downtime", "filter": "host.name == filterHost && !service && downtime.author == filterAuthor", "filter_vars": { - "filterHost": "example.localdomain", + "filterHost": "icinga2-satellite1.localdomain", "filterAuthor": "icingaadmin" }, "pretty": true @@ -1313,7 +1447,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local "results": [ { "code": 200.0, - "status": "Successfully removed downtime 'example.localdomain!mbmif.local-1463043129-3'." + "status": "Successfully removed downtime 'icinga2-satellite1.localdomain!ecc5fa55-a5b8-ef34-abcd-a5d41234af34'." } ] } @@ -1321,7 +1455,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local ### shutdown-process -Shuts down Icinga2. May or may not return. +Shuts down Icinga. May or may not return. Send a `POST` request to the URL endpoint `/v1/actions/shutdown-process`. @@ -1330,7 +1464,8 @@ This action does not support a target type or filter. Example: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/shutdown-process?pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/shutdown-process?pretty=1' { "results": [ @@ -1344,7 +1479,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local ### restart-process -Restarts Icinga2. May or may not return. +Restarts Icinga. May or may not return. Send a `POST` request to the URL endpoint `/v1/actions/restart-process`. @@ -1353,7 +1488,8 @@ This action does not support a target type or filter. Example: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/restart-process?pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/restart-process?pretty=1' { "results": [ @@ -1370,6 +1506,12 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local Generates a PKI ticket for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). This can be used in combination with satellite/client setups requesting this ticket number. +> **Note** +> +> This must be used on the local host, or e.g. by a Puppet master. +> Doing so remotely may result in security issues with cluster +> trust relationships. + Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`. Parameter | Type | Description @@ -1379,8 +1521,9 @@ Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`. Example: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/generate-ticket' \ --d '{ "cn": "icinga2-client1.localdomain", "pretty": true }' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/generate-ticket' \ + -d '{ "cn": "icinga2-client1.localdomain", "pretty": true }' { "results": [ { @@ -1394,6 +1537,14 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local ## Event Streams +Event streams can be used to receive check results, downtimes, comments, +acknowledgements, etc. as a "live stream" from Icinga. + +You can for example forward these types into your own backend. Process the +metrics and correlate them with notifications and state changes e.g. in Elasticsearch +with the help of [Icingabeat](https://icinga.com/docs/icingabeat/latest/). Another use +case are aligned events and creating/resolving tickets automatically in your ticket system. + You can subscribe to event streams by sending a `POST` request to the URL endpoint `/v1/events`. The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body): @@ -1428,6 +1579,8 @@ Example for all downtime events: ``` &types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered + +-d '{ "types": ["DowntimeAdded", "DowntimeRemoved", "DowntimeTriggered"] }' ``` #### Event Stream Type: CheckResult @@ -1568,6 +1721,8 @@ Example for the `CheckResult` type with the `exit_code` set to `2`: ``` &types=CheckResult&filter=event.check_result.exit_status==2 + +-d '{ "types": "CheckResult", "filter": "event.check_result.exit_status==2" }' ``` Example for the `CheckResult` type with the service [matching](18-library-reference.md#global-functions-match) @@ -1575,6 +1730,8 @@ the string pattern "random\*": ``` &types=CheckResult&filter=match%28%22random*%22,event.service%29 + +-d { "types": "CheckResult", "filter": "match(\"random*\", event.service)" } ``` ### Event Stream Response @@ -1585,7 +1742,9 @@ must support long-polling and HTTP/1.1. HTTP/1.0 is not supported. Example: ``` -$ 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' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/events' \ + -d '{ "queue": "myqueue", "types": "CheckResult", "filter": "event.check_result.exit_status==2" }' {"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421319.7226390839,"type":"CheckResult"} {"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421324.7226390839,"type":"CheckResult"} @@ -1649,23 +1808,30 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication? ## Configuration Management -The main idea behind configuration management is to allow external applications -creating configuration packages and stages based on configuration files and +The main idea behind configuration management is that external applications +can create configuration packages and stages based on configuration files and directory trees. This replaces any additional SSH connection and whatnot to dump configuration files to Icinga 2 directly. + In case you are pushing a new configuration stage to a package, Icinga 2 will validate the configuration asynchronously and populate a status log which -can be fetched in a separated request. +can be fetched in a separated request. Once the validation succeeds, +a reload is triggered by default. + +This functionality was primarly developed for the [Icinga Director](https://icinga.com/docs/director/latest/) +but can be used with your own deployments too. It also solves the problem +with certain runtime objects (zones, endpoints) and can be used to +deploy global templates in [global cluster zones](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync). -### Creating a Config Package +### Create a Config Package Send a `POST` request to a new config package called `example-cmdb` in this example. This -will create a new empty configuration package. +creates a new empty configuration package. ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \ -'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ +-X POST 'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1' { "results": [ { @@ -1677,12 +1843,20 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \ } ``` -Package names starting with an underscore are reserved for internal packages and must not be used. +Package names with the `_` prefix are reserved for internal packages and must not be used. +You can recognize `_api`, `_etc` and `_cluster` when querying specific objects and packages. -### Uploading configuration for a Config Package +Each configuration object stores the package source in the `package` attribute. -Configuration files in packages are managed in stages. -Stages provide a way to maintain multiple configuration versions for a package. +### Create a Stage: Upload Configuration + +Configuration files in packages are managed in stages. Stages provide a way +to maintain multiple configuration versions for a package. Once a new stage +is deployed, the content is validated and set as active stage on success. + +On failure, the older stage remains active, and the caller can fetch the `startup.log` +from this stage deployment attempt to see what exactly failed. You can see that +in the Director's deployment log. Send a `POST` request to the URL endpoint `/v1/config/stages` and add the name of an existing configuration package to the URL path (e.g. `example-cmdb`). @@ -1723,8 +1897,8 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \ { "code": 200.0, "package": "example-cmdb", - "stage": "example.localdomain-1441625839-0", - "status": "Created stage. Icinga2 will reload." + "stage": "7e7861c8-8008-4e8d-9910-2a0bb26921bd", + "status": "Created stage. Reload triggered." } ] } @@ -1742,7 +1916,7 @@ and its configuration objects will remain active. > > 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. -Icinga 2 will create the following files in the configuration package +Icinga 2 creates the following files in the configuration package stage after configuration validation: File | Description @@ -1751,7 +1925,8 @@ stage after configuration validation: startup.log | Contains the [configuration validation](11-cli-commands.md#config-validation) output. You can [fetch these files](12-icinga2-api.md#icinga2-api-config-management-fetch-config-package-stage-files) -in order to verify that the new configuration was deployed successfully. +in order to verify that the new configuration was deployed successfully. Please follow the chapter below +to learn more about this. ### List Configuration Packages and their Stages @@ -1769,7 +1944,7 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/packages?pretty=1' "active-stage": "", "name": "example-cmdb", "stages": [ - "example.localdomain-1441625839-0" + "7e7861c8-8008-4e8d-9910-2a0bb26921bd" ] } ] @@ -1780,10 +1955,10 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/packages?pretty=1' In order to retrieve a list of files for a stage you can send a `GET` request to the URL endpoint `/v1/config/stages`. You need to include -the package name (`example-cmdb`) and stage name (`example.localdomain-1441625839-0`) in the URL: +the package name (`example-cmdb`) and stage name (`7e7861c8-8008-4e8d-9910-2a0bb26921bd`) in the URL: ``` -$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441625839-0?pretty=1' +$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd?pretty=1' { "results": [ ... @@ -1823,7 +1998,7 @@ the package name, the stage name and the relative path to the file to the URL pa The following example fetches the configuration file `conf.d/test.conf`: ``` -$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441625839-0/conf.d/test.conf' +$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/conf.d/test.conf' object Host "cmdb-host" { chec_command = "dummy" } ``` @@ -1841,18 +2016,18 @@ by sending a `GET` request to the URL endpoint `/v1/config/files`. You must incl the package name, stage name and the `startup.log` in the URL path. ``` -$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441133065-1/startup.log' +$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/startup.log' ... critical/config: Error: Attribute 'chec_command' does not exist. Location: -/var/lib/icinga2/api/packages/example-cmdb/example.localdomain-1441133065-1/conf.d/test.conf(1): object Host "cmdb-host" { chec_command = "dummy" } +/var/lib/icinga2/api/packages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/conf.d/test.conf(1): object Host "cmdb-host" { chec_command = "dummy" } ^^^^^^^^^^^^^^^^^^^^^^ critical/config: 1 error ``` -The output is similar to the manual [configuration validation](11-cli-commands.md#config-validation). +The output is the exact as known from [configuration validation](11-cli-commands.md#config-validation). > **Note** > @@ -1865,12 +2040,12 @@ You can send a `DELETE` request to the URL endpoint `/v1/config/stages` in order to purge a configuration stage. You must include the package and stage name inside the URL path. -The following example removes the failed configuration stage `example.localdomain-1441133065-1` +The following example removes the failed configuration stage `7e7861c8-8008-4e8d-9910-2a0bb26921bd` in the `example-cmdb` configuration package: ``` -$ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE \ -'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441133065-1?pretty=1' +$ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X DELETE 'https://localhost:5665/v1/config/stages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd?pretty=1' { "results": [ { @@ -1954,11 +2129,17 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/types/Object?pretty=1' } ``` -## Console +## Debug Console You can inspect variables and execute other expressions by sending a `POST` request to the URL endpoint `/v1/console/execute-script`. In order to receive auto-completion suggestions, send a `POST` request to the URL endpoint `/v1/console/auto-complete-script`. +> **Note** +> +> This functionality is used by the [debug console](11-cli-commands.md#cli-command-console). Do not use this in production, unless +> you are aware of the fact that expressions and commands may crash the daemon, or lead into +> unwanted behaviour. Use this URL endpoint **read-only** when needed. + The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body): Parameter | Type | Description @@ -1980,7 +2161,8 @@ If you specify a session identifier, the same script context can be reused for m Example for fetching the command line from the local host's last check result: ``` -$ 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&pretty=1' +$ 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&pretty=1' { "results": [ { @@ -2004,7 +2186,8 @@ Example for fetching auto-completion suggestions for the `Host.` type. This work similar fashion when pressing TAB inside the [console CLI command](11-cli-commands.md#cli-command-console): ``` -$ 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&pretty=1' +$ 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&pretty=1' { "results": [ { @@ -2027,27 +2210,92 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local ## API Clients -There are a couple of existing clients which can be used with the Icinga 2 API: +After its initial release in 2015, community members +and developers have been working hard to add more REST API +clients and integrations into DevOps tools. -* [curl](https://curl.haxx.se/) or any other HTTP client really -* [Icinga 2 console (CLI command)](12-icinga2-api.md#icinga2-api-clients-cli-console) -* [Icinga Web 2 Director](https://icinga.com/products/icinga-web-2-modules/) - -Demo cases: - -* [Dashing](https://github.com/Icinga/dashing-icinga2) -* [API examples](https://github.com/Icinga/icinga2-api-examples) +* [Libraries](12-icinga2-api.md#icinga2-api-clients-libraries) +* [Status](#icinga2-api-clients-status) +* [Management](#icinga2-api-clients-management) +* [Event Streams](#icinga2-api-clients-event-streams) +* [Actions](#icinga2-api-clients-actions) +* [REST API Apps](#icinga2-api-clients-apps) Additional [programmatic examples](12-icinga2-api.md#icinga2-api-clients-programmatic-examples) will help you getting started using the Icinga 2 API in your environment. -### Icinga 2 Console +### Libraries -By default the [console CLI command](11-cli-commands.md#cli-command-console) evaluates -expressions in a local interpreter, i.e. independently from your Icinga 2 daemon. -Add the `--connect` parameter to debug and evaluate expressions via the API. +Name | Language | Description +------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------- +[ruby-icinga2](https://github.com/bodsch/ruby-icinga2) | Ruby | Ruby library +[python-icinga2_api](https://github.com/KevinHonka/Icinga2_Python_API) | Python | Python library +[python-icinga2-api](https://github.com/fmnisme/python-icinga2api) | Python | Python bindings for Icinga 2 interaction +[go-icinga2](https://github.com/xert/go-icinga2) | Golang | Golang functions and type definitions +[go-icinga2-api](https://github.com/lrsmith/go-icinga2-api/) | Golang | Golang implementation used inside the Terraform provider +[go-icinga2-client](https://github.com/Nexinto/go-icinga2-client) | Golang | Golang implementation for the Rancher integration. +[Monitoring::Icinga2::Client::REST](https://metacpan.org/release/THESEAL/Monitoring-Icinga2-Client-REST-2.0.0) | Perl | Perl bindings. +[Icinga 2 API in PHP](https://github.com/uniwue-rz/icinga2-api) | PHP | PHP implementation. For other examples, look into Icinga Web 2 and Director. -### API Clients Programmatic Examples +### Status + +Name | Language | Description +------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------- +[Dashing](https://github.com/dnsmichi/dashing-icinga2) | Ruby, HTML | Dashboard for Dashing querying the REST API for current host/service/global status +[InfluxDB Telegraf Input](https://github.com/influxdata/telegraf/blob/master/plugins/inputs/icinga2/README.md) | Golang | [Telegraf](https://github.com/influxdata/telegraf) is an agent written in Go for collecting, processing, aggregating, and writing metrics. +[Icinga 2 Slack Bot](https://github.com/mlabouardy/icinga2-slack-bot) | Golang | Query host/service details from a [Slack](https://slack.com/) channel +[icinga2bot](https://github.com/reikoNeko/icinga2bot) | Python | [Errbot](http://errbot.io/en/latest/user_guide/setup.html) plugin to fetch status and event stream information and forward to XMPP, IRC, etc. +[IcingaBusyLightAgent](https://github.com/stdevel/IcingaBusylightAgent) | C# | Notification Agent in Systray +[BitBar for OSX](https://getbitbar.com/plugins/Dev/Icinga2/icinga2.24m.py) | Python | macOS tray app for highlighting the host/service status +[Icinga 2 Multistatus](https://chrome.google.com/webstore/detail/icinga-multi-status/khabbhcojgkibdeipanmiphceeoiijal/related) | - | Chrome Extension + +### Manage Objects + +Name | Language | Description +------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------- +[Icinga Director](https://icinga.com/docs/director/latest) | PHP, JS | Icinga 2 configuration interface with a nice frontend, and automated imports for nearly any source. +[Terraform Provider](https://github.com/terraform-providers/terraform-provider-icinga2) | Golang | Register hosts from Terraform in Icinga 2. [Official docs](https://www.terraform.io/docs/providers/icinga2/index.html). +[Kube Icinga](https://github.com/gyselroth/kube-icinga) | Typescript | Monitor Kubernetes services / resources using icinga2 (including autodiscovery support) +[Logstash output for Icinga](https://www.icinga.com/products/integrations/elastic/) | Ruby | Forward check results and create objects from log events +[Foreman Smart Proxy Monitoring](https://github.com/theforeman/smart_proxy_monitoring) | Ruby | Smart Proxy extension for Foreman creating and deleting hosts and services in Icinga 2 +[Rancher integration](https://github.com/Nexinto/rancher-icinga) | Golang | Registers [Rancher](http://rancher.com/rancher/) resources in Icinga 2 for monitoring. +[AWS/EC2](https://github.com/Icinga/icinga2-api-examples/tree/master/aws-ec2) | Ruby | Example script for creating and deleting AWS instances in Icinga 2 +[Ansible Host Module](https://docs.ansible.com/ansible/latest/modules/icinga2_host_module.html) | Python | In progress, [Ansible Feature](https://docs.ansible.com/ansible/latest/modules/icinga2_feature_module.html#icinga2-feature-module) is also there. + +### Event Streams + +Name | Language | Description +------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------- +[Elastic Icingabeat](https://icinga.com/docs/icingabeat/latest/) | Golang | Process events and send to Elasticsearch/Logstash outputs +[Request Tracker ticket integration](https://github.com/bytemine/icinga2rt) | Golang | Create and update RT tickets +[Logstash input event stream](https://github.com/bobapple/logstash-input-icinga_eventstream) | Ruby | Forward events as Logstash input +[Flapjack events](https://github.com/sol1/flapjack-icinga2) | Golang | Dumping events into Redis for Flapjack processing +[Stackstorm integration](https://github.com/StackStorm-Exchange/stackstorm-icinga2) | Python | Processing events and fetching status information + +### Actions + +Name | Language | Description +------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------- +[Icinga Web 2](https://icinga.com/docs/icingaweb2/latest/) | PHP | Trigger actions via command transport +[Logstash output for Icinga](https://www.icinga.com/products/integrations/elastic/) | Ruby | Forward check results and create objects from log events +[OTRS SystemMonitoring](https://github.com/OTRS/SystemMonitoring) | Perl | Acknowledge problems in Icinga 2 from OTRS tickets +[mqttwarn](https://github.com/jpmens/mqttwarn#icinga2) | Python | Forward check results from mqttwarn to Icinga 2 +[Lita handler](https://github.com/tuxmea/lita-icinga2) | Ruby | List, recheck and acknowledge through a #chatops bot called [Lita](https://github.com/litaio/lita) +[Sakuli forwarder](http://sakuli.readthedocs.io/en/latest/forwarder-icinga2api/) | Java | Forward check results from tests from [Sakuli](https://github.com/ConSol/sakuli) to Icinga 2 +[OpsGenie actions](https://www.opsgenie.com/docs/integrations/icinga2-integration) | Golang, Java | Integrate Icinga 2 into OpsGenie + + +### REST API Apps + +Name | Language | Description +------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------- +Browser plugins | - | [Postman for Chrome](https://www.getpostman.com), [RESTED for Firefox](https://addons.mozilla.org/en-US/firefox/addon/rested/) +[Postman](https://www.getpostman.com/) | - | App instead of browser plugin +[Cocoa Rest Client](http://mmattozzi.github.io/cocoa-rest-client/) | - | macOS app +[Paw for MacOS](https://paw.cloud) | (exported) | Paw is a full-featured HTTP client that lets you test and describe the APIs you build or consume. It has a beautiful native macOS interface to compose requests, inspect server responses, generate client code and export API definitions. + + +### Programmatic Examples The following languages are covered: @@ -2057,11 +2305,10 @@ The following languages are covered: * [Perl](12-icinga2-api.md#icinga2-api-clients-programmatic-examples-perl) * [Golang](12-icinga2-api.md#icinga2-api-clients-programmatic-examples-golang) -The [request method](icinga2-api-requests) is `POST` using -[X-HTTP-Method-Override: GET](12-icinga2-api.md#icinga2-api-requests-method-override) -which allows you to send a JSON request body. The examples request -specific service attributes joined with host attributes. `attrs` -and `joins` are therefore specified as array. +The [request method](icinga2-api-requests) is `POST` using [X-HTTP-Method-Override: GET](12-icinga2-api.md#icinga2-api-requests-method-override) +which allows you to send a JSON request body. The examples request specific service +attributes joined with host attributes. `attrs` and `joins` are therefore specified +as array. The `filter` attribute [matches](18-library-reference.md#global-functions-match) on all services with `ping` in their name. diff --git a/doc/19-technical-concepts.md b/doc/19-technical-concepts.md index eefeb4a26..878e5391f 100644 --- a/doc/19-technical-concepts.md +++ b/doc/19-technical-concepts.md @@ -1680,7 +1680,7 @@ Message updates are dropped when * The origin sender is not in a parent zone of the receiver. * The certificate fingerprint is in an invalid format. -#### log::SetLogPosition +#### log::SetLogPosition > Location: `apilistener.cpp` and `jsonrpcconnection.cpp`