icinga2: How to enable Api in icinga?

$ 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:

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)" }'

• Author
• Recent Posts

Follow me

Rajesh Kumar

Mentor for DevOps - DevSecOps - SRE - Cloud - Container & Micorservices at Software AG

Join my following certification courses...
- DevOps Certified Professionals (DCP)
- Site Reliability Engineering Certified Professionals (SRECP)
- Master in DevOps Engineering (MDE)
- DevSecOps Certified Professionals (DSOCP)
URL - https://www.devopsschool.com/certification/

My Linkedin - https://www.linkedin.com/in/rajeshkumarin

Follow me

Latest posts by Rajesh Kumar (see all)

• What is robots ops? - July 10, 2024
• 5 Effective Online Learning Strategies for DevOps Professionals - July 4, 2024
• Complete Guide to Obtaining a Private Pilot License (PPL) - June 30, 2024