Prerequisites
You need Icinga Core and IDOUtils or MKLiveStatus installed and running in order to use the API.
![]() |
Note |
---|---|
If you don't have Icinga yet please follow the instructions given in the "quickstart-idoutils" documentation. |
If you are using IDOUtils database as data source, install PHP-PDO.
RHEL/Fedora/CentOS
Make sure you have a repository/packages for PHP 5.2.x - RHEL/CentOS only support 5.1.6 out of the box.
# yum install php-pdo php-mysql|pgsql
Debian/Ubuntu
# apt-get install php5 php5-mysql|pgsql
openSuSE
Please use yast to install the packages php5, php5-pdo, and php5-mysql|php5-pgsql.
Installation and Configuration
![]() |
Note |
---|---|
Icinga API is already included in the package with Core, IDOUtils and docs and also installed during 'make install'. If you already installed this package, there's no need to install Icinga API. It is located by default in /usr/local/icinga/share/icinga-api/ and you can skip this section! |
![]() |
Note |
---|---|
If you just require Icinga API for Icinga-Web, and already installed the Core with IDOUtils, skip this Howto and refer directly to installing Icinga Web. |
Download
Take your clone from the icinga-api.git to get a fresh branch
# git clone git://git.icinga.org/icinga-api.git
or if you just need an update:
# cd icinga-api && git pull origin master
or download the software using https://git.icinga.org/index?p=icinga-api.git;a=snapshot;h=refs/heads/master;sf=tgz.
Installation
Unpack Icinga API run configure and install it.
# tar xzvf icinga-api-(version).tar.gz # ./configure
You can set the prefix where it will be installed, and point Icinga API where your Icinga and IDOUtils config is located and which users are required to run (those settings are directly applied when installing the API through Icinga Core Installation).
# ./configure --datarootdir=/usr/local/icinga/share \ --sysconfdir=/usr/local/icinga/etc \ --with-command-user=icinga-cmd \ --with-command-group=icinga-cmd \ --with-icinga-user=icinga \ --with-icinga-group=icinga
# make install
Configuration
If you are developing you own Addon based on the Icinga API, you need the following associative array.
$idoConfig = array ( 'type' => '<Type of database>', 'host' => '<Database hostname>', 'database' => '<Databasename>', 'user' => '<Username>', 'password' => '<password>', 'persistent' => <true | false>, 'table_prefix' => '<table prefix>', );
Example:
$idoConfig = array ( 'type' => 'mysql', 'host' => 'localhost', 'database' => 'ido', 'user' => 'idouser', 'password' => 'idopassword', 'persistent' => true, 'table_prefix' => 'icinga_', );
Supported Backends
Currently the following backend types are available. More information about that can be found in doc/icinga-api-types.txt.
IDOUtils DB - OK
Livestatus Module - experimental, not for productive usage
Filebased, status.dat - experimental, not for productive usage
Use of the API
Examples can be found in doc/examples
Fetching data
hostnames and corresponding states
Create an instance of class IcingaApi:
$api = IcingaApi::getConnection(IcingaApi::CONNECTION_IDO, $idoConfig);
Create your search:
$apiRes = $api->createSearch() ->setSearchTarget(IcingaApi::TARGET_HOST) ->setResultColumns(array(’HOST_NAME’, ‘HOST_CURRENT_STATE’)) ->fetch();
By using setSearchFilter() you can define filters to narrow down the result set:
$apiRes = $api->createSearch() ->setSearchTarget(IcingaApi::TARGET_HOST) ->setResultColumns(array(’HOST_NAME’, ‘HOST_CURRENT_STATE’)) ->setSearchFilter(HOST_NAME, ‘Switch%’, IcingaApi::MATCH_LIKE) ->fetch();
Processing results
foreach($apiRes as $apiHandle){ echo ‘Host ‘.$apiHandle->HOST_NAME.’ has state ‘.$apiHandle->HOST_CURRENT_STATE.’<br />’; }
Output without filter:
Host localhost has state 0 Host MySql has state 0 Host router-01 has state 0 Host windows100 has state 0 Host Apache_01 has state 0
Output with filter:
Host switch70 has the current state 0 Host switch71 has the current state 0 Host switch72 has the current state 0 Host switch73 has the current state 0 Host switch74 has the current state 0 Host switch75 has the current state 0 Host switch76 has the current state 0 Host switch77 has the current state 0
Complete code without use of filters
<? // Path to icinga api file $apiFile = ‘icinga-api/IcingaApi.php’; // Database connection $idoConfig = array ( 'type' => 'mysql', 'host' => 'localhost', 'database' => 'ido', 'user' => 'idouser', 'password' => 'idopassword', 'persistent' => true, 'table_prefix' => 'icinga_', ); // Include required files require_once($apiFile); // Instance the class $api = IcingaApi::getConnection(IcingaApi::CONNECTION_IDO, $idoConfig); // Create search $apiRes = $api->createSearch() ->setSearchTarget(IcingaApi::TARGET_HOST) ->setResultColumns(array('HOST_NAME', 'HOST_CURRENT_STATE')) ->fetch(); // Create output foreach($apiRes as $apiHandle){ echo 'Host '.$apiHandle->HOST_NAME.' has the current state '.$apiHandle->HOST_CURRENT_STATE.'<br />'; } ?>
Please have a look at the git repository for further information or consult the exmaples in the doc/examples folder.
© 2009-2010 Icinga Development Team, http://www.icinga.org