icinga2: How to enable Api in icinga?

Posted by

$ icinga2 api setup
$ systemctl restart icinga2
$ icinga2 feature enable api

/etc/icinga2/zones.conf

object Endpoint "self" {
    host = "172.31.11.106" // can be omitted if it's the same system
}

/etc/icinga2/conf.d/api-users.conf
object ApiUser "api" {
    password = "rajesh123"
    permissions = [ "*" ]
    // Ensure the client_cn is matching if you're using certificate-based authentication
}

/etc/icinga2/zones.conf
object Zone "master" {
    endpoints = [ "self" ]
}

$ systemctl restart icinga2

In this example:

  • api-user is the username for the API.
  • secret is the password (you should choose a strong, secure password).
  • permissions defines what the user is allowed to do:
    • status/query allows the user to query Icinga2 status.
    • actions/* permits the user to perform all actions like sending custom notifications, rescheduling checks, etc.
    • objects/modify/* allows the user to modify objects.
    • objects/query/* permits querying all object types.
Here’s how you can define an API user with specific permissions:

vi /etc/icinga2/features-enabled/api.conf

Add the following configuration block to the file:


object ApiUser "api-user" {
  password = "secret"
  permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
}

Available permissions for specific URL endpoints:

The permissions field in the ApiUser object specifies what the API user is allowed to do. You can tailor the permissions according to your security and operational requirements. Here are some common permissions:

  • *: Grants full access.
  • status/query: Allows querying Icinga2 status.
  • objects/query/*: Allows reading all object types.
  • objects/query/Hosts: Limits reading to host objects.
  • objects/modify/*: Allows modification of all object types.
  • actions/*: Allows all actions like acknowledging problems or sending notifications.

Available permissions for specific URL endpoints:

PermissionsURL EndpointSupports filtersMax body size in MB
actions/<action>/v1/actionsYes1
config/query/v1/configNo1
config/modify/v1/configNo512
console/v1/consoleNo1
events/<type>/v1/eventsNo1
objects/query/<type>/v1/objectsYes1
objects/create/<type>/v1/objectsNo1
objects/modify/<type>/v1/objectsYes1
objects/delete/<type>/v1/objectsYes1
status/query/v1/statusYes1
templates/<type>/v1/templatesYes1
types/v1/typesYes1
variables/v1/variablesYes1
Test the API
Test the API setup by making a request using curl or any other HTTP client:

curl -k -s -u 'api:rajesh123' -H 'Accept: application/json' 'https://localhost:5665/v1/status'

Query an existing object by sending a POST request with X-HTTP-Method-Override: GET as request header:

curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
 -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: DELETE as request header:

curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
 -H 'X-HTTP-Method-Override: DELETE' -X POST \
 'https://localhost:5665/v1/objects/hosts/example.localdomain'
Query objects with complex filters. For a detailed introduction into filter, please read the following chapter.

curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
 -H 'X-HTTP-Method-Override: GET' -X POST \
 'https://localhost:5665/v1/objects/services' \
 -d '{ "filter": "service.state==2 && match(\"ping*\",service.name)" }'
Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments
0
Would love your thoughts, please comment.x
()
x