tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
icinga2/doc/9-icinga2-api.md

17 KiB
Raw Blame History

Icinga 2 API

Introduction

The Icinga 2 API allows you to manage configuration objects and resources in a simple, programmatic way using HTTP requests.

The endpoints are logically separated allowing you to easily make calls to

  • retrieve information (status, config)
  • run actions (reschedule checks, etc.)
  • create/update/delete configuration objects
  • manage configuration modules
  • subscribe to event streams

This chapter will start with a general overview followed by detailed information about specific endpoints.

<a id="icinga2-api-requests> Requests

Any tool capable of making HTTP requests can communicate with the API, for example curl.

Requests are only allowed to use the HTTPS protocol so that traffic remains encrypted.

By default the Icinga 2 API listens on port 5665 sharing this port with the cluster communication protocol. This can be changed by setting the bind_port attribute in the ApiListener configuration object in the /etc/icinga2/features-available/api.conf file.

Supported request methods:

Method Usage
GET Retrieve information about configuration objects. Any request using the GET method is read-only and does not affect any objects.
POST Update attributes of a specified configuration object.
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.

<a id="icinga2-api-http-statuses> HTTP Statuses

The API will return standard HTTP statuses including error codes.

When an error occurs, the response body will contain additional information about the problem and its source.

A status in the range of 200 generally means that the request was succesful and no error was encountered.

Return codes within the 400 range indicate that there was a problem with the request. Either you did not authenticate correctly, you are missing the authorization for your requested action, the requested object does not exist or the request was malformed.

A status in the range of 500 generally means that there was a server-side problem and Icinga 2 is unable to process your request currently.

Ask your Icinga 2 system administrator to check the icinga2.log file for further troubleshooting.

<a id="icinga2-api-responses> Responses

Succesful requests will send back a response body containing a results list. Depending on the number of affected objects in your request, the results may contain one or more entries.

The output will be sent back as JSON object:

{
    "results": [
        {
            "code": 200.0,
            "status": "Object was created."
        }
    ]
}

<a id="icinga2-api-authentication> Authentication

There are two different ways for authenticating against the Icinga 2 API:

  • username and password using HTTP basic auth
  • X.509 certificate with client CN

In order to configure a new API user you'll need to add a new ApiUser configuration object. In this example root will be the basic auth username and the password attribute contains the basic auth password.

vim /etc/icinga2/conf.d/api-users.conf

object ApiUser "root" {
  password = icinga"
}

Alternatively you can use X.509 client certificates by specifying the client_cn the API should trust.

vim /etc/icinga2/conf.d/api-users.conf

object ApiUser "api-clientcn" {
  password = "CertificateCommonName"
}

An ApiUser object can have both methods configured. Sensitive information such as the password will not be exposed through the API itself.

New installations of Icinga 2 will automatically generate a new ApiUser named root with a generated password in the /etc/icinga2/conf.d/api-users.conf file. You can manually invoke the cli command icinga2 api setup which will generate a new local CA, self-signed certificate and a new API user configuration.

Once the API user is configured make sure to restart Icinga 2:

# service icinga2 restart

Now pass the basic auth information to curl and send a GET request to the API:

$ curl -u root:icinga -k -s 'https://nbmif.int.netways.de:5665/v1' -X GET

In case you will get Unauthorized make sure to check the API user credentials.

<a id="icinga2-api-permissions> Permissions

TODO https://dev.icinga.org/issues/9088

<a id="icinga2-api-parameters> Parameters

Depending on the request method there are two ways of passing parameters to the request:

  • JSON body (POST, PUT)
  • Query string (GET, DELETE)

Reserved characters by the HTTP protocol must be passed url-encoded as query string, e.g. a whitespace becomes %20.

Example for query string:

/v1/hosts?filter=match(%22nbmif*%22,host.name)&attrs=host.name&attrs=host.state

Example for JSON body:

{ "attrs": { "address": "8.8.4.4", "vars.os" : "Windows" } }

TODO

<a id="icinga2-api-filters> Filters

Use the same syntax as for apply rule expressions for filtering specific objects.

Example for all services in NOT-OK state:

https://localhost:5665/v1/services?filter=service.state!=0

Example for matching all hosts by name (Note: " are url-encoded as %22):

https://localhost:5665/v1/hosts?filter=match(%22nbmif*%22,host.name)

TODO

<a id="icinga2-api-output-format>Output Format

The request and reponse body contain a JSON encoded string.

<a id="icinga2-api-version>Version

Each url contains the version string as prefix (currently "/v1").

<a id="icinga2-api-url-overview>Url Overview

The Icinga 2 API provides multiple url endpoints

Url Endpoints Description
/v1/actions Endpoint for running specific API actions.
/v1/config Endpoint for managing configuration modules.
/v1/events Endpoint for subscribing to API events.
/v1/types Endpoint for listing Icinga 2 configuration object types and their attributes.

Additionally there are endpoints for each config object type:

TODO Update

Url Endpoints Description
/v1/hosts Endpoint for retreiving and updating Host objects.
/v1/services Endpoint for retreiving and updating Service objects.
/v1/notifications Endpoint for retreiving and updating Notification objects.
/v1/dependencies Endpoint for retreiving and updating Dependency objects.
/v1/users Endpoint for retreiving and updating User objects.
/v1/checkcommands Endpoint for retreiving and updating CheckCommand objects.
/v1/eventcommands Endpoint for retreiving and updating EventCommand objects.
/v1/notificationcommands Endpoint for retreiving and updating NotificationCommand objects.
/v1/hostgroups Endpoint for retreiving and updating HostGroup objects.
/v1/servicegroups Endpoint for retreiving and updating ServiceGroup objects.
/v1/usergroups Endpoint for retreiving and updating UserGroup objects.
/v1/zones Endpoint for retreiving and updating Zone objects.
/v1/endpoints Endpoint for retreiving and updating Endpoint objects.
/v1/timeperiods Endpoint for retreiving and updating TimePeriod objects.

<a id="icinga2-api-actions> Actions

There are several actions available for Icinga 2 provided by the actions url endpoint.

In case you have been using the external commands in the past, the API actions provide a yet more powerful interface with filters and even more functionality.

Actions require specific target types (e.g. type=Host) and a filter

TODO

Action name Parameters Target types Notes
process-check-result exit_status; plugin_output; check_source; performance_data[]; check_command[]; execution_end; execution_start; schedule_end; schedule_start Service; Host -
reschedule-check {next_check}; {(force_check)} Service; Host -
acknowledge-problem author; comment; {timestamp}; {(sticky)}; {(notify)} Service; Host -
remove-acknowledgement - Service; Host -
add-comment author; comment Service; Host -
remove-comment - Service;Host -
remove-comment-by-id comment_id - -
delay-notifications timestamp Service;Host -
add-downtime start_time; end_time; duration; author; comment; {trigger_id}; {(fixed)} Service; Host; ServiceGroup; HostGroup Downtime for all services on host x?
remove-downtime - Service; Host -
remove-downtime-by-id downtime_id - -
send-custom-notification options[]; author; comment Service; Host -

enable-passive-checks | - | Service; Host; ServiceGroup; HostGroup | "System" as target? disable-passive-checks | - | Service; Host; ServiceGroup; HostGroup | diable all passive checks for services of hosts y in hostgroup x? enable-active-checks | - | Host; HostGroup | - disable-active-checks | - | Host; HostGroup | - enable-notifications | - | Service; Host; ServiceGroup; HostGroup | Enable all notifications for services of host x? disable-notifications | - | Service; Host; ServiceGroup; HostGroup | - enable-flap-detection | - | Service; Host; ServiceGroup; HostGroup | - disable-flap-detection | - | Service; Host; ServiceGroup; HostGroup | - enable-event-handler | - | Service; Host | - disable-event-handler | - | Service; Host | -

enable-global-notifications | - | - | - disable-global-notifications | - | - | - enable-global-flap-detection | - | - | - disable-global-flap-detection | - | - | - enable-global-event-handlers | - | - | - disable-global-event-handlers | - | - | - enable-global-performance-data | - | - | - disable-global-performance-data | - | - | - start-global-executing-svc-checks | - | - | - stop-global-executing-svc-checks | - | - | - start-global-executing-host-checks | - | - | - stop-global-executing-host-checks | - | - | - shutdown-process | - | - | - restart-process | - | - | -

Examples:

Reschedule a service check for all services in NOT-OK state:

$ curl -u root:icinga -k -s 'https://localhost:5665/v1/actions/reschedule-check?filter=service.state!=0&type=Service' -X POST | python -m json.tool
{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully rescheduled check for nbmif.int.netways.de!http."
        },
        {
            "code": 200.0,
            "status": "Successfully rescheduled check for nbmif.int.netways.de!disk."
        },
        {
            "code": 200.0,
            "status": "Successfully rescheduled check for nbmif.int.netways.de!disk /."
        }
    ]
}

<a id="icinga2-api-config-management> Configuration Management

/v1/config

TODO Depends on https://dev.icinga.org/issues/9953

<a id="icinga2-api-events> Events

TODO

<a id="icinga2-api-hosts> Hosts

All object attributes are prefixed with their respective object type.

Example:

host.address

Output listing and url parameters use the same syntax.

<a id="icinga2-api-hosts-list> List All Hosts

Send a GET request to /v1/hosts to list all host objects and their attributes.

$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts' -X GET

<a id="icinga2-api-hosts-create> Create New Host Object

New objects must be created by sending a PUT request. The following parameters need to be passed inside the JSON body:

Parameters Description
name Optional. If not specified inside the url, this is required.
templates Optional. Import existing configuration templates, e.g. generic-host.
attrs Required. Set specific Host object attributes.

If attributes are of the Dictionary type, you can also use the indexer format:

"attrs": { "vars.os": "Linux" }

Example:

$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' \
-X PUT \
-d '{ "templates": [ "generic-host" ], "attrs": { "address": "8.8.8.8", "vars.os" : "Linux" } }' \
| python -m json.tool
{
    "results": [
        {
            "code": 200.0,
            "status": "Object was created."
        }
    ]
}

Note: Host objects require the check_command attribute. In the example above the generic-host template already provides such.

If the configuration validation fails, the new object will not be created and the response body contains a detailed error message. The following example omits the required check_command attribute.

$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' \
-X PUT \
-d '{ "attrs": { "address": "8.8.8.8", "vars.os" : "Linux" } }' \
| python -m json.tool
{
    "results": [
        {
            "code": 500.0,
            "errors": [
                "Error: Validation failed for object 'google.com' of type 'Host'; Attribute 'check_command': Attribute must not be empty."
            ],
            "status": "Object could not be created."
        }
    ]
}

<a id="icinga2-api-hosts-show> Show Host

Send a GET request including the host name inside the url:

$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' -X GET

You can select specific attributes by adding them as url parameters using ?attrs=.... Multiple attributes must be added one by one, e.g. ?attrs=host.address&attrs=host.name.

$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com?attrs=host.name&attrs=host.address' -X GET | python -m json.tool
{
    "results": [
        {
            "attrs": {
                "host.address": "8.8.8.8",
                "host.name": "google.com"
            }
        }
    ]
}

<a id="icinga2-api-hosts-modify> Modify Host

Existing objects must be modifed by sending a POST request. The following parameters need to be passed inside the JSON body:

Parameters Description
name Optional. If not specified inside the url, this is required.
templates Optional. Import existing configuration templates, e.g. generic-host.
attrs Required. Set specific Host object attributes.

If attributes are of the Dictionary type, you can also use the indexer format:

"attrs": { "vars.os": "Linux" }

Example for existing object google.com:

$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' \
-X POST \
-d '{ "attrs": { "address": "8.8.4.4", "vars.os" : "Windows" } }' \
| python -m json.tool
{
    "results": [
        {
            "code": 200.0,
            "name": "google.com",
            "status": "Attributes updated.",
            "type": "Host"
        }
    ]
}

<a id="icinga2-api-hosts-delete> Delete Host

You can delete objects created using the API by sending a DELETE request. Specify the object name inside the url.

Parameters Description
cascade Optional. Delete objects depending on the deleted objects (e.g. services on a host).

Example:

$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com?cascade=1' -X DELETE | python -m json.tool
{
    "results": [
        {
            "code": 200.0,
            "name": "google.com",
            "status": "Object was deleted.",
            "type": "Host"
        }
    ]
}

TODO Add more config objects