Icinga 2 API use cases, clients and programmatic examples.

1. www.icinga.org
#icingacamp – San Diego – 10/18/2016
ICINGA 2 – APIFY THEM ALL

2. • Michael Friedrich
• Icinga 2 Developer & Community Lead
• Senior Developer @NETWAYS
• 7+ years #icingalove
• @dnsmichi

3. ICINGA 2 - API

4. • HTTP with RESTful Url Schema
• ApiUser config object
• X.509 and/or Basic Auth

5. ApiUser Object
object ApiUser "root" {
password = "icinga”
permissions = [ "*" ]
}

6. ApiUser Permissions
permissions = [
{
permission = "objects/query/Host"
filter = {{ regex("^Linux", host.vars.os) }}
},
{
permission = "objects/query/Service"
filter = {{ regex("^Linux", host.vars.os) }}
}
]

7. • create, modify and delete objects
• query objects and status
• run actions
• subscribe to events
• manage configuration packages

8. • Status, Objects, Actions and Events
• Simple filter
services?service=localhost!ping6
• Advanced filter
type=Service&filter=service.name==%22ping6%22
(Hint: assign where expressions)

9. • Configuration management
• New standard config API
• Support for Packages and Stages
• No more SSH transport, all HTTP
• Used by the Icinga Director

10. • Event Streams
• Based on types
CheckResult, StateChange, Notification, Acknowledgement*, Comment*,
Downtime*
• Use filters
Example: Receive all check results where the state is not OK.
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST
'https://192.168.33.5:5665/v1/events'
-d '{ "queue": "mine", "types": [ "CheckResult" ], "filter":
"event.check_result.state != 0" }'

11. Demo

12. API CLIENTS

13. Icinga Studio

14. Icinga 2 console
# ICINGA2_API_PASSWORD=icinga icinga2 console --connect
'https://root@localhost:5665/' --eval
'get_host(NodeName).last_check_result.command' | python -m
json.tool
[
"/usr/lib64/nagios/plugins/check_ping",
"-H",
"127.0.0.1",
"-c",
"5000,100%",
"-w",
"3000,80%"
]

15. Icinga 2 Dashing

16. Icinga Director

17. Bitbar for OSX

18. aNag for Android

19. Programmatic examples: Event Streams

20. Paw for MacOS

21. ICINGA 2 API – COMMUNITY

22. • Libraries
• python-icinga2api: https://pypi.python.org/pypi/python-
icinga2api
• go-icinga2: https://github.com/xert/go-icinga2
• Management
• Foreman Smart Proxy:
https://github.com/theforeman/smart_proxy_monitoring
• Terraform Provider: https://github.com/lrsmith/terraform-
provider-icinga2

23. • Status
• Grafana Plugin: https://github.com/tegud/grafana-icinga2api
• aNag on Android:
https://damien.degois.info/android/aNag/summary
• BitBar OSX:
https://getbitbar.com/plugins/Dev/Icinga2/icinga2.24m.py
• Event Streams
• Logstash input: https://github.com/bobapple/logstash-input-
icinga_eventstream
• Flapjack events: https://github.com/sol1/flapjack-icinga2

24. • Actions
• Lita handler: https://github.com/tuxmea/lita-icinga2
• Sakuli Forwarder:
http://sakuli.readthedocs.io/en/dev/forwarder-icinga2api/
• mqttwarn: https://github.com/jpmens/mqttwarn#icinga2
• OpsGenie actions:
https://www.opsgenie.com/docs/integrations/icinga2-
integration

25. ICINGA 2 API – WHAT’S NEXT?

26. • More libraries
• Elastic Beats integration
• Puppet/Ansible/Chef/Salt Hook
• Nagstamon, NagVis, …
• Send a PR:
https://github.com/Icinga/icinga2-api-
examples

27. CONCLUSION

28. • Download Icinga 2
• Play with the Vagrant boxes
• Check the API docs
• Share your ideas & API clients

29. THANK YOU!
www.icinga.org
dev.icinga.org
git.icinga.org
@icinga
/icinga
+icinga