Icinga

Installation and use of the Icinga API

  1. Software

    Take your clone from the icinga-api.git to get a fresh branch

     # git clone git://git.icinga.org/icinga-api.git

    or download the software using https://git.icinga.org/index?p=icinga-api.git;a=snapshot;h=refs/heads/master;sf=tgz.

  2. The installation

    Unpack the software and move it to the Icinga source code tree

     # tar xzvf icinga-api-(version).tar.gz
     # mv icinga-api/* /usr/src/icinga-core/module/icinga-api

    Recompile the code (you may have to rerun ./configure again).

     # make all
     # make install
    [Note] Note

    If you don't have Icinga yet please follow the instructions given in the "quickstart-idoutils" documentation.

  3. Configuration

    Configuration is simply done by using an 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_',
     );
  4. 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();
  5. 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
  6. 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.