jablonka.czprosek.czf

weathermap

 Subversion Repositories:
[/] [docs/] [pages/] [targets.html] - Blame information for rev 98

 

Line No. Rev Author Line
11simandl<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 
4<html lang="en" xml:lang="en">
5<head>
6 <link rel="stylesheet" type="text/css" media="screen" href="weathermap.css" />
7 <meta name="generator" content=
8 "HTML Tidy for Mac OS X (vers 12 April 2006), see www.w3.org" />
9 
10 <title>PHP Weathermap
1185simandlv0.97a
12 - Targets Reference</title>
131simandl<style type="text/css" media="print">
14/*<![CDATA[*/
15body { font-size: 12pt; }
16a { color: black; text-decoration: underline; font-weight: normal;}
17/*]]>*/
18</style>
19 
20</head>
21 
22<body>
23 <div id="frame">
24 
25 
26<div class="navcontainer">
27 <ul id="navlist">
28 <li><a href="main.html">Main Page</a></li>
29 <li><a href="main.html#installation">Installation</a></li>
30 <li><a href="main.html#basics">Basics</a></li>
31 <li><a href="faq.html">FAQ and Tips</a></li>
32 <li><a href="main.html#example">Sample Map</a></li>
33 <li><a href="cli-reference.html">CLI Reference</a></li>
34 <li><a href="config-reference.html">Config Reference</a></li>
35 <li><a href="advanced.html">Advanced Topics</a></li>
36 <li><a href="editor.html">Editor</a></li>
37 <li><a href="cacti-plugin.html">Cacti Plugin</a></li>
38 <li><a href="http://www.network-weathermap.com/">Site</a></li>
39 </ul>
40</div>
41 
42<div id="header">
43 <h1>PHP Weathermap
4485simandlv0.97a
451simandl</h1>
4685simandl <h4>Copyright &copy; 2005-2010 Howard Jones, <tt><a
471simandlhref="mailto:howie@thingy.com">howie@thingy.com</a></tt>. (<a
48href="http://www.network-weathermap.com/">Website</a>)</h4>
49</div>
50 
51 
52 <h2><a name="targets">Specifying <a href="config-reference.html#LINK_TARGET">TARGET</a> lines</a></h2>
53 
5485simandl<p>The actual data-reading part of Weathermap is handled by Data Source Plugins since version 0.9. These allow users or third-parties to easily add new data sources into Weathermap without altering the core code. </p>
55<p>There are a number of plugins supplied as standard, which will be described here. Each one uses a different format of <a href="config-reference.html#LINK_TARGET">TARGET</a> string, which contains the parameters the plugin needs to find your data. <em>All</em> plugins return an 'in' and 'out' value, and some may set other variables that can be accessed by <a href="advanced.html#tokens">Special Tokens</a> in strings. For situations where there is only really one output, the 'out' value may just be the same as the 'in'. </p>
561simandl 
5785simandl<p>Here are the details of the standard data source plugins:
58<ul>
59<li><a href="#static">Static value</a></li>
60<li><a href="#rrd">RRDtool files</a> (Cacti, Cricket, "new-style" MRTG, etc)</li>
61<li><a href="#tabs">Tab-separated text files</a></li>
62<li><a href="#mrtg">MRTG-generated HTML files</a></li>
63<li><a href="#cactihost">Cacti host status</a></li>
64<li><a href="#cactithold">Cacti threshold/monitor status</a></li>
65<li><a href="#cactidsstats">Cacti DSStats data collection plugin</a></li>
66<li><a href="#script">MRTG-style external script</a></li>
67<li><a href="#snmp">SNMP OID</a></li>
68<li><a href="#fping">fping</a></li>
69<li><a href="#time">Time</a></li>
70</ul>
71 </p>
721simandl 
73<hr />
74 
7585simandl 
76 
77 
78 
79 
80 
81 
821simandl<h3><a name="static"></a>Static value</h3>
83 
8485simandl<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> static:<em>invalue</em>:<em>outvalue</em></div>
85<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> static:<em>value</em></div>
861simandl 
8785simandl<p>The simplest of all the plugins, static allows you to just set a value in the config file itself. Sometimes this is useful for testing, or simple maps of things like OSPF metrics. If only a single value is specified, it is used for <em>both</em> input and output, just like the <a href="config-reference.html#LINK_BANDWIDTH">BANDWIDTH</a> parameter. </p>
881simandl 
8985simandl<p>The values in the target string can use the same K,M,G,T suffixes as <a href="config-reference.html#LINK_BANDWIDTH">BANDWIDTH.</a> </p>
901simandl 
9185simandl<hr />
92 
93 
94 
95 
96 
97 
98 
99 
1001simandl<h3><a name="rrd"></a>RRDtool files</h3>
101 
10285simandl<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> <em>rrdfile.rrd</em>:<em>in_ds</em>:<em>out_ds</em></div>
103<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> gauge:<em>rrdfile.rrd</em>:<em>in_ds</em>:<em>out_ds</em></div>
104<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> rrd:<em>rrdfile.rrd</em>:<em>in_ds</em>:<em>out_ds</em></div>
105<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> scale:<em>factor</em>:<em>rrdfile.rrd</em>:<em>in_ds</em>:<em>out_ds</em></div>
1061simandl 
10785simandl<p>This is the 'core' plugin for Weathermap. It reads data from rrd files, created using <a href="http://www.rrdtool.org/">Tobi Oetiker's
108RRDtool</a>, by tools like Cacti, MRTG, Cricket, NRG and so on. </p>
109<p>First of all, Weathermap needs to be able to find your rrdtool executable. If you are using the Cacti plugin, then this
110information is taken automatically from Cacti. If you are using the command-line tool, you will need to edit <tt>weathermap</tt>
111around line 29 to point to your rrdtool executable. </p>
112<h4><a href="config-reference.html#LINK_TARGET">TARGET</a> formats</h4>
1131simandl<p>If you only specify a filename, and no DS-names, the default DS names for RRD files are 'traffic_in' and 'traffic_out', which works with
11485simandl the majority of Cacti RRD files (those produced by the Interface Traffic template). For MRTG-produced RRD files, the names are
115 'DS0' and 'DS1'. For Cricket standard-interface RRD files, it would be 'ds0' and 'ds1'.
1161simandl </p><p>You can also specify '-' for either DS name, which tells Weathermap to ignore
117 this rrd file for the purposes of the input or output value.
11885simandl This is mainly useful in combination with the aggregation feature, where you can take the input data from one rrd file, and the output data from another. </p>
119 <p>With no prefix, or with just '<b>rrd:</b>' as a prefix, the data read from the rrd file is assumed to be a standard SNMP
120 interface counter, which is a byte-rate. It automatically multiplies these by 8 to get a bit-rate for the map.
121 With the '<b>gauge:</b>' prefix, this multiplication doesn't happen, which is useful for non-bandwidth values,
122 like SNR or session-counts. Finally, you can use the '<b>scale:</b>' prefix to multiply by any factor -
123 suppose you have a value in seconds, and you want to show it in milliseconds for example. Of course, you can also divide using this,
124 by using a scale factor that is less than 1 - multiplying by 1/x is the same as dividing by x. Since 0.95, you can also use negative scale factors - useful to turn dB SNR into something weathermap can deal with. </p>
1251simandl 
12685simandl<h4>rrdtool adjustments</h4>
127<p>By default, the plugin will read the last 800 seconds of data, and find the most recent within that to use. You might need to make it read back further, if you are updating your rrd files slowly. You can do this with the <a href="config-reference.html#GLOBAL_SET">SET</a> command, by adding <a href="config-reference.html#GLOBAL_SET">'SET</a> rrd_period 3000' (any value in seconds) at the top of your map config file, before any <a href="config-reference.html#NODE_NODE">NODE</a> or <a href="config-reference.html#LINK_LINK">LINK</a> lines. </p>
128<p>Similarly, you can change the time that the plugin looks for data at from the present to the past, by using <a href="config-reference.html#GLOBAL_SET">'SET</a> rrd_start -1d' in the top section of the config file. The full range of time-specification strings is at the bottom of the <a href="http://oss.oetiker.ch/rrdtool/doc/rrdfetch.en.html">rrdfetch manual page</a>. </p>
129<p>If you are using a tool other than Cacti, then the default DS names of traffic_in and traffic_out are probably wrong. You can change the defaults for the whole config file by adding two <a href="config-reference.html#GLOBAL_SET">SET</a> lines to the top of the map config file. For example, <a href="config-reference.html#GLOBAL_SET">'SET</a> rrd_default_in_ds DS0' and <a href="config-reference.html#GLOBAL_SET">'SET</a> rrd_default_in_ds DS1' will
130make the default DS names DS0 and DS1 respecively so MRTG users don't need to specify the DS names in every <a href="config-reference.html#LINK_TARGET">TARGET</a> line. </p>
131<p>For any other special rrdtool 'tweaks', you can <a href="config-reference.html#GLOBAL_SET">SET</a> rrd_options to a string which is added directly to the rrdtool command-line. This should allow for any changes that I haven't expected! </p>
132<p>Finally, if the <a href="config-reference.html#LINK_TARGET">TARGET</a> filename doesn't begin with a / it is usually assumed to be a relative path from the weathermap directory. If you <a href="config-reference.html#GLOBAL_SET">SET</a> rrd_default_path to some other path in the global (top) section of the map config file, you can
133change that assumption so that the DS plugin looks somewhere else. </p>
1341simandl 
13585simandl<h4>Cacti-specific additions</h4>
136 
137<p>If the plugin detects that it is running within the Cacti poller process, it defines a couple of useful global Hint Variables for Cacti users - {map:cacti_path_rra} contains the path to the rra/ directory in your Cacti installation, with no trailing slash, and {map:cacti_url} is
138the URL to the front page of your Cacti installation, as known to the Plugin Architecture. These can be used in the <a href="config-reference.html#LINK_TARGET">TARGET,</a> <a href="config-reference.html#LINK_INFOURL">INFOURL</a> and <a href="config-reference.html#LINK_OVERLIBGRAPH">OVERLIBGRAPH</a> commands in particular, to reduce a lot of duplication. </p>
139 
140<h4><a name="rrdpollerextras">Cacti poller_output support</a> (aka Boost support)</h4>
141 
142<p>If you are using Cacti as your data collector, and running Weathermap from Cacti's poller, then there is another special feature, called poller_output. Weathermap can intercept data as it is collected by Cacti, and therefore avoid
143running lots of external rrdtool processes to collect the data it needs to display your map. This is <em>especially</em> useful if you are using TheWitness' Boost plugin, as the data isn't written to the rrd files
144until some time after it is collected. Even without Boost, it should provide a performance improvement, particularly with large installations of Weathermap. </p>
145<p>To use this feature, a map-global variable needs to be set. Near the top of your map config file, add <a href="config-reference.html#GLOBAL_SET">'SET</a> rrd_use_poller_output 1'. The setting will take a few poller cycles to take effect: during the first one, the
146appropriate cacti data sources are identified based on the rrd filenames, on the second cycle values will be collected, and on the third we'll have two values, so any COUNTER datasources will begin to work properly. If the poller_output feature
147fails to collect data, then the regular rrdtool-running method will be attempted too. </p>
148 
149<p>Because in poller_output mode, Weathermap is pulling data directly from the Cacti database, it can also collect some other information that you might find useful in your map. It takes all the data stored in the host_snmp_cache table for the
150specified datasource, and dumps that into Hint Variables. This table contains all the columns that you see when you are picking which datasource to graph in Cacti, so for
151normal interface traffic, it contains things like the interface speed, operational status, interface description (your 'comment' name, usually) and so on. These are stored in Hint Variables called 'cacti_<em>cache variable</em>' - e.g. cacti_ifSpeed, or cacti_ifIP. It also sets
152cacti_host_id to be the internal host_id from Cacti for the host containing this data source, and the cacti_graph_id to be the local_graph_id of a graph that uses this DS in Cacti. You can then use those to automatically add correct <a href="config-reference.html#LINK_OVERLIBGRAPH">OVERLIBGRAPH</a> and <a href="config-reference.html#LINK_INFOURL">INFOURL</a> lines:
153<div class="example">
154<pre>
155<a href="config-reference.html#GLOBAL_SET">SET</a> rrd_use_poller_output 1
156 
157<a href="config-reference.html#LINK_LINK">LINK</a> DEFAULT
158 <a href="config-reference.html#GLOBAL_SET">SET</a> cacti_use_ifspeed 1
159 <a href="config-reference.html#LINK_INFOURL">INFOURL</a> {map:cacti_url}/graph.php?local_graph_id={link:this:cacti_graph_id}
160 <a href="config-reference.html#LINK_OVERLIBGRAPH">OVERLIBGRAPH</a> {map:cacti_url}/graph_image.php?local_graph_id={link:this:cacti_graph_id}&amp;rra_id=0&amp;graph_nolegend=true
161 
162<a href="config-reference.html#LINK_LINK">LINK</a> uplink1
163 <a href="config-reference.html#LINK_NODES">NODES</a> a b
164 <a href="config-reference.html#LINK_TARGET">TARGET</a> {map:cacti_path_rra}/router1_345_traffic_in.rrd
165 
166<a href="config-reference.html#LINK_LINK">LINK</a> uplink2
167 <a href="config-reference.html#LINK_NODES">NODES</a> a c
168 <a href="config-reference.html#LINK_TARGET">TARGET</a> {map:cacti_path_rra}/router1_377_traffic_in.rrd
169</pre>
170<p>In this example, all each link needs to have defined is the <a href="config-reference.html#LINK_TARGET">TARGET</a> rrdfile, and which nodes it joins. The rest is supplied by this plugin. </p>
171</div>
172 
173<p>As a final feature, if you add <a href="config-reference.html#GLOBAL_SET">'SET</a> cacti_use_ifspeed 1' to either the link or node, or any item it inherits settings from (e.g. DEFAULT) then Weathermap will take the value of ifSpeed (or ifHighSpeed for 4G+ links) and use it
174in place of the value defined in the map config file - this allows you to do some basic dynamic configuration of Weathermap based on Cacti, which in turn should pick
175up changes from the network device. </p>
176 
177<p><strong>Note</strong> that since the rrdtool program is not being run in this mode, you <em>can't</em> use the "time-shifting" features described above - those rely on using <em>real</em> rrdtool files. If you are using poller_output
178to allow Weathermap to work alongside Boost, then there is no workaround - the data isn't in the .rrd files until Boost's own update process puts it there sometime later. </p>
179 
180<h4>RRDtool Aggregation</h4>
181<p>XXX THIS NEEDS TO BE WRITTEN! </p>
182 
183<hr />
184 
185 
186 
187 
188 
189 
190 
191 
192 
193 
1941simandl<h3><a name="tabs"></a>Tab-separated text</h3>
19585simandl<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> <em>textfile</em></div>
1961simandl 
197 <p>For tab-delimited data files, the format is plain-text, with three tab-seperated columns.
198 The first one is a linkname, and the second and third are traffic-in and traffic-out, respectively.
199 The linkname should match the name in the configuration file. This allows you to create one text file
200 for the entire map from some outside source. Traffic in &amp; out values can use the same "K,M,G,T" abbreviated forms
201 as the <a href="config-reference.html#LINK_BANDWIDTH">BANDWIDTH</a> configuration command. The file should have an extension of .txt or .tsv to be
20285simandl recognised as a tab-delimited file by Weathermap. </p>
2031simandl 
20485simandl<div class="example">
205<h5>A suitable tab-delimited data file</h5>
206<pre>link1 3M 4M
207link2 66K 1.8M
208link3 34.6K 113</pre>
209</div>
2101simandl 
21185simandl<hr />
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
2231simandl<h3><a name="mrtg"></a>MRTG .html file</h3>
22485simandl<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> <em>htmlfile</em></div>
2251simandl 
226<p>This plugin reads data from special comments in the HTML files generated by MRTG. This is intended mainly for people using the 'old-style' MRTG .log files. If you are using MRTG with an RRDtool backend, then it's probably better to use the RRDtool plugin. </p>
22785simandl<p>The file should have an extension of .html or .htm to be recognised as an MRTG file by Weathermap. </p>
228<p>Since 0.95, there are a few hint variables that will adjust the behaviour of this datasaource:
229<ul>
230<li><b><a href="config-reference.html#GLOBAL_SET">SET</a> mrtg_swap 1</b> - (per-link/node) will swap the in and out values over</li>
231<li><b><a href="config-reference.html#GLOBAL_SET">SET</a> mrtg_negate 1</b> - (per-link/node) will make negate the value from the MRTG file. Weathermap doesn't deal well with negative values yet, so this is sometimes useful.</li>
232<li><b><a href="config-reference.html#GLOBAL_SET">SET</a> mrtg_period d</b> - (per-link/node) allows you to choose between daily, monthly, weekly, and yearly values - use 'd','m','w','y' - default is 'd'</li>
233<li><b><a href="config-reference.html#GLOBAL_SET">SET</a> mrtg_value av</b> - (per-link/node) allows you to choose between average, minimum, maximum and current values - use 'av','min','max','cu' - default is 'cu'</li>
234</ul>
235 </p>
2361simandl 
23785simandl<hr />
2381simandl<h3><a name="cactihost"></a>Cacti host status</h3>
23985simandl<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> cactihost:<em>hostid</em></div>
2401simandl 
24185simandl<p>This plugin reads the current status of a host from your Cacti database. The hostid is visible in Cacti URLs when you click on links in the Devices page. The return values for this plugin are numeric codes. It also sets a Hint Variable called <em>state</em> to a string, that can be nicer to use in an <a href="config-reference.html#NODE_ICON">ICON</a> filename, for example - possible values are 'up','down','disabled', and 'recovering'. </p>
2421simandl<table>
243<thead><tr><th>Code</th><th><tt>state</tt> value</th></tr></thead>
244<tbody>
245<tr><td>0</td><td>disabled</td></tr>
246<tr><td>1</td><td>down</td></tr>
247<tr><td>2</td><td>recovering</td></tr>
248<tr><td>3</td><td>up</td></tr>
249</tbody>
250</table>
251 
25285simandl<p>It also sets the following additional Hint Variables, to use in a <a href="config-reference.html#NODE_LABEL">LABEL,</a> COMMENT or <a href="config-reference.html#LINK_NOTES">NOTES</a> section as you see fit:
253<em>cacti_hostname</em>, <em>cacti_description</em>, <em>cacti_curtime</em>, <em>cacti_avgtime</em>,
254<em>cacti_mintime</em>, <em>cacti_maxtime</em>, <em>cacti_availability</em>, <em>cacti_faildate</em>,
255and <em>cacti_recdate</em> </p>.
256 
2571simandl<p>An appropriate <a href="config-reference.html#GLOBAL_SCALE">SCALE</a> definition to get red, green, yellow and grey labels based on the state of a host would be:
25885simandl<div class="example"><pre><a href="config-reference.html#GLOBAL_SCALE">SCALE</a> cactiupdown 0 0.5 192 192 192
2591simandl<a href="config-reference.html#GLOBAL_SCALE">SCALE</a> cactiupdown 0.5 1.5 255 0 0
260<a href="config-reference.html#GLOBAL_SCALE">SCALE</a> cactiupdown 1.5 2.5 0 0 255
261<a href="config-reference.html#GLOBAL_SCALE">SCALE</a> cactiupdown 2.5 3.5 0 255 0 </pre>
26285simandl</div>
263 </p>
264<hr />
2651simandl 
26685simandl 
267 
268 
269 
270 
271 
272 
273 
274<h3><a name="cactithold"></a>Cacti threshold status</h3>
275<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> cactimonitor:<em>hostid</em></div>
276<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> cactithold:<em>tholdid</em></div>
277<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> cactithold:<em>rra_id</em>:<em>data_id</em></div>
278<p>When used with cactimonitor: prefix, this plugin takes data from both Cacti's host table and from the THold plugin's data to produce a composite state, similar to the one used by the Monitor plugin. </p>
279<p>It sets all the same Hint Variables as cactihost: plus a couple more: <em>thold_failcount</em> is the number of thresholds failing on this host,
280and <em>thold_failpercent</em> is the percentage of thresholds set on this host that are failing. Bear in mind that if you have both a minimum and
281maximum set on the same variable, then you will <em>never</em> get 100% failure. </p>
282<p>It also has a new value possible for the <em>state</em> Hint Variable - 'tholdbreached', and adds a new state number 4, for "threshold breached". </p>
283<p>In the second and third forms, with the cactithold: prefix, the plugin simply returns either a 0 or 1 for the 'input bandwidth' value. 0 if the threshold has not been breached,
2841 if it has. You can supply either the internal THold id number for a threshold (not easily visible), the the rra_id and data_id values which can be seen at the end of URLs within
285THolds web pages. </p>
286 
287<p>You can provide a similar output to the Monitor plugin by using the cactimonitor: <a href="config-reference.html#LINK_TARGET">TARGET</a> and multiple icons. Create a set of coloured (or otherwise different) icons for your node - they should have 'up','down','disabled','recovering' and 'tholdbreached' in the names. Then: <div class="example"><pre>
288 <a href="config-reference.html#NODE_NODE">NODE</a> myserver
289 <a href="config-reference.html#NODE_LABEL">LABEL</a> Server 1
290 <a href="config-reference.html#NODE_POSITION">POSITION</a> 100 100
291 <a href="config-reference.html#LINK_TARGET">TARGET</a> cactimonitor:77
292 <a href="config-reference.html#NODE_ICON">ICON</a> images/server_{node:this:state}.png
293 <a href="config-reference.html#NODE_LABELOFFSET">LABELOFFSET</a> S
294 <a href="config-reference.html#LINK_USESCALE">USESCALE</a> none
295</pre>
296</div>
297Will allow you to change the icon between images/server_up.png, images/server_down.png etc.. as the state in Cacti changes and thresholds are breached. The <a href="config-reference.html#LINK_USESCALE">'USESCALE</a> none' on the end
298stops the label for the node from changing colour as well. </p>
299 
300<p>You can make use of the <a href="config-reference.html#LINK_TARGET">TARGET</a> aggregation features of weathermap to make a value that is effectively a 'percentage badness' for a set of thresholds. Suppose you have a set of load-balanced firewalls,
301and you want to see how many of the set have exceeded their session count. You would set up thresholds on each firewall as normal, and then:
302<div class="example">
303<pre>
304 <a href="config-reference.html#GLOBAL_SCALE">SCALE</a> badness 0 100 0 255 0 255 0 0
305 <a href="config-reference.html#NODE_NODE">NODE</a> firewall_status
306 <a href="config-reference.html#LINK_TARGET">TARGET</a> cactithold:334:22 cactithold:34:255 cactithold:337:235 cactithold:33:254
307 <a href="config-reference.html#NODE_MAXVALUE">MAXVALUE</a> 4
308 <a href="config-reference.html#LINK_USESCALE">USESCALE</a> badness in
309</pre>
310</div>
311defines a scale where 0 is green and 100% is red and in between is a smooth gradient. Each target will return either 0 or 1, so 100% failed thresholds gives a value of 4. Setting the <a href="config-reference.html#NODE_MAXVALUE">MAXVALUE</a> to 4 makes that 100% within weathermap.
312 </p>
313<hr />
314 
315 
316 
317 
318 
319 
320 
321 
322 
323<h3><a name="cactidsstats"></a>Cacti DSStats data collection plugin</h3>
324 
325<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> dsstats:<em>dsid</em>:<em>in_ds</em>:<em>out_ds</em></div>
326<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> dsstats:<em>source</em>:<em>dsid</em>:<em>in_ds</em>:<em>out_ds</em></div>
327 
328<p>The <a href="http://forums.cacti.net/about33875.html">DSStats Cacti plugin</a> stores data as the poller collects it, and also collates periodic average and maximums.
329Which are all stored in tables in the Cacti database. This makes collecting data (especially the periodic data) much more efficient.
330This DS plugin will read that data, saving a lot of external calls to <tt>rrdtool</tt>. This is similar to the 'poller_output' mode of the
331rrdtool DS, except that this way will allow you to easily make monthly or weekly summary maps. On the downside you need to supply the Cacti internal
332datasource ID for each target, rather than the rrd filename. </p>
333 
334<p>The <em>dsid</em> parameter is the 'local_data_id' in Cacti - you can see this in the URLs on the datasource management page. The 'in_ds' and 'out_ds' are the names
335of the RRD DS that Cacti will update with these values (e.g. traffic_in and traffic_out for normal Interface Traffic). Either of the in_ds or out_ds can be a single hyphen (-) to
336indicate that you don't care about filling in a value for that direction. </p>
337<p>The <em>source</em> parameter defines what data to use for this query. 'last' fetches the most-recently collected value for that dsid. The remaining possibilities all combine a
338period and a type. The possible periods are 'hourly','daily','weekly','monthly' and 'yearly'. The types are 'average' and 'peak'. So to get the maximium value over the last week, use 'weeklypeak' as your <em>source</em>.
339If one is not specified at all (as in the first format above), then 'last' is assumed. You can change that default by setting the global <a href="config-reference.html#GLOBAL_SET">SET</a> variable "dsstats_default_type" to the required default. </p>
340 
341<p>The DSStats datasource also sets the same additional variables described in for <a href="#rrdpollerextras">poller_output support</a> in the rrdtool plugin. </p>
342<p><strong>NOTE:</strong> One important difference between this and poller_ouput mode or regular rrdtool targets is that this plugin fetches the
343raw data from the poller. If you collecting octet counter data (like interface traffic) then you will need to multiply that data by 8 to get
344bits per second: </p>
345<div class="example"><pre>
346 <a href="config-reference.html#LINK_TARGET">TARGET</a> 8*dsstats:4455:traffic_in:traffic_out
347</pre>
348</div>
349 
350<hr />
351 
352 
353 
354 
355 
356 
357 
358 
359 
360 
3611simandl<h3><a name="snmp"></a>SNMP value</h3>
362 
36385simandl<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> snmp:<em>community</em>:<em>host</em>:<em>in_oid</em>:<em>out_oid</em></div>
3641simandl 
36585simandl<p>This is a fairly experimental plugin. It requires the PHP snmp extension to be installed and enabled. Even then, it's hit & miss whether it will work on a particular system - some versions of PHP have better support for SNMP than others, and on some platforms it is different to others, too. </p>
366<p>This plugin can directly query an SNMP-manageable device and fetch an OID from it. You can specify '-' in place of either of the OIDs if you only need to fetch one value. </p>
367<p>It returns the numeric values for each OID as the in and out values. It <em>does not</em> currently understand COUNTER types, so you will
368just get the total bytes rather than a rate, for example. </p>
369<p>It also sets snmp_in_raw and snmp_out_raw to the 'raw' results from the SNMP library, before the plugin tried to force them to be numbers. </p>
3701simandl 
37185simandl<p>You can adjust the behaviour of the SNMP plugin with some global <a href="config-reference.html#GLOBAL_SET">SET</a> values. 'snmp_timeout' sets the timeout for a request in <em>microseconds</em> (so the default 1000000=1 second). 'snmp_retries' changes the number of retries per request from the default (2).
372Finally, you can set 'snmp_abort_count' to an integer value - this is the number of failures for a given host before weathermap gives up on that host. The default is 0 (unlimited). This can
373improve performance if you are polling a lot of switch ports on a device that has gone down, for example. </p>
374 
375<hr />
376 
377 
378 
379 
380 
381 
382 
383 
384 
385 
386 
387 
3881simandl<h3><a name="script"></a>External script</h3>
389 
39085simandl<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> !<em>scriptname</em></div>
3911simandl 
39285simandl<p>This plugin is fairly experimental and not thoroughly tested. </p>
393<p>This plugin allows you to write small external scripts, and pass the value from the script into Weathermap. The output format of the script is the same one that MRTG uses for <em>it's</em> external scripts, so it's possible that you can even find an existing script to do what you want, somewhere else. </p>
394<p>MRTG external scripts produce 4 lines of output. Line 1 is the state of the first (in) variable, line 2 is the state of the second (out) variable, line 3 is the uptime of the device, and line 4 is the name of the device. This plugin only cares about the first 2 lines, but it <em>does</em> expect there to be 4 lines. </p>
395<p>This plugin also sets a few Hint Variables - external_line1, external_line2, external_line3, and external_line4 are the raw output of your script. This can be useful
396if your script really is intended for MRTG, as the 3rd line would be the device uptime and the 4th line would be it's name. </p>
3971simandl 
39885simandl<hr />
399 
400 
401 
402 
403 
404 
405 
406 
407 
408 
409<h3><a name="fping"></a>FPING</h3>
410 
411<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> fping:<em>hostname</em></div>
412 
413<p>This plugin is fairly experimental and not thoroughly tested. It's also rather slow, as each node takes 5 seconds or so to run. There are planned improvements to take advantage of fping's parallelisation support in a future version. </p>
414<p>This plugin uses the 'fping' command-line tool [<a href="http://fping.sourceforge.net/">http://fping.sourceforge.net/</a>] to ping a host, and returns
415various statistics about it's state. </p>
416<p>You can adjust the number of pings (the default is 5), by setting the 'fping_ping_count' global variable to another number. </p>
417<p>After it has been run, the 'in' value is the average ping time in milliseconds, the 'out' value is the percentage packet loss from 5 pings (or whatever you have set), the 'fping_min' Hint Variable is the minimum ping time in milliseconds, and 'fping_max' is the maximum. </p>
418 
419 
420 
421 
422<h3><a name="time"></a>Current Time</h3>
423 
424<div class="definition"><a href="config-reference.html#LINK_TARGET">TARGET</a> time:<em>zonename</em></div>
425 
426<p>This plugin allows you to embed the current time in any timezone in your maps. </p>
427<p>The 'in' value is the hours, the 'out' value is minutes. </p>
428<p>The format for specifying timezones is the same as most unix systems - Europe/London, US/Eastern, Japan and Etc/GMT+10 are all valid. These names are
429usually stored in /usr/share/zoneinfo on a unix-based system. </p>
430 
431<p>This plugin also sets a few Hint Variables - time_time12, time_time24, time_time12ap. These are the current time in 12-hour, 24-hour and 12-hour-with-am/pm, respectively. </p>
432 
433<p>A typical use is:
434 <code>
435<a href="config-reference.html#NODE_NODE">NODE</a> timelabel
436 <a href="config-reference.html#NODE_LABEL">LABEL</a> {node:this:time_time12ap}
437 <a href="config-reference.html#LINK_USESCALE">USESCALE</a> none
438 <a href="config-reference.html#LINK_TARGET">TARGET</a> time:Europe/Paris
439 </code>
440 </p>
441 
442<p><strong>NOTE:</strong>The timezone handling code requires at least PHP version 5. </p>
443 
444<hr />
445 
446 
4471simandl </div>
448</body>
449</html>

Powered by WebSVN 2.2.1