Current File : //proc/self/root/proc/self/root/usr/share/nagios/html/docs/qh.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>Nagios: Query Handler</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">Nagios
 <span id="projectnumber">4.4.3</span>
</div>
<div id="projectbrief">Dev docs for Nagios core and neb-module hackers</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Query Handler </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#purpose">Purpose</a></li>
<li class="level1"><a href="#caveats">Caveats</a></li>
<li class="level1"><a href="#qh_registering">Registering a query handler</a></li>
<li class="level1"><a href="#syntax">Syntax</a><ul><li class="level2"><a href="#qh_examples">Example queries</a></li>
</ul>
</li>
<li class="level1"><a href="#icqh">In-core query handlers</a><ul><li class="level2"><a href="#help">The help service</a></li>
<li class="level2"><a href="#echo">The echo service</a></li>
<li class="level2"><a href="#nerd">Nagios Event Radio Dispatcher</a></li>
<li class="level2"><a href="#wproc">Worker process manager</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>A brief intro to the Nagios query handler system</p>
<h1><a class="anchor" id="purpose"></a>
Purpose</h1>
<p>The purpose of the query handler is to provide Nagios Core and its eventbroker modules with the ability to communicate directly with the outside world through a well-defined API, as well as allowing external apps a way to help out with various Nagios tasks.</p>
<h1><a class="anchor" id="caveats"></a>
Caveats</h1>
<p>The query handlers run in the main thread. Nagios doesn't provide any parallelism here and main Nagios will be blocked while a query is running. As such, it's a very good idea to make ones queryhandlers complete in as little time as possible.</p>
<h1><a class="anchor" id="qh_registering"></a>
Registering a query handler</h1>
<p>This is really for module authors only.</p>
<p>To register a query handler, you <em>must</em> have a function like the one below: the following arguments: </p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> lala_query_handler(<span class="keywordtype">int</span> sd, <span class="keywordtype">char</span> *query, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> query_len)</div>
</div><!-- fragment --><p>The parameters don't have to have those exact names, and the function certainly doesn't have to be called "lala_query_handler()". We're not quite that childish (well, we are, but we like to pretend we're not). They will suffice for this explanation, however. </p>
<ul>
<li>sd - The socket you should respond to. </li>
<li>query - The query, minus the address and the magic byte. </li>
<li>query_len - Length of the query, in bytes.</li>
</ul>
<p>The call to register it with Nagios so you get all queries directed to the 'lala' address is then: </p>
<div class="fragment"><div class="line">qh_register_handler(<span class="stringliteral">"lala"</span>, <span class="stringliteral">"The LaLa query handler"</span>, 0,</div>
<div class="line">lala_query_handler);</div>
</div><!-- fragment --><p>The second argument is a description, which will be printed when someone sends a help request. </p>
<dl class="section note"><dt>Note</dt><dd>It's a good idea to handle queries such as "help" and take them to mean "print me some text telling me at least the basics
of how to use this query handler".</dd></dl>
<h1><a class="anchor" id="syntax"></a>
Syntax</h1>
<p>The query language is remarkably simple (although each handler may implement its own parsers that handle and do pretty much whatever they want). The first byte is magic. If it's an at-sign, we expect the queryer to persist and issue more queries after the first one. If it's a hash-sign, the query handler will disconnect the client as soon as it regains control from whatever handler registered for the particular address. Each particular handler has some control over this behaviour though, and can use specific return codes to denote that it will take over the socket from the query handler. If no at-sign and no hash-sign is present at the first byte, the -1'th byte will be considered an at-sign, and the connection will consequently be considered persistent.</p>
<h2><a class="anchor" id="qh_examples"></a>
Example queries</h2>
<p>Subscribe for real-time push-events for servicechecks from the NERD radio: </p>
<pre class="fragment">@nerd subscribe servicechecks\0
</pre><p>One-shot query the core query handler for current load-control options: </p>
<pre class="fragment">#core loadctl\0
</pre><p>Get Nagios to say hi to you: </p>
<pre class="fragment">#echo Greetings, Exalted One
</pre><p>Ask the help handler to list registered handlers: </p>
<pre class="fragment">#help list
</pre><h1><a class="anchor" id="icqh"></a>
In-core query handlers</h1>
<p>There are a few in-core query handlers.</p>
<h2><a class="anchor" id="help"></a>
The help service</h2>
<p>The help query handler is quite possibly the most important one. It can be used to list registered handlers (with short descriptions), and can be used to get help about registered handlers (assuming they've implemented it, that is). It should be noted that the ones that <em>have</em> implemented it can also be queried directly for their help output, like so: </p>
<pre class="fragment">@core help
</pre><h2><a class="anchor" id="echo"></a>
The echo service</h2>
<p>As I'm sure you've already guessed, the echo service just prints the inbound data right back at you. While that's not exactly nobel prize winning material, it's actually pretty nifty to figure out how fast Nagios can parse its inbound data, which in turn shows how fast it can handle its inbound checkresults, which puts an upper cap on how many checks Nagios can handle at any given time (although short bursts that exceed that limit are ok and will be handled just fine).</p>
<p>It can be addressed as such: </p>
<pre class="fragment">@echo foo bar baz said the bunny\0
</pre><h2><a class="anchor" id="nerd"></a>
Nagios Event Radio Dispatcher</h2>
<p>The nerd radio is subscribed in fuller detail at </p>
<dl class="section see"><dt>See Also</dt><dd>nerd, but its worth knowing that it's a core part of Nagios 4 and that it will always be available.</dd></dl>
<h2><a class="anchor" id="wproc"></a>
Worker process manager</h2>
<p>The worker process manager lets you register workers that can help out with running checks, send notifications, run eventhandlers or whatever.</p>
<p>In order to register a worker that only handles checks supposed to be run by the plugins check_foo and check_bar (irrespective of where in the paths they are), you'd do something like this: </p>
<pre class="fragment">@wproc register name=foobar;plugin=check_foo;plugin=check_bar\0
</pre> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.5
</small></address>
</body>
</html>
Mini Shell