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

Rajesh Kumar

I’m a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I am working at Cotocus. I blog tech insights at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at I reviewed , and SEO strategies at Wizbrand. 

Please find my social handles as below;

Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at PINTEREST
Rajesh Kumar at QUORA
Rajesh Kumar at WIZBRAND