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 icinga2Code language: JavaScript (javascript)

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/*" ]
}Code language: JavaScript (javascript)

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'Code language: JavaScript (javascript)

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)" }'Code language: JavaScript (javascript)

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.