Adding upstream version 1.10.2.upstream/1.10.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 684 insertions, 0 deletions

diff --git a/doc/70-REST-API.md b/doc/70-REST-API.md
new file mode 100644
index 0000000..dd5d266
--- /dev/null
+++ b/doc/70-REST-API.md
@@ -0,0 +1,684 @@
+<a id="REST-API"></a>The Icinga Director REST API
+=================================================
+
+Introduction
+------------
+
+Icinga Director has been designed with a REST API in mind. Most URLs you
+can access with your browser will also act as valid REST url endpoints.
+
+Base Headers
+------------
+All your requests MUST have a valid accept header. The only acceptable
+variant right now is `application/json`, so please always append a header
+as follows to your requests:
+
+    Accept: application/json
+
+
+Authentication
+--------------
+Please use HTTP authentication and any valid Icinga Web 2 user, granted
+enough permissions to accomplish the desired actions. The restrictions
+and permissions that have been assigned to web users will also be enforced
+for API users. In addition, the permission `director/api` is required for
+any API access.
+
+Versioning
+----------
+
+There are no version strings so far in the Director URLs. We will try hard
+to not break compatibility with future versions. Sure, sooner or later we
+also might be forced to introduce some kind of versioning. But who knows?
+
+As a developer you can trust us to not remove any existing REST url or any
+provided property. However, you must always be ready to accept new properties.
+
+URL scheme and supported methods
+--------------------------------
+
+We support GET, POST, PUT and DELETE.
+
+| Method | Meaning                                                             |
+|--------|---------------------------------------------------------------------|
+| GET    | Read / fetch data. Not allowed to run operations with the potential |
+|        | to cause any harm                                                   |
+| POST   | Trigger actions, create or modify objects. Can also be used to      |
+|        | partially modify objects                                            |
+| PUT    | Creates or replaces objects, cannot be used to modify single object |
+|        | properties                                                          |
+| DELETE | Remove a specific object                                            |
+
+TODO: more examples showing the difference between POST and PUT
+
+POST director/host
+ gives 201 on success
+GET director/host?name=hostname.example.com
+PUT director/host?name=hostname.example.com
+ gives 200 ok on success and 304 not modified on no change
+DELETE director/host?name=hostname.example.com
+ gives 200 on success
+
+
+First example request with CURL
+-------------------------------
+
+```sh
+curl -H 'Accept: application/json' \
+     -u 'username:password' \
+     'https://icinga.example.com/icingaweb2/director/host?name=hostname.example.com'
+```
+
+### CURL helper script
+
+A script like the following makes it easy to play around with curl:
+
+```sh
+METHOD=$1
+URL=$2
+BODY="$3"
+USERNAME="demo"
+PASSWORD="***"
+test -z "$PASSWORD" || USERNAME="$USERNAME:$PASSWORD"
+
+test -z "$BODY" && curl -u "$USERNAME" \
+  -i https://icingaweb/icingaweb/$URL \
+  -H 'Accept: application/json' \
+  -X $METHOD
+
+test -z "$BODY" || curl -u "$USERNAME" \
+  -i https://icingaweb/icingaweb/$URL \
+  -H 'Accept: application/json' \
+  -X $METHOD \
+  -d "$BODY"
+
+echo
+```
+
+It can be used as follows:
+
+```sh
+director-curl GET director/host?name=localhost
+
+director-curl POST director/host '{"object_name": "host2", "... }'
+```
+
+
+Should I use HTTPS?
+-------------------
+
+Sure, absolutely, no doubt. There is no, absolutely no reason to NOT use
+HTTPS these days. Especially not for a configuration tool allowing you to
+configure check commands that are going to be executed on all your servers.
+
+Icinga Objects
+--------------
+
+### Special parameters
+
+| Parameter      | Description                                                 |
+|----------------|-------------------------------------------------------------|
+| resolved       | Resolve all inherited properties and show a flat object     |
+| withNull       | Retrieve default (null) properties also                     |
+| withServices   | Show services attached to a host. `resolved` and `withNull` |
+|                | are applied for services too                                |
+| allowOverrides | Set variable overrides for virtual Services                 |
+| showStacktrace | Returns the related stack trace, in case an error occurs    |
+
+#### Resolve object properties
+
+In case you add the `resolved` parameter to your URL, all inherited object
+properties will be resolved. Such a URL could look as follows:
+
+    director/host?name=hostname.example.com&resolved
+
+
+#### Retrieve default (null) properties also
+
+Per default properties with `null` value are skipped when shipping a result.
+You can influence this behavior with the `properties` parameter. Just append
+`&withNull` to your URL:
+
+    director/host?name=hostname.example.com&withNull
+
+
+#### Fetch host with it's services
+
+This is what the `withServices` parameter exists:
+
+    director/host?name=hostname.example.com&withServices
+
+
+#### Retrieve only specific properties
+
+The `properties` parameter also allows you to specify a list of specific
+properties. In that case, only the given properties will be returned, even
+when they have no (`null`) value:
+
+    director/host?name=hostname.example.com&properties=object_name,address,vars
+
+
+#### Override vars for inherited/applied Services
+
+Enabling `allowOverrides` allows you to let Director figure out, whether your
+modified Custom Variables need to be applied to a specific individual Service,
+or whether setting Overrides at Host level is the way to go.
+
+     POST director/service?name=Uptime&host=hostname.example.com&allowOverrices
+
+```json
+{ "vars.uptime_warning": 300 }
+```
+
+In case `Uptime` is an Apply Rule, calling this without `allowOverrides` will
+trigger a 404 response. Please note that when modifying the Host object, the
+body for response 200 will show the Host object, as that's the one that has
+been modified.
+
+### Example
+
+GET director/host?name=pe2015.example.com
+```json
+{
+  "address": "127.0.0.3",
+  "check_command": null,
+  "check_interval": null,
+  "display_name": "pe2015 (example.com)",
+  "enable_active_checks": null,
+  "flapping_threshold": null,
+  "groups": [ ],
+  "imports": [
+    "generic-host"
+  ],
+  "retry_interval": null,
+  "vars": {
+    "facts": {
+      "aio_agent_build": "1.2.5",
+      "aio_agent_version": "1.2.5",
+      "architecture": "amd64",
+      "augeas": {
+        "version": "1.4.0"
+      },
+   ...
+}
+```
+
+director/host?name=pe2015.example.com&resolved
+```json
+{
+    "address": "127.0.0.3",
+    "check_command": "tom_ping",
+    "check_interval": "60",
+    "display_name": "pe2015 (example.com)",
+    "enable_active_checks": true,
+    "groups": [ ],
+    "imports": [
+      "generic-host"
+    ],
+    "retry_interval": "10",
+    "vars": {
+      "facts": {
+        "aio_agent_build": "1.2.5",
+        "aio_agent_version": "1.2.5",
+        "architecture": "amd64",
+        "augeas": {
+          "version": "1.4.0"
+        },
+     ...
+}
+```
+
+JSON is pretty-printed per default, at least for PHP >= 5.4
+
+Error handling
+--------------
+
+Director tries hard to return meaningful output and error codes:
+```
+HTTP/1.1 400 Bad Request
+Server: Apache
+Content-Length: 46
+Connection: close
+Content-Type: application/json
+```
+
+```json
+{
+    "error": "Invalid JSON: Syntax error"
+}
+```
+
+Trigger actions
+---------------
+You can of course also use the API to trigger specific actions. Deploying the configuration is as simple as issueing:
+
+    POST director/config/deploy
+
+More
+----
+
+Currently we do not handle Last-Modified und ETag headers. This would involve some work, but could be a cool feature. Let us know your ideas!
+
+
+Sample scenario
+---------------
+
+Let's show you how the REST API works with a couple of practical examples:
+
+### Create a new host
+
+```
+POST director/host
+```
+
+```json
+{
+  "object_name": "apitest",
+  "object_type": "object",
+  "address": "127.0.0.1",
+  "vars": {
+    "location": "Berlin"
+  }
+}
+```
+#### Response
+```
+HTTP/1.1 201 Created
+Date: Tue, 01 Mar 2016 04:43:55 GMT
+Server: Apache
+Content-Length: 140
+Content-Type: application/json
+```
+
+```json
+{
+    "address": "127.0.0.1",
+    "object_name": "apitest",
+    "object_type": "object",
+    "vars": {
+        "location": "Berlin"
+    }
+}
+```
+
+The most important part of the response is the response code: `201`, a resource has been created. Just for fun, let's fire the same request again. The answer obviously changes:
+
+```
+HTTP/1.1 500 Internal Server Error
+Date: Tue, 01 Mar 2016 04:45:04 GMT
+Server: Apache
+Content-Length: 60
+Connection: close
+Content-Type: application/json
+```
+
+```json
+{
+    "error": "Trying to recreate icinga_host (apitest)"
+}
+```
+
+So, let's update this host. To work with existing objects, you must ship their `name` in the URL:
+
+    POST director/host?name=apitest
+
+```json
+{
+  "object_name": "apitest",
+  "object_type": "object",
+  "address": "127.0.0.1",
+  "vars": {
+    "location": "Berlin"
+  }
+}
+```
+
+Same body, so no change:
+```
+HTTP/1.1 304 Not Modified
+Date: Tue, 01 Mar 2016 04:45:33 GMT
+Server: Apache
+```
+
+So let's now try to really change something:
+
+    POST director/host?name=apitest
+
+```json
+{"address": "127.0.0.2", "vars.event": "Icinga CAMP" }
+```
+
+We get status `200`, changes have been applied:
+
+```
+HTTP/1.1 200 OK
+Date: Tue, 01 Mar 2016 04:46:25 GMT
+Server: Apache
+Content-Length: 172
+Content-Type: application/json
+```
+
+```json
+{
+    "address": "127.0.0.2",
+    "object_name": "apitest",
+    "object_type": "object",
+    "vars": {
+        "location": "Berlin",
+        "event": "Icinga CAMP"
+    }
+}
+```
+
+The response always returns the full object on modification. This way you can immediately investigate the merged result. As you can see, `POST` requests only touch the parameters you passed - the rest remains untouched.
+
+One more example to prove this:
+
+```
+POST director/host?name=apitest
+```
+
+```json
+{"address": "127.0.0.2", "vars.event": "Icinga CAMP" }
+```
+
+No modification, you get a `304`. HTTP standards strongly discourage shipping a body in this case:
+```
+HTTP/1.1 304 Not Modified
+Date: Tue, 01 Mar 2016 04:52:05 GMT
+Server: Apache
+```
+
+As you might have noted, we only changed single properties in the vars dictionary. Now lets override the whole dictionary:
+
+```
+POST director/host?name=apitest
+```
+
+```json
+{"address": "127.0.0.2", "vars": { "event": [ "Icinga", "Camp" ] } }
+```
+
+The response shows that this works as expected:
+
+```
+HTTP/1.1 200 OK
+Date: Tue, 01 Mar 2016 04:52:33 GMT
+Server: Apache
+Content-Length: 181
+Content-Type: application/json
+```
+
+```json
+{
+    "address": "127.0.0.2",
+    "object_name": "apitest",
+    "object_type": "object",
+    "vars": {
+        "event": [
+            "Icinga",
+            "Camp"
+        ]
+    }
+}
+```
+
+If merging properties is not what you want, `PUT` comes to the rescue:
+
+    PUT director/host?name=apitest
+
+```
+{ "vars": { "event": [ "Icinga", "Camp" ] }
+```
+
+All other properties vanished, all but name and type:
+```
+HTTP/1.1 200 OK
+Date: Tue, 01 Mar 2016 04:54:33 GMT
+Server: Apache
+Content-Length: 153
+Content-Type: application/json
+```
+
+```json
+{
+    "object_name": "apitest",
+    "object_type": "object",
+    "vars": {
+        "event": [
+            "Icinga",
+            "Camp"
+        ]
+    }
+}
+```
+
+Let's put "nothing":
+
+    PUT director/host?name=apitest
+
+```json
+{}
+```
+
+Works as expected:
+
+```
+HTTP/1.1 200 OK
+Date: Tue, 01 Mar 2016 04:57:35 GMT
+Server: Apache
+Content-Length: 62
+Content-Type: application/json
+```
+
+```json
+{
+    "object_name": "apitest",
+    "object_type": "object"
+}
+```
+
+Of course, `PUT` also supports `304`, you can check this by sending the same request again.
+
+Now let's try to cheat:
+
+    KILL director/host?name=apitest
+
+```
+HTTP/1.1 400 Bad Request
+Date: Tue, 01 Mar 2016 04:54:07 GMT
+Server: Apache
+Content-Length: 43
+Connection: close
+Content-Type: application/json
+```
+
+```json
+{
+    "error": "Unsupported method KILL"
+}
+```
+
+Ok, no way. So let's use the correct method:
+
+    DELETE director/host?name=apitest
+
+```
+HTTP/1.1 200 OK
+Date: Tue, 01 Mar 2016 05:59:22 GMT
+Server: Apache
+Content-Length: 109
+Content-Type: application/json
+```
+
+```json
+{
+    "imports": [
+        "generic-host"
+    ],
+    "object_name": "apitest",
+    "object_type": "object"
+}
+```
+
+### Service Apply Rules
+
+Please note that Service Apply Rule names are not unique in Icinga 2. They are
+not real objects, they are creating other objects in a loop. This makes it
+impossible to distinct them by name. Therefore, a dedicated REST API endpoint
+`director/serviceapplyrules` ships all Service Apply Rules combined with their
+internal ID. This ID can then be used to modify or delete a Rule via
+`director/service`.
+
+### Deployment Status
+In case you want to fetch the information about the deployments status, 
+you can call the following API:
+
+    GET director/config/deployment-status
+
+```
+HTTP/1.1 200 OK
+Date: Wed, 07 Oct 2020 13:14:33 GMT
+Server: Apache
+Content-Type: application/json
+```
+
+```json
+{
+    "active_configuration": {
+        "stage_name": "b191211d-05cb-4679-842b-c45170b96421",
+        "config": "617b9cbad9e141cfc3f4cb636ec684bd60073be1",
+        "activity": "028b3a19ca7457f5fc9dbb5e4ea527eaf61616a2"
+    }
+}
+```
+This throws a 500 in case Icinga isn't reachable. 
+In case there is no active stage name related to the Director, active_configuration 
+is set to null.
+
+Another possibility is to pass a list of checksums to fetch the status of 
+specific deployments and (activity log) activities.
+Following, you can see an example of how to do it:
+
+    GET director/config/deployment-status?config_checksums=617b9cbad9e141cfc3f4cb636ec684bd60073be2,
+    617b9cbad9e141cfc3f4cb636ec684bd60073be1&activity_log_checksums=617b9cbad9e141cfc3f4cb636ec684bd60073be1,
+    028b3a19ca7457f5fc9dbb5e4ea527eaf61616a2
+    
+```json
+{
+    "active_configuration": {
+        "stage_name": "b191211d-05cb-4679-842b-c45170b96421",
+        "config": "617b9cbad9e141cfc3f4cb636ec684bd60073be1",
+        "activity": "028b3a19ca7457f5fc9dbb5e4ea527eaf61616a2"
+    },
+    "configs": {
+        "617b9cbad9e141cfc3f4cb636ec684bd60073be2": "deployed",
+        "617b9cbad9e141cfc3f4cb636ec684bd60073be1": "active"
+    },
+    "activities": {
+        "617b9cbad9e141cfc3f4cb636ec684bd60073be1": "undeployed",
+        "028b3a19ca7457f5fc9dbb5e4ea527eaf61616a2": "active"
+    }
+}
+```
+The list of possible status is: 
+* `active`: whether this configuration is currently active
+* `deployed`: whether this configuration has ever been deployed
+* `failed`: whether the deployment of this configuration has failed
+* `undeployed`: whether this configuration has been rendered, but not yet deployed
+* `unknown`: whether no configurations have been found for this checksum
+
+### Agent Tickets
+
+The Director is very helpful when it goes to manage your Icinga Agents. In
+case you want to fetch tickets through the API, please do as follows:
+
+    GET director/host/ticket?name=apitest
+
+```
+HTTP/1.1 200 OK
+Date: Thu, 07 Apr 2016 22:19:24 GMT
+Server: Apache
+Content-Length: 43
+Content-Type: application/json
+```
+
+```json
+"5de9883080e03278039bce57e4fbdbe8fd262c40"
+```
+
+Please expect an error in case the host does not exist or has not been
+configured to be an Icinga Agent.
+
+### Self Service API
+
+#### Theory of operation
+
+Icinga Director offers a Self Service API, allowing new Icinga nodes to register
+themselves. No credentials are required, authentication is based on API keys.
+There are two types of such keys:
+
+* Host Template API keys
+* Host Object API keys
+
+Template keys basically grant the permission to:
+
+* Create a new host based on that template
+* Specify name and address properties for that host
+
+This is a one-time operation and allows one to claim ownership of a specific host.
+Now, there are two possible scenarios:
+
+* The host already exists
+* The host is not known to Icinga Director
+
+In case the host already exists, Director will check whether it's API key matches
+the given one. [..]
+
+#### Request processing for Host registration
+
+A new node will `POST` to `self-service/register-host`, with two parameters in
+the URL:
+
+* `name`: it's desired object name, usually the FQDN
+* `key`: a valid Host Template API key
+
+In it's body it is allowed to specify a specific set of properties. At the time
+of this writing, these are:
+
+* `display_name`
+* `address`
+* `address6`
+
+Director will validate the `key` and load the corresponding *Host Template*. In
+case no such is found, the request is rejected. Then it checks whether a *Host*
+with the given `name` exists. In case it does, the request is rejected unless:
+
+* It inherits the loaded *Host Template*
+* It already has an API key
+
+If these conditions match, the request is processed. The following sketch roughly shows the decision tree (AFTER the key has been
+validated):
+
+```
+                               +-----------------------------+
+    +--------------+           | * Validate given properties |
+    | Host exists? | -- NO --> | * Create new host object    |-----------+
+    +--------------+           | * Return new Host API key   |           |
+           |                   +-----------------------------+           |
+          YES                                                            |
+           |                                                             |
+           v                          +-----------------------------+    |
+   +----------------------+           | * Validate given properties |    |
+   | Host has an API key? | -- NO --> | * Apply eventual changes    |----+
+   +----------------------+           | * Return new Host API key   |    |
+           |                          +-----------------------------+    |
+          YES                                                            |
+           |                                         +-------------------+
+           v                                         |
+   +--------------------+                            v
+   | Reject the request |                +---------------------+
+   +--------------------+                | Client persists the |
+                                         | new Host API key    |
+                                         +---------------------+
+```