singuliere / icinga2-api-examples

Examples for the Icinga 2 API

General

These examples for the Icinga 2 API should help you get started with your own projects.

Please read the API documentation thoroughly before looking into the scripting details.

Support

These examples remain generally unsupported, you should not put them in production without your own review and knowledge.

Discuss your questions on the community channels.

Integrations

If any tool or script is missing, please send a patch/PR :)

Libraries

Name	Language	Description
ruby-icinga2	Ruby	Ruby library
python-icinga2_api	Python	Python library
python-icinga2-api	Python	Python bindings for Icinga 2 interaction
go-icinga2	Golang	Golang functions and type definitions
go-icinga2-api	Golang	Golang implementation used inside the Terraform provider
go-icinga2-client	Golang	Golang implementation for the Rancher integration.
Monitoring::Icinga2::Client::REST	Perl	Perl bindings.

Status

Name	Language	Description
Dashing	Ruby, HTML	Dashboard for Dashing querying the REST API for current host/service/global status
Icinga 2 Slack Bot	Golang	Query host/service details from a Slack channel
InfluxDB Telegraf Input	Golang	Telegraf is an agent written in Go for collecting, processing, aggregating, and writing metrics.
icinga2bot	Python	Errbot plugin to fetch status and event stream information and forward to XMPP, IRC, etc.
IcingaBusyLightAgent	C#	Notification Agent in Systray
BitBar for OSX	Python	macOS tray app for highlighting the host/service status
Icinga 2 Multistatus	-	Chrome Extension
Clippy.js	PHP, JS	Funny demo for presenting alerts in your browser

Manage Objects

Name	Language	Description
Icinga Director	PHP, JS	Icinga 2 configuration interface integrated into Icinga Web 2
Logstash output for Icinga	Ruby	Forward check results and create objects from log events
AWS/EC2	Ruby	Example script for creating and deleting AWS instances in Icinga 2
Foreman Smart Proxy Monitoring	Ruby	Smart Proxy extension for Foreman creating and deleting hosts and services in Icinga 2
Terraform Provider	Golang	Register hosts from Terraform in Icinga 2. Official docs.
Rancher integration	Golang	Registers Rancher resources in Icinga 2 for monitoring.

Event Streams

Name	Language	Description
Elastic icingabeat	Golang	Process events and send to Elasticsearch/Logstash outputs
Request Tracker ticket integration	Golang	Create and update RT tickets
Logstash input event stream	Ruby	Forward events as Logstash input
Flapjack events	Golang	Dumping events into Redis for Flapjack processing
Stackstorm integration	Python	Processing events and fetching status information

Actions

Name	Language	Description
Icinga Web 2	PHP	Trigger actions via command transport
Logstash output for Icinga	Ruby	Forward check results and create objects from log events
OTRS SystemMonitoring	Perl	Acknowledge problems in Icinga 2 from OTRS tickets
mqttwarn	Python	Forward check results from mqttwarn to Icinga 2
Lita handler	Ruby	List, recheck and acknowledge through a #chatops bot called Lita
Sakuli forwarder	Java	Forward check results from tests from Sakuli to Icinga 2
OpsGenie actions	Golang, Java	Integrate Icinga 2 into OpsGenie

REST API Clients

Name	Language	Description
Browser plugins	-	Postman for Chrome, REST Easy for Firefox
Postman	-	App instead of browser plugin
Cocoa Rest Client	-	macOS app
Paw for MacOS	(exported)	Examples here
Icinga Studio	C++	Application for visualizing the status information
icinga2 console	C++	CLI tool for running config expressions against the API

Misc

Several Scripts.

Name	Language	Description
go-icinga2-events	Golang	Connect to the event stream and output state changes
console	-	Examples for using the icinga2 console CLI command
events	-	Examples for event streams
objects	PHP, Python	Examples for fetching status and managing objects

Filter json output with jq

You can test your filter expression online.

Example: how to get output from service

curl -k -u training:icinga 'https://icinga2Server.localdomain:5665/v1/objects/services?filter=match(%22icingaHost1%22,host.name)&attr=last_check_result' |jq '.results[].attrs.last_check_result.output'
"OK - load average per CPU: 0.00, 0.00, 0.00"