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 \
   --with-web-user=www-data \
   --with-web-group=www-data

	Note
	The --with-web... directives have to be set. Otherwise the web logs will not be written correctly. This may also lead to an empty main cronk. Please note that the values of user and group differ across distributions.

 # make install

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 examples in the doc/examples folder.