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¶

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:

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:

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&allowOverrides

{ "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

{
  "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

{
    "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

Dropping a template from imports this way can also remove a custom variable value, if that value only existed because of the template you just dropped. See Attaching custom variables to objects and templates for details. Unlike the UI, the API does this without asking for confirmation.

Custom Variables¶

Custom variable values on an existing object can also be updated directly, without having to submit the whole object, using a dedicated endpoint.

POST director/<objectType>/variables?<params>
PUT  director/<objectType>/variables?<params>

This endpoint requires director/admin, regardless of object type. Call it with a JSON body whose keys are variable names and values are the new values. Strings, numbers, booleans, arrays and nested dictionaries are all accepted, matching the types described in Working with custom variables. The custom variable must already be configured under Custom Variables and already be attached to (or inherited from) the object you are updating. What happens when a variable isn’t attached yet depends on the method and the object type. See Attaching a variable to a template for the first time and Variable not configured below.

As with the general POST/PUT semantics described above, the two methods differ in how they treat variables you don’t mention in the body.

POST merges: only the keys you send are touched, all other existing variables on the object are left untouched.
PUT replaces: All the custom variables in the object are replaced with the ones in the body. Values inherited from templates are not affected either way, since they aren’t stored on the object itself.

On a template, PUT replaces more than values: it detaches every variable currently attached directly to that template, then reattaches only the ones present in the request body, attaching a not-yet-used one for the first time if needed (see Attaching a variable to a template for the first time below). A directly attached variable left out of the body is detached along with it, not just cleared of its value.

This endpoint only ever reads and writes values, it has no way to set or query the required flag itself. To keep a values-only PUT from silently turning a required variable optional, the required flag of a variable still present in the body is preserved across that detach/reattach cycle; changing the flag still requires the Custom Variables tab of the template the variable was attached on.

On any other object (host, service, command, user, notification), PUT only replaces values: it can never attach a variable that isn’t already available to the object through one of its imported templates; see Attaching a variable to a template for the first time below for how that’s restricted.

Setting a `string` variable¶

POST director/host/variables?name=apitest

{ "environment": "production" }

Setting a `number` variable¶

POST director/service/variables?name=Uptime&host=apitest

{ "snmp_timeout": 30 }

Setting a `bool` variable¶

POST director/host/variables?name=apitest

{ "ssl_verify": true }

Setting a `sensitive` variable¶

POST director/host/variables?name=apitest

{ "snmp_community": "s3cr3t-community" }

A sensitive variable is masked in object forms and in the Icinga DB read view, but that masking doesn’t extend to the API. A GET on this object returns snmp_community with its real value, not ***, since the API is meant to give you back exactly what’s stored. Keep that in mind when logging requests or sharing API responses.

The Preview tab for the objects in the Director web UI is likewise unmasked: it renders the generated Icinga 2 configuration exactly as it will be deployed, sensitive values included in cleartext. Treat that page with the same care as the API response.

Setting an array variable (`fixed-array`, `dynamic-array`, or a datalist array)¶

POST director/host/variables?name=apitest

{ "ssh_args": ["monitoring", "22", "/etc/icinga2/ssh/id_rsa"] }

A datalist-strict property only accepts values from its datalist, scalar or array. If an entry is limited to certain roles, the API user needs one of those roles too, just like the object form already requires. A value blocked by a role restriction is rejected the same way as a value that isn’t in the list at all, so make sure any automation user has the right role before it writes such a property.

Setting a dictionary variable (`fixed-dictionary`)¶

POST director/host/variables?name=apitest

{
    "mysql": {
        "host": "db-primary.internal",
        "port": "3306",
        "user": "icinga_monitor",
        "password": "s3cr3t",
        "database": "app_production"
    }
}

Only the outer shape is currently checked here, the value must be a JSON object. The individual keys inside it are not yet validated against the property’s configured keys and per-key types, so a request using the wrong keys can still be accepted.

A dynamic-dictionary works the same way, but its top-level keys are chosen by whoever sends the request instead of coming from the property’s schema. The same limitation from Handling custom variables applies here too, a key made up only of digits (e.g. "0") isn’t supported and gets miscast into a plain list, so avoid purely numeric keys in the JSON body as well.

Setting several variables at once¶

POST director/host/variables?name=apitest

{
    "environment": "production",
    "owner_teams": ["networking", "platform"]
}

Response¶

Just like GET on the object’s base endpoint, the response is the full object, not just the variables you sent; vars contains every custom variable currently set on apitest, including ones this call didn’t touch.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "object_name": "apitest",
    "object_type": "object",
    "address": "127.0.0.1",
    "vars": {
        "environment": "production",
        "owner_teams": [
            "networking",
            "platform"
        ]
    }
}

Replacing all variables set on an object¶

Unlike the examples above, PUT drops every custom variable previously set directly on apitest before applying the body, so only environment survives this call even if other variables had been set before:

PUT director/host/variables?name=apitest

{ "environment": "production" }

Unlike a plain object PUT, this always answers 200 OK, even when the submitted variables are identical to what was already stored. The activity log, however, only gets a new entry when a value actually changed, so a 200 response here does not guarantee a corresponding log entry.

Clearing a variable’s value¶

POST director/host/variables?name=apitest

{ "mysql": null }

Sending null for a variable that is already attached to (or inherited by) the object clears its local override, the object falls back to whatever it inherits from its templates, or to nothing if it doesn’t inherit anything. This works for arrays and dictionaries the same as it does for plain values.

#### Attaching a variable to a template for the first time¶

Both POST and PUT can update the value of a variable that is already attached to the object (or inherited from one of its imported templates). Only PUT, and only when the target object is itself a template, can additionally attach a variable that is configured under Custom Variables but not yet used on that template; Director creates the attachment and then stores the value in the same call.

PUT director/host/variables?name=generic-host

{ "datacenter": "eu-west-1" }

Sending the very same body with POST instead fails, because POST is not allowed to change which custom variables are attached to a template.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "The custom variable datacenter should be first added to the template"
}

The same restriction applies to non-template objects (hosts, services, …) regardless of method. A variable must first be attached to one of the object’s imported templates before it can be set on the object itself.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "The custom variable datacenter should be first added to one of the imported templates for this object"
}

Not every template type supports attachment at all. A service set is a template but can never have a custom variable attached to it, so a PUT to director/serviceset/variables for an unattached key is rejected outright, whether or not the value is null:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "The custom variable datacenter can not be attached, this object type does not support custom properties"
}

#### Variable not configured

The message depends on how the variable is unknown.

On POST, or on PUT to a non-template object, a variable that isn’t yet attached to the object gets the same “should be first added…” error shown above, whether or not it has been configured under Custom Variables elsewhere. This applies whether the value sent is null or real, a null value does not change the outcome on these paths.
Only PUT to a template distinguishes the case where the variable has never been configured under Custom Variables at all, meaning there is no matching top-level entry in Custom Variables to attach. An unknown key like this is rejected below, whether or not the value is null.
A null value in a template PUT for a key that is configured under Custom Variables, just not yet attached to this template, is a silent no-op: nothing is attached, nothing is rejected. Only a non-null value on this path actually attaches the property.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "error": "'unknown_var' is not configured in Icinga Director as a custom variable"
}

GET¶

GET is also accepted on this endpoint.

GET director/host/variables?name=apitest

It behaves exactly like GET on the object’s base endpoint (director/host?name=apitest) and returns the full object, not just its custom variables; there’s no dedicated “variables only” response. Use the properties parameter if you only want the vars property back.

GET director/host/variables?name=apitest&properties=vars

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

{
    "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

{
  "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

{
    "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

{
    "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

{
  "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

{"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

{
    "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

{"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

{"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

{
    "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

{
    "object_name": "apitest",
    "object_type": "object",
    "vars": {
        "event": [
            "Icinga",
            "Camp"
        ]
    }
}

Let’s put “nothing”:

PUT director/host?name=apitest

{}

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

{
    "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

{
    "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

{
    "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

{
    "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?configs=617b9cbad9e141cfc3f4cb636ec684bd60073be2,
617b9cbad9e141cfc3f4cb636ec684bd60073be1&activitiess=617b9cbad9e141cfc3f4cb636ec684bd60073be1,
028b3a19ca7457f5fc9dbb5e4ea527eaf61616a2

{
    "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

"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    |
                                         +---------------------+

The Icinga Director REST API¶

Introduction¶

Base Headers¶

Authentication¶

Versioning¶

URL scheme and supported methods¶

First example request with CURL¶

CURL helper script¶

Should I use HTTPS?¶

Icinga Objects¶

Special parameters¶

Resolve object properties¶

Retrieve default (null) properties also¶

Fetch host with it’s services¶

Retrieve only specific properties¶

Override vars for inherited/applied Services¶

Example¶

Custom Variables¶

Setting a string variable¶

Setting a number variable¶

Setting a bool variable¶

Setting a sensitive variable¶

Setting an array variable (fixed-array, dynamic-array, or a datalist array)¶

Setting a dictionary variable (fixed-dictionary)¶

Setting several variables at once¶

Response¶

Replacing all variables set on an object¶

Clearing a variable’s value¶

#### Attaching a variable to a template for the first time¶

GET¶

Error handling¶

Trigger actions¶

More¶

Sample scenario¶

Create a new host¶

Response¶

Service Apply Rules¶

Deployment Status¶

Agent Tickets¶

Self Service API¶

Theory of operation¶

Request processing for Host registration¶

Setting a `string` variable¶

Setting a `number` variable¶

Setting a `bool` variable¶

Setting a `sensitive` variable¶

Setting an array variable (`fixed-array`, `dynamic-array`, or a datalist array)¶

Setting a dictionary variable (`fixed-dictionary`)¶