50 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 URL endpoints are logically separated allowing you to easily make calls to

run actions (reschedule checks, etc.)
query, create, modify and delete config objects
manage configuration packages
subscribe to event streams

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

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 which is shared with the cluster stack. The port 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.

Each URL contains the version string as prefix (currently "/v1"). Be prepared to see additional fields being added in future versions. New fields could be added even with minor releases. Modifications to existing fields are considered backward-compatibility-breaking and will only take place in new API versions.

The request and response bodies contain a JSON-encoded object.

Request Method Override

GET requests do not allow to send a request body. In case you cannot pass everything as URL parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the X-HTTP-Method-Override header. This comes in handy when you are using HTTP proxies disallowing PUT or DELETE requests too.

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 '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: GET as request header:

$ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: DELETE' -X POST 'https://localhost:5665/v1/objects/hosts/icinga.org'

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 code between 200 and 299 generally means that the request was successful.

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.

Responses

Successful 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 a JSON object:

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

Authentication

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

username and password using HTTP basic auth
X.509 certificate

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. The X.509 certificate has to be signed by the CA certificate that is configured in the ApiListener object.

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

object ApiUser "api-clientcn" {
  client_cn = "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 set up a new ApiUser named root with an auto-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

You can test authentication by sending a GET request to the API:

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

In case you get an error message make sure to check the API user credentials.

Read the next chapter on API permissions in order to authorize the newly created API user.

Permissions

By default an API user does not have any permissions to perform actions on the URL endpoints.

Permissions for API users must be specified in the permissions attribute as array. The array items can be a list of permission strings with wildcard matches.

Example for an API user with all permissions:

permissions = [ "*" ]

A yet more sophisticated approach is to specify additional permissions and their filters. The latter must be defined as lambda function returning a boolean expression.

The permission attribute contains the action and the specific capitalized object type name. Instead of the type name it is also possible to use a wildcard match.

The following example allows the API user to query all hosts and services with the custom host attribute os matching the regular expression ^Linux.

permissions = [
  {
    permission = "objects/query/Host"
    filter = {{ regex("^Linux", host.vars.os)  }}
  },
  {
    permission = "objects/query/Service"
    filter = {{ regex("^Linux", host.vars.os)  }}
  },
]

Available permissions for specific URL endpoints:

Permissions	URL Endpoint
actions/<action>	/v1/actions
config/query	/v1/config
config/modify	/v1/config
objects/query/<type>	/v1/objects
objects/create/<type>	/v1/objects
objects/modify/<type>	/v1/objects
objects/delete/<type>	/v1/objects
status/query	/v1/status
events/<type>	/v1/events

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:

JSON object as request body (POST, PUT)
Query string as URL parameter (GET, DELETE)

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

Example for an URL-encoded query string:

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

Example for a JSON body:

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

Selecting a single object as URL parameter:

?host=icinga.org

Selecting multiple objects as URL parameter:

?hosts=host1&hosts=host2&hosts=host3

The array-append-notation is also supported:

?hosts[]=host1&hosts[]=host2&hosts[]=host3

Filters

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

Note

Filters used as URL parameter must be URL-encoded. The following examples are not URL-encoded for better readability.

Example matching all services in NOT-OK state:

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

Example matching all hosts by name:

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

Example for all hosts being a member of the host group linux-servers:

https://localhost:5665/v1/objects/hosts?filter="linux-servers" in host.groups

In order to add complex filters with specific filter variables it is possible to send a POST request using X-HTTP-Method-Override: GET. Add the filter and filter_vars attributes to the request body and receive all host objects matching the filter:

$ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/hosts' \
-d '{ "filter": "host.vars.os == os", "filter_vars": { "os": "Linux" } }'

The filters_vars attribute can only be used inside the request body, but not as URL parameter.

URL Endpoints

The Icinga 2 API provides multiple URL endpoints:

URL Endpoints	Description
/v1/actions	Endpoint for running specific API actions.
/v1/events	Endpoint for subscribing to API events.
/v1/status	Endpoint for receiving the global Icinga 2 status and statistics.
/v1/objects	Endpoint for querying, creating, modifying and deleting config objects.
/v1/types	Endpoint for listing Icinga 2 configuration object types and their attributes.
/v1/config	Endpoint for managing configuration modules.

Please check the respective sections for detailed URL information and parameters.

Actions

There are several actions available for Icinga 2 provided by the actions URL endpoint /v1/actions. You can run actions by sending a POST request.

In case you have been using the 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.

Some actions require specific target types (e.g. type=Host) and a filter expression. For each object matching the filter the action in question is performed once.

These parameters may either be passed as an URL query string (e.g. url/actions/action-name?list=of&parameters) or as key-value pairs in a JSON-formatted payload or a mix of both.

All actions return a 200 OK or an appropriate error code for each action performed on each object matching the supplied filter.

Actions which affect the Icinga Application itself such as disabling notification on a program-wide basis must be applied by updating the IcingaApplication object called app.

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' -d '{ "attrs": { "enable_notifications": false } }'

process-check-result

Process a check result for a host or a service.

Send a POST request to the URL endpoint /v1/actions/process-check-result.

Parameter	Type	Description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.
exit_status	integer	Required. For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=OK, 1=CRITICAL.
plugin_output	string	Required. The plugins main output, i.e. the text before the `
performance_data	string array	Optional. One array entry per `;` separated block.
check_command	string array	Optional. The first entry should be the check commands path, then one entry for each command line option followed by an entry for each of its argument.
check_source	string	Optional. Usually the name of the `command_endpoint`

This is used to submit a passive check result for a service or host. Passive checks need to be enabled for the check result to be processed.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/process-check-result?type=Service&filter=service.name==%22ping6%22' \
-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": "icinga2-node1.localdomain" }' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully processed check result for object 'localhost!ping6'."
        }
    ]
}

reschedule-check

Reschedule a check for hosts and services. The check can be forced if required.

Send a POST request to the URL endpoint /v1/actions/reschedule-check.

Parameter	Type	Description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.
next_check	timestamp	Optional. The next check will be run at this time. If omitted the current time is used.
force_check	boolean	Optional. Defaults to `false`. If enabled the checks are executed regardless of time period restrictions and checks being disabled per object or on a global basis.

The example reschedules all services with the name "ping6" to immediately perform a check (next_check default), ignoring any time periods or whether active checks are allowed for the service (force_check=true).

$ curl -k -s -u root:icinga -X POST "https://localhost:5665/v1/actions/reschedule-check?type=Service&filter=service.name==%22ping6%22" \
-d '{ "force_check": true }' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully rescheduled check for object 'localhost!ping6'."
        }
    ]
}

send-custom-notification

Send a custom notification for hosts and services. This notification type can be forced being sent to all users.

Send a POST request to the URL endpoint /v1/actions/send-custom-notification.

Parameter	Type	Description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.
author	string	Required. Name of the author, may be empty.
comment	string	Required. Comment text, may be empty.
force	boolean	Optional. Default: false. If true, the notification is sent regardless of downtimes or whether notifications are enabled or not.

Example for a custom host notification announcing a global maintenance to host owners:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/send-custom-notification' \
-d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true }' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully sent custom notification for object 'host0'."
        },
        {
            "code": 200.0,
            "status": "Successfully sent custom notification for object 'host1'."
        }
}

delay-notification

Delay notifications for a host or a service. Note that this will only have an effect if the service stays in the same problem state that it is currently in. If the service changes to another state, a new notification may go out before the time you specify in the timestamp argument.

Send a POST request to the URL endpoint /v1/actions/delay-notification.

Parameter	Type	Description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.
timestamp	timestamp	Required. Delay notifications until this timestamp.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/delay-notification' \
-d '{ "type": "Service", "timestamp": 1446389894 }' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully delayed notifications for object 'host0!service0'."
        },
        {
            "code": 200.0,
            "status": "Successfully delayed notifications for object 'host1!service1'."
        }
}

acknowledge-problem

Allows you to acknowledge the current problem for hosts or services. By acknowledging the current problem, future notifications (for the same state if sticky is set to false) are disabled.

Send a POST request to the URL endpoint /v1/actions/acknowledge-problem.

Parameter	Type	Description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.
author	string	Required. Name of the author, may be empty.
comment	string	Required. Comment text, may be empty.
expiry	timestamp	Optional. If set the acknowledgement will vanish after this timestamp.
sticky	boolean	Optional. If `true`, the default, the acknowledgement will remain until the service or host fully recovers.
notify	boolean	Optional. If `true` a notification will be sent out to contacts to indicate this problem has been acknowledged. The default is false.

The following example acknowledges all services which are in a hard critical state and sends out a notification for them:

$ curl -k -s -u root:icinga -X POST 'https://localhost:566tions/acknowledge-problem?type=Service&filter=service.state==2&service.state_type=1' \
-d '{ "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true }' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully acknowledged problem for object 'i-42866686!ping4'."
        },
        {
            "code": 200.0,
            "status": "Successfully acknowledged problem for object 'i-43866687!ping4'."
        }
}

remove-acknowledgement

Removes the acknowledgements for services or hosts. Once the acknowledgement has been removed notifications will be sent out again.

Send a POST request to the URL endpoint /v1/actions/remove-acknowledgement.

parameter	type	description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.

The example removes all service acknowledgements:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/remove-acknowledgement?type=Service' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully removed acknowledgement for object 'host0!service0'."
        },
        {
            "code": 200.0,
            "status": "Successfully removed acknowledgement for object 'i-42866686!aws-health'."
        }
}

add-comment

Adds a comment from an author to services or hosts.

Send a POST request to the URL endpoint /v1/actions/add-comment.

parameter	type	description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.
author	string	Required. name of the author, may be empty.
comment	string	Required. Comment text, may be empty.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/add-comment?type=Service&filter=service.name==%22ping4%22' -d '{ "author": "icingaadmin", "comment": "Troubleticket #123456789 opened." }' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "comment_id": "i-42866686!ping4!mbmif.local-1446390475-55",
            "legacy_id": 2.0,
            "status": "Successfully added comment with id 'i-42866686!ping4!mbmif.local-1446390475-55' for object 'i-42866686!ping4'."
        }
}

remove-all-comments

Removes all comments for services or hosts.

Send a POST request to the URL endpoint /v1/actions/remove-all-comments.

parameter	type	description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/remove-all-comments?type=Service' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully removed comments for object 'i-42866686!aws-health'."
        },
        {
            "code": 200.0,
            "status": "Successfully removed comments for object 'i-43866687!aws-health'."
        }
}

remove-comment-by-id

Tries to remove the comment with the ID comment_id, returns OK if the comment did not exist. Note: This is not the legacy ID but the comment ID returned by Icinga 2 itself.

Send a POST request to the URL endpoint /v1/actions/remove-comment-by-id.

parameter	type	description
comment_id	integer	Required. ID of the comment to remove.

Does not support a target type or filters.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/remove-comment-by-id?comment_id=i-43866687!ping4!mbmif.local-1446390475-56' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully removed comment 'i-43866687!ping4!mbmif.local-1446390475-56'."
        }
    ]
}

schedule-downtime

Schedule a downtime for hosts and services.

Send a POST request to the URL endpoint /v1/actions/schedule-downtime.

parameter	type	description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.
start_time	timestamp	Required. Timestamp marking the beginning of the downtime.
end_time	timestamp	Required. Timestamp marking the end of the downtime.
duration	integer	Required. Duration of the downtime in seconds if `fixed` is set to false.
fixed	boolean	Optional. Defaults to `false`. If true the downtime is `fixed` otherwise `flexible`. See downtimes for more information.
trigger_id	integer	Optional. Sets the trigger for a triggered downtime. See downtimes for more information on triggered downtimes.

Example:

$ curl -k -s -u root:icinga -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" }' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "downtime_id": "i-42866686!ping4!mbmif.local-1446388986-545",
            "legacy_id": 8.0,
            "status": "Successfully scheduled downtime with id 'i-42866686!ping4!mbmif.local-1446388986-545' for object 'i-42866686!ping4'."
        },
        {
            "code": 200.0,
            "downtime_id": "i-43866687!ping4!mbmif.local-1446388986-546",
            "legacy_id": 9.0,
            "status": "Successfully scheduled downtime with id 'i-43866687!ping4!mbmif.local-1446388986-546' for object 'i-43866687!ping4'."
        }
    ]
}

remove-all-downtimes

Removes all downtimes for services or hosts.

Send a POST request to the URL endpoint /v1/actions/remove-all-downtimes.

parameter	type	description
type	string	Required. `Host` or `Service`.
filter	string	Optional. Apply the action only to objects matching the filter.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/remove-all-downtimes?type=Service&filter=service.name==%22ping4%22' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully removed downtimes for object 'i-42866686!ping4'."
        },
        {
            "code": 200.0,
            "status": "Successfully removed downtimes for object 'i-43866687!ping4'."
        }
    ]
}

remove-downtime-by-id

Tries to remove the downtime with the ID downtime_id, returns OK if the downtime did not exist. Note: This is not the legacy ID but the downtime ID returned by Icinga 2 itself.

Send a POST request to the URL endpoint /v1/actions/remove-downtime-by-id.

parameter	type	description
downtime_id	integer	Required. ID of the downtime to remove.

Does not support a target type or filter.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/remove-downtime-by-id?downtime_id=mbmif.local-1446339731-582' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Successfully removed downtime 'mbmif.local-1446339731-582'."
        }
    ]
}

shutdown-process

Shuts down Icinga2. May or may not return.

Send a POST request to the URL endpoint /v1/actions/shutdown-process.

This action does not support a target type or filter.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/shutdown-process' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Shutting down Icinga 2."
        }
    ]
}

restart-process

Restarts Icinga2. May or may not return.

Send a POST request to the URL endpoint /v1/actions/restart-process.

This action does not support a target type or filter.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/actions/restart-process' | python -m json.tool

{
    "results": [
        {
            "code": 200.0,
            "status": "Restarting Icinga 2."
        }
    ]
}

Event Streams

You can subscribe to event streams by sending a POST request to the URL endpoint /v1/events. The following parameters need to be passed as URL parameters:

Parameters	Description
types	Required. Event type(s). Multiple types as URL parameters are supported.
queue	Required. Unique queue name. Multiple HTTP clients can use the same queue with existing filters.
filter	Optional. Filter for specific event attributes using filter expressions.

Event Stream Types

The following event stream types are available:

Type	Description
CheckResult	Check results for hosts and services.
StateChange	Host/service state changes.
Notification	Notification events including notified users for hosts and services.
AcknowledgementSet	Acknowledgement set on hosts and services.
AcknowledgementCleared	Acknowledgement cleared on hosts and services.
CommentAdded	Comment added for hosts and services.
CommentRemoved	Comment removed for hosts and services.
DowntimeAdded	Downtime added for hosts and services.
DowntimeRemoved	Downtime removed for hosts and services.
DowntimeTriggered	Downtime triggered for hosts and services.

Note: Each type requires api permissions being set.

Example for all downtime events:

&types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered

Event Stream Filter

Event streams can be filtered by attributes using the prefix event..

Example for the CheckResult type with the exit_code set to 2:

&types=CheckResult&filter=event.check_result.exit_status==2

Example for the CheckResult type with the service matching the string "random":

&types=CheckResult&filter=match%28%22random*%22,event.service%29

Event Stream Response

The event stream response is separated with new lines. The HTTP client must support long-polling and HTTP/1.1. HTTP/1.0 is not supported.

Example:

$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=michi&types=CheckResult&filter=event.check_result.exit_status==2'

{"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421319.7226390839,"type":"CheckResult"}
{"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421324.7226390839,"type":"CheckResult"}
{"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421329.7226390839,"type":"CheckResult"}

Status and Statistics

Send a POST request to the URL endpoint /v1/status for retrieving the global status and statistics.

Contains a list of sub URL endpoints which provide the status and statistics of available and enabled features. Any filters are ignored.

Example for the main URL endpoint /v1/status:

$ curl -k -s -u root:icinga 'https://localhost:5665/v1/status' | python -m json.tool
{
    "results": [
        {
            "name": "ApiListener",
            "perfdata": [ ... ],
            "status": [ ... ]
        },
        ...
        {
            "name": "IcingaAplication",
            "perfdata": [ ... ],
            "status": [ ... ]
        },
        ...
    ]
}

/v1/status is always available as virtual status URL endpoint. It provides all feature status information in a collected overview.

Example for the IcingaApplication URL endpoint /v1/status/IcingaApplication:

$ curl -k -s -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication' | python -m json.tool
{
    "results": [
        {
            "perfdata": [],
            "status": {
                "icingaapplication": {
                    "app": {
                        "enable_event_handlers": true,
                        "enable_flapping": true,
                        "enable_host_checks": true,
                        "enable_notifications": true,
                        "enable_perfdata": true,
                        "enable_service_checks": true,
                        "node_name": "icinga.org",
                        "pid": 59819.0,
                        "program_start": 1443019345.093372,
                        "version": "v2.3.0-573-g380a131"
                    }
                }
            }
        }
    ]
}

Config Objects

Provides functionality for all configuration object URL endpoints provided by config object types:

URL Endpoints	Description
/v1/objects/hosts	Endpoint for retrieving and updating Host objects.
/v1/objects/services	Endpoint for retrieving and updating Service objects.
/v1/objects/notifications	Endpoint for retrieving and updating Notification objects.
/v1/objects/dependencies	Endpoint for retrieving and updating Dependency objects.
/v1/objects/users	Endpoint for retrieving and updating User objects.
/v1/objects/checkcommands	Endpoint for retrieving and updating CheckCommand objects.
/v1/objects/eventcommands	Endpoint for retrieving and updating EventCommand objects.
/v1/objects/notificationcommands	Endpoint for retrieving and updating NotificationCommand objects.
/v1/objects/hostgroups	Endpoint for retrieving and updating HostGroup objects.
/v1/objects/servicegroups	Endpoint for retrieving and updating ServiceGroup objects.
/v1/objects/usergroups	Endpoint for retrieving and updating UserGroup objects.
/v1/objects/zones	Endpoint for retrieving and updating Zone objects.
/v1/objects/endpoints	Endpoint for retrieving and updating Endpoint objects.
/v1/objects/timeperiods	Endpoint for retrieving and updating TimePeriod objects.
/v1/objects/icingaapplications	Endpoint for retrieving and updating IcingaApplication objects.
/v1/objects/comments	Endpoint for retrieving and updating Comment objects.
/v1/objects/downtimes	Endpoint for retrieving and updating Downtime objects.

All object attributes are prefixed with their respective object type.

Example:

host.address

Output listing and url parameters use the same syntax.

API Objects and Joins

Icinga 2 knows about object relations, i.e. when querying a service object the query handler will automatically add the referenced host object and its attributes to the result set. If the object reference is null (e.g. when no event_command is defined), the joined results not added to the result set.

Note: Select your required attributes beforehand by passing them to your request. The default result set might get huge.

Each joined object will use its own attribute name as prefix for the attribute. There is an exception for multiple objects used in dependencies and zones.

Objects with optional relations (e.g. host notifications without a service) will not be joined.

Object Type	Object Relations (prefix name)
Service	host, notification, check_command, event_command
Host	notification, check_command, event_command
Notification	host, service, command, period
Dependency	child_host, child_service, parent_host, parent_service, period
User	period
Zones	parent

API Objects and Cluster Config Sync

Newly created or updated objects can be synced throughout your Icinga 2 cluster. Set the zone attribute to the zone this object belongs to and let the API and cluster handle the rest. Objects without zone attribute are only synced in the same (HA) zone.

Note

Cluster nodes must accept configuration for creating, modifying and deleting objects. Ensure that accept_config is set to true in the ApiListener object on each node.

If you add a new cluster instance, or boot an instance which has been offline for a while, Icinga 2 takes care of the initial object sync for all objects created by the API.

More information about distributed monitoring, cluster and its configuration can be found here.

List All Objects

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

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

This works in a similar fashion for other config objects.

Create New Config 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	Required. Name of the newly created config object.
templates	Optional. Import existing configuration templates for this object type.
attrs	Required. Set specific object attributes for this object type.

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

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

Example for creating the new host object google.com:

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

Note: Host objects require the check_command attribute.

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 check_command attribute required by the host object.

$ curl -u root:icinga -k -s 'https://localhost:5665/v1/objects/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."
        }
    ]
}

Query Object

Send a GET request including the object name inside the URL.

Example for the host google.com:

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

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/objects/hosts/google.com?attrs=host.name&attrs=host.address' | python -m json.tool
{
    "results": [
        {
            "attrs": {
                "host.address": "8.8.8.8",
                "host.name": "google.com"
            }
        }
    ]
}

Modify Object

Existing objects must be modified 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 object configuration templates.
attrs	Required. Set specific object attributes for this object type.

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/objects/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"
        }
    ]
}

Delete Object

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).

Note: Objects created by apply rules (services, notifications, etc.) will implicitly require to pass the cascade parameter on host object deletion.

Example for deleting the host object google.com:

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

Configuration Management

The main idea behind configuration management is to allow external applications creating 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.

Create Config Package

Send a POST request to a new config package called puppet in this example. This will create a new empty configuration package.

$ curl -k -s -u root:icinga -X POST https://localhost:5665/v1/config/packages/puppet | python -m json.tool
{
    "results": [
        {
            "code": 200.0,
            "package": "puppet",
            "status": "Created package."
        }
    ]
}

Create Configuration to Package Stage

Send a POST request to the URL endpoint /v1/config/stages including an existing configuration package, e.g. puppet. The request body must contain the files attribute with the value being a dictionary of file targets and their content.

The example below will create a new file called test.conf underneath the conf.d directory populated by the sent configuration. The Icinga 2 API returns the package name this stage was created for, and also generates a unique name for the package attribute you'll need for later requests.

Note: This example contains an error (chec_command), do not blindly copy paste it.

$ curl -k -s -u root:icinga -X POST -d '{ "files": { "conf.d/test.conf": "object Host \"cfg-mgmt\" { chec_command = \"dummy\" }" } }' https://localhost:5665/v1/config/stages/puppet | python -m json.tool
{
    "results": [
        {
            "code": 200.0,
            "package": "puppet",
            "stage": "nbmif-1441625839-0",
            "status": "Created stage."
        }
    ]
}

If the configuration fails, the old active stage will remain active. If everything is successful, the new config stage is activated and live. Older stages will still be available in order to have some sort of revision system in place.

Icinga 2 automatically creates the following files in the main configuration package stage:

File	Description
status	Contains the configuration validation exit code (everything else than 0 indicates an error).
startup.log	Contains the configuration validation output.

You can fetch these files via API call after creating a new stage.

List Configuration Packages and their Stages

List all config packages, their active stage and other stages. That way you may iterate of all of them programmatically for older revisions and their requests.

The following example contains one configuration package puppet. The latter already has a stage created, but it is not active.

$ curl -k -s -u root:icinga https://localhost:5665/v1/config/packages | python -m json.tool
{
    "results": [
        {
            "active-stage": "",
            "name": "puppet",
            "stages": [
                "nbmif-1441625839-0"
            ]
        }
    ]
}

List Configuration Packages and their Stages

Sent a GET request to the URL endpoint /v1/config/stages including the package (puppet) and stage (nbmif-1441625839-0) name.

$ curl -k -s -u root:icinga https://localhost:5665/v1/config/stages/puppet/nbmif-1441625839-0 | python -m json.tool
{
    "results": [
...
        {
            "name": "startup.log",
            "type": "file"
        },
        {
            "name": "status",
            "type": "file"
        },
        {
            "name": "conf.d",
            "type": "directory"
        },
        {
            "name": "zones.d",
            "type": "directory"
        },
        {
            "name": "conf.d/test.conf",
            "type": "file"
        }
    ]
}

Fetch Configuration Package Stage Files

Send a GET request to the URL endpoint /v1/config/files including the package name, the stage name and the relative path to the file. Note: You cannot use dots in paths.

You can fetch a list of existing files in a configuration stage and then specifically request their content.

The following example fetches the faulty configuration inside conf.d/test.conf for further analysis.

$ curl -k -s -u root:icinga https://localhost:5665/v1/config/files/puppet/nbmif-1441625839-0/conf.d/test.conf
object Host "cfg-mgmt" { chec_command = "dummy" }

Note: The returned files are plain-text instead of JSON-encoded.

Configuration Package Stage Errors

Now that we don't have an active stage for puppet yet seen here, there must have been an error.

Fetch the startup.log file and check the config validation errors:

$ curl -k -s -u root:icinga https://localhost:5665/v1/config/files/puppet/imagine-1441133065-1/startup.log
...

critical/config: Error: Attribute 'chec_command' does not exist.
Location:
/var/lib/icinga2/api/packages/puppet/imagine-1441133065-1/conf.d/test.conf(1): object Host "cfg-mgmt" { chec_command = "dummy" }
                                                                                                       ^^^^^^^^^^^^^^^^^^^^^^

critical/config: 1 error

The output is similar to the manual configuration validation.

50 KiB Raw Blame History

Icinga 2 API

Introduction

Requests

Request Method Override

HTTP Statuses

Responses

Authentication

Permissions

Parameters

Filters

URL Endpoints

Actions

process-check-result

reschedule-check

send-custom-notification

delay-notification

acknowledge-problem

remove-acknowledgement

add-comment

remove-all-comments

remove-comment-by-id

schedule-downtime

remove-all-downtimes

remove-downtime-by-id

shutdown-process

restart-process

Event Streams

Event Stream Types

Event Stream Filter

Event Stream Response

Status and Statistics

Config Objects

API Objects and Joins

API Objects and Cluster Config Sync

List All Objects

Create New Config Object

Query Object

Modify Object

Delete Object

Configuration Management

Create Config Package

Create Configuration to Package Stage

List Configuration Packages and their Stages

List Configuration Packages and their Stages

Fetch Configuration Package Stage Files

Configuration Package Stage Errors

50 KiB

Raw Blame History