doc: initial Self Service API documentation

refs #486

doc/70-REST-API.md

@@ -508,3 +508,76 @@ Content-Type: application/json
 
 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 annd 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-servie/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    |
+                                         +---------------------+
+```

doc/74-Self-Service-API.md

@@ -0,0 +1,55 @@
+<a id="Self-Service-API"></a>Self Service API
+=============================================
+
+Introduction
+------------
+
+Icinga Director offers a Self Service API, allowing new Hosts running the Icinga
+Agent to register themselves in a secure way.
+
+### Windows Agents
+
+Windows Agents are the main target audience for this feature. It allows you to
+generate a single Powershell Script based on the [Icinga 2 Powershell Module](
+https://github.com/Icinga/icinga2-powershell-module
+). You can either use the same script for all of your Windows Hosts or generate
+different ones for different kind of systems.
+
+This installation script could then be shipped with your base images, invoked
+remotely via **PowerShell Remoting**, distributed as a module via **Group
+Policies** and/or triggered via **Run-Once** (AD Policies).
+
+### Linux Agents
+
+At the time of this writing, we do not ship a script with all the functionality
+you can find in the Windows Powershell script. Linux and Unix environments are
+mostly highly automated these days, and such a magic shell script is often not
+what people want.
+
+Still, you can also benefit from this feature by directly using our [Self Service
+REST API](70-REST-API.md#Self Service API). It should be easy to integrate it into
+the automation tool of your choice.
+
+Base Configuration
+------------------
+
+You have full control over the automation Script generated by the Icinga Director.
+Please got to the **Infrastructure Dashboard** and choose the **Self Service API**:
+
+![Infrastructure Dashboard - Self Service API](
+screenshot/director/74_self-service-api/7401-director_self-service-dashboard.png
+)
+
+This leads to the Self Service API Settings form. Most settings are self-explaining
+and come with detailled inline hints. The most important choice is whether the
+script should automatically install the Icinga Agent:
+
+![Settings - Choose installation source](
+screenshot/director/74_self-service-api/7402-director_self-service-choose-source.png
+)
+
+In case you opted for automated installation, more options will pop up:
+
+![Settings - Installer Details](
+screenshot/director/74_self-service-api/7403-director_self-service-settings.png
+)