Targeting hosts and services in Icinga 2 API requests

Today, we are going to take a look at the Icinga 2 API and the various ways targets can be specified for different actions, such as querying information or scheduling downtimes. This post focuses on the API request payloads themselves and assumes some familiarity with sending requests to the Icinga 2 API. Please refer to our documentation for the missing details if you want to try the requests yourself.

In general, specifying the objects to which an action applies works the same way for all actions. The following examples will use the reschedule-check action, since the requests and responses are compact and serve as good examples. So all examples are HTTP POST requests to /v1/actions/reschedule-check.

Single object by name

Let’s start with probably the simplest example possible: we know the name of a particular host object and want to rerun its host check. To do so, we can simply give its name as the host parameter:

{
    "host": "agent-1",
    "pretty": true
}

{
    "results": [
        {
            "code": 200,
            "status": "Successfully rescheduled check for object 'agent-1'."
        }
    ]
}

JSON body and URL parameters

As you might know, the parameters can be given both as part of a JSON body or as part of the URL query string. So sending a POST request to /v1/actions/reschedule-check?host=agent-1&pretty=1 with an empty body has the same effect as the JSON body above. The examples here will always use JSON as it can be formatted nicely, making it easier to read.

Multiple objects by name

If you want to perform the same action for multiple hosts, you can also provide a list in the hosts (now plural) parameter. This can also be specified in the URL query string by repeating hosts like in ?hosts=agent-1&hosts=agent-2.

{
    "hosts": ["agent-1", "agent-2"],
    "pretty": true
}

{
    "results": [
        {
            "code": 200,
            "status": "Successfully rescheduled check for object 'agent-1'."
        },
        {
            "code": 200,
            "status": "Successfully rescheduled check for object 'agent-2'."
        }
    ]
}

Objects matching filter expression

The two previous examples all assumed that you already know all the names of the objects, though this might not always be the case. In this case, you can also provide any filter expression in the Icinga 2 config language (i.e. the same syntax used in apply rules) as the filter parameter. In contrast to the examples using host or hosts, this no longer implicitly specifies the target type. Instead, it has to be given as the type parameter explicitly.

{
    "type": "Host",
    "filter": "match(\"agent-*\", host.name)",
    "pretty": true
}

{
    "results": [
        {
            "code": 200,
            "status": "Successfully rescheduled check for object 'agent-1'."
        },
        {
            "code": 200,
            "status": "Successfully rescheduled check for object 'agent-2'."
        },
        {
            "code": 200,
            "status": "Successfully rescheduled check for object 'agent-windows'."
        }
    ]
}

Targeting other object types

This works all the same for other types as well, just say service instead of host and you are ready to go. However, keep in mind that the object names refer to the full names of the individual objects. In case of services, the name isn’t ping but rather something like webserver!ping, i.e. it includes the name of the corresponding host object. So {"service":"ping"} would match nothing, in order to reschedule all ping services on all hosts, you have to use a filter for the request: {"type":"Service","filter":"service.name == \"ping\""}.

Filter variables

As both JSON and the Icinga config language use double quotes for string literals, nesting them like in the previous example is a bit annoying as you need to escape them as \". There is an alternative though: filter variables. In the parameter filter_vars, you can give an additional JSON object that contains variables that will be included in the execution context of the filter expression:

{
    "type": "Service",
    "filter": "service.name == service_to_reschedule",
    "filter_vars": {
        "service_to_reschedule": "ping"
    },
    "pretty": true
}

{
    "results": [
        {
            "code": 200,
            "status": "Successfully rescheduled check for object 'webserver!ping'."
        },
        {
            "code": 200,
            "status": "Successfully rescheduled check for object 'mailserver!ping'."
        }
    ]
}

If you’re sending the API requests programmatically, this allows you to let your JSON library do all the string escaping work for you. Please note that you can’t use variables like service as these are already used for the objects the filter is evaluated on.

Querying objects

All of this doesn’t just work for the /v1/actions endpoints, but also for /v1/objects to query or modify objects. In fact, it works exactly the same, you just have to send the same JSON body as a GET request (or POST request with the X-HTTP-Method-Override: GET header set) to /v1/objects/hosts (or any other type) instead of /v1/actions/reschedule-check and instead of rescheduling the next check, you get the objects with all their attributes as a response.

For the objects API endpoints, there’s a convenience feature that also allows specifying specifying a single object name directly inside the path of the URL. Apart from that, there is no functional difference, so /v1/objects/hosts/fileserver is just a shorthand for /v1/objects/hosts?host=fileserver.

Now you should know everything you know about how to specify objects in Icinga 2 API requests, please refer to the full documentation for all the other details.