1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>11.3. No Icinga API to install anymore</title>
<link rel="stylesheet" href="../stylesheets/icinga-docs.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<meta name="keywords" content="Supervision, Icinga, Nagios, Linux">
<link rel="home" href="index.html" title="Icinga Version 1.14 Documentation">
<link rel="up" href="ch11.html" title="Chapter 11. Development">
<link rel="prev" href="epnplugins.html" title="11.2. Developing Plugins For Use With Embedded Perl">
<link rel="next" href="icinga-web-api.html" title="11.4. The Icinga Web REST API">
<script src="../js/jquery-min.js" type="text/javascript"></script><script src="../js/icinga-docs.js" type="text/javascript"></script>
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<CENTER><IMG src="../images/logofullsize.png" border="0" alt="Icinga" title="Icinga"></CENTER>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">11.3. No Icinga API to install anymore</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="epnplugins.html">Prev</a> </td>
<th width="60%" align="center">Chapter 11. Development</th>
<td width="20%" align="right"> <a accesskey="n" href="icinga-web-api.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="section" title="11.3. No Icinga API to install anymore">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="icinga-api"></a>11.3. No Icinga API to install anymore</h2></div></div></div>
<div class="toc"><dl><dt><span class="section">11.3.1. <a href="icinga-api.html#idm140381622160288">Installation and use of the Icinga API</a></span></dt></dl></div>
<div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top">
<p>In the days leading up to the v1.5 release, we bid our Icinga API goodbye and ushered in a new API and Web concept.</p>
<p>You may ask yourself, what was this API anyway? Indeed, if you weren’t developing or adapting extensions for the new web
interface, you wouldn’t have had much contact with this important project component. When Icinga was conceived, one of the main
missions was to facilitate the development of addons and plugins. The API provided a set of commonly used request operations, removing
the need to write sql-queries and generally a lot of excess code.</p>
<p>All was well until we decided to offer some extra database flexibility. When we added support for Oracle and
PostgreSQL on top of MySQL, we also gave our Icinga API team some extra work. With each change, bug fix or new feature,
Marius, Michael L and Jannis had to edit the queries for each database back-end separately. This process was not only complicated and
error-prone, but also a sign that we needed a more flexible architecture.</p>
<p>As of Icinga 1.5, the external Icinga API was replaced by an internal database layer Doctrine, and merged into Icinga Web.
Much like before, queries will run through this layer between the database (IDOUtils) and the web interface. However, with
Doctrine we can use several database back-ends and querying the database is now much easier. In contrast to SQL, its object relational
mapper (ORM) uses Doctrine Query Language, so we now have the flexibility minus the code duplication.</p>
<p><span class="inlinemediaobject"><img src="../images/Architecture_1.5_800px.png"></span></p>
<p>That being said, queries from the old API still exist, thanks to the ‘legacy layer’ which will transform old API queries into this
new ORM type. In this way, we maintain compatibility with addons designed for older Icinga versions. The Rest API is also still
there as part of Icinga Web, extending on our Doctrine layer with HTTP for addons that require only certain bits of monitoring
info.</p>
<p>With the departure of a standalone API, the average Icinga user will barely notice a change, apart from the fact that the
configuration has now been moved to the <code class="filename">databases.xml</code>. Best of all, every module developer can now easily access
the Icinga database without much code overhead– so addon developers get hacking and let us know how you go!</p>
</td></tr>
</table></div>
<div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top">
<p>The following is deprecated and only kept for reference</p>
</td></tr>
</table></div>
<div class="section" title="11.3.1. Installation and use of the Icinga API">
<div class="titlepage"><div><div><h3 class="title">
<a name="idm140381622160288"></a>11.3.1. Installation and use of the Icinga API</h3></div></div></div>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<p><span class="bold"><strong>Prerequisites</strong></span></p>
<p>You need Icinga Core and IDOUtils or <a class="link" href="http://mathias-kettner.de/checkmk_livestatus.html" target="_top">MKLiveStatus</a> installed and running in order to use the
API.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>If you don't have Icinga yet please follow the instructions given in the "<a class="link" href="quickstart-idoutils.html" title="2.6. Icinga with IDOUtils Quickstart">quickstart-idoutils</a>" documentation.</p>
</td></tr>
</table></div>
<p>If you are using IDOUtils database as data source, install PHP-PDO.</p>
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
<li class="listitem">
<p><span class="bold"><strong>RHEL/Fedora/CentOS</strong></span></p>
<p>Make sure you have a repository/packages for PHP 5.2.x - RHEL/CentOS only support 5.1.6 out of the box.</p>
<pre class="programlisting"> # yum install php-pdo php-mysql|pgsql</pre>
</li>
<li class="listitem">
<p><span class="bold"><strong>Debian/Ubuntu</strong></span></p>
<pre class="programlisting"> # apt-get install php5 php5-mysql|pgsql</pre>
</li>
<li class="listitem">
<p><span class="bold"><strong>openSuSE</strong></span></p>
<p>Please use yast to install the packages php5, php5-pdo, and php5-mysql|php5-pgsql.</p>
</li>
</ul></div>
</li>
<li class="listitem">
<p><span class="bold"><strong>Installation and Configuration</strong></span></p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>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!</p>
</td></tr>
</table></div>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>If you just require Icinga API for Icinga-Web, and already installed the Core with IDOUtils, skip this Howto and
refer directly to <a class="link" href="icinga-web-scratch.html" title="6.5. Installation of the Icinga Web Frontend">installing Icinga Web</a>.</p>
</td></tr>
</table></div>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
<p><span class="bold"><strong>Download</strong></span></p>
<p>Take your clone from the icinga-api.git to get a fresh branch</p>
<pre class="programlisting"> # git clone git://git.icinga.org/icinga-api.git</pre>
<p>or if you just need an update:</p>
<pre class="programlisting"> # cd icinga-api && git pull origin master</pre>
<p>or download the software using <a class="link" href="https://git.icinga.org/index?p=icinga-api.git;a=snapshot;h=refs/heads/master;sf=tgz" target="_top">https://git.icinga.org/index?p=icinga-api.git;a=snapshot;h=refs/heads/master;sf=tgz</a>.</p>
</li>
<li class="listitem">
<p><span class="bold"><strong>Installation</strong></span></p>
<p>Unpack Icinga API run configure and install it.</p>
<pre class="programlisting"> # tar xzvf icinga-api-(version).tar.gz
# ./configure</pre>
<p>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).</p>
<pre class="programlisting"> # ./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</pre>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>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.</p>
</td></tr>
</table></div>
<pre class="programlisting"> # make install</pre>
</li>
</ol></div>
</li>
<li class="listitem">
<p><span class="bold"><strong>Configuration</strong></span></p>
<p>If you are developing you own Addon based on the Icinga API, you need the following associative array. </p>
<pre class="programlisting"> $idoConfig = array (
'type' => '<Type of database>',
'host' => '<Database hostname>',
'database' => '<Databasename>',
'user' => '<Username>',
'password' => '<password>',
'persistent' => <true | false>,
'table_prefix' => '<table prefix>',
);</pre>
<p> Example:</p>
<pre class="programlisting"> $idoConfig = array (
'type' => 'mysql',
'host' => 'localhost',
'database' => 'ido',
'user' => 'idouser',
'password' => 'idopassword',
'persistent' => true,
'table_prefix' => 'icinga_',
);</pre>
</li>
<li class="listitem">
<p><span class="bold"><strong>Supported Backends</strong></span></p>
<p>Currently the following backend types are available. More information about that can be found in doc/icinga-api-types.txt.
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="circle">
<li class="listitem">
<p>IDOUtils DB - OK</p>
</li>
<li class="listitem">
<p>Livestatus Module - experimental, not for productive usage</p>
</li>
<li class="listitem">
<p>Filebased, status.dat - experimental, not for productive usage</p>
</li>
</ul></div>
</li>
<li class="listitem">
<p><span class="bold"><strong>Use of the API</strong></span></p>
<p>Examples can be found in doc/examples</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
<p><span class="bold"><strong>Fetching data</strong></span></p>
<p>hostnames and corresponding states</p>
<p>Create an instance of class IcingaApi:</p>
<pre class="programlisting"> $api = IcingaApi::getConnection(IcingaApi::CONNECTION_IDO, $idoConfig);</pre>
<p>Create your
search:</p>
<pre class="programlisting"> $apiRes = $api->createSearch()
->setSearchTarget(IcingaApi::TARGET_HOST)
->setResultColumns(array(’HOST_NAME’, ‘HOST_CURRENT_STATE’))
->fetch();</pre>
<p>By using setSearchFilter() you can define filters to narrow down the result set:</p>
<pre class="programlisting"> $apiRes = $api->createSearch()
->setSearchTarget(IcingaApi::TARGET_HOST)
->setResultColumns(array(’HOST_NAME’, ‘HOST_CURRENT_STATE’))
->setSearchFilter(HOST_NAME, ‘Switch%’, IcingaApi::MATCH_LIKE)
->fetch();</pre>
</li>
<li class="listitem">
<p><span class="bold"><strong>Processing results</strong></span></p>
<pre class="programlisting"> foreach($apiRes as $apiHandle){
echo ‘Host ‘.$apiHandle->HOST_NAME.’ has state ‘.$apiHandle->HOST_CURRENT_STATE.’<br />’;
}</pre>
<p>Output without filter:</p>
<pre class="programlisting"> 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</pre>
<p>Output with filter:</p>
<pre class="programlisting"> 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</pre>
</li>
<li class="listitem">
<p><span class="bold"><strong>Complete code without use of filters</strong></span></p>
<pre class="programlisting"> <?
// 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 />';
}
?></pre>
<p>Please have a look at the <a class="link" href="http://git.icinga.org/" target="_top">git repository</a> for further information or
consult the examples in the doc/examples folder.</p>
</li>
</ol></div>
</li>
</ul></div>
<a class="indexterm" name="idm140381622109392"></a>
<a class="indexterm" name="idm140381622108080"></a>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="epnplugins.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="ch11.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="icinga-web-api.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">11.2. Developing Plugins For Use With Embedded Perl </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 11.4. The Icinga Web REST API</td>
</tr>
</table>
</div>
<P class="copyright">© 1999-2009 Ethan Galstad, 2009-2017 Icinga Development Team, https://www.icinga.com</P>
</body>
</html>
|
