jablonka.czprosek.czf

weathermap

 Subversion Repositories:
[/] [docs/] [pages/] [config-reference.html] - Blame information for rev 25

 

Line No. Rev Author Line
11simandl<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
4<link rel="stylesheet" type="text/css" media="screen" href="weathermap.css">
5<title>PHP Weathermap
6v0.91
7 Configuration Reference</title>
8</head>
9<body><div id="frame">
10 
11 
12<div class="navcontainer">
13 <ul id="navlist">
14 <li><a href="main.html">Main Page</a></li>
15 <li><a href="main.html#installation">Installation</a></li>
16 <li><a href="main.html#basics">Basics</a></li>
17 <li><a href="faq.html">FAQ and Tips</a></li>
18 <li><a href="main.html#example">Sample Map</a></li>
19 <li><a href="cli-reference.html">CLI Reference</a></li>
20 <li><a href="config-reference.html">Config Reference</a></li>
21 <li><a href="advanced.html">Advanced Topics</a></li>
22 <li><a href="editor.html">Editor</a></li>
23 <li><a href="cacti-plugin.html">Cacti Plugin</a></li>
24 <li><a href="http://www.network-weathermap.com/">Site</a></li>
25 </ul>
26</div>
27 
28<div id="header">
29 <h1>PHP Weathermap
30v0.91
31</h1>
32 <h4>Copyright &copy; 2005-2007 Howard Jones, <tt><a
33href="mailto:howie@thingy.com">howie@thingy.com</a></tt>. (<a
34href="http://www.network-weathermap.com/">Website</a>)</h4>
35</div>
36 
37 
38<h2><a name="configref">Configuration Reference</a></h2>
39<p>This page is automatically compiled, and documents all the configuration directives that are available in PHP Weathermap
40v0.91
41. </p>
42 <h1 class="configsection">Introduction</h1>
43 <div class="preamble"><div id="contents">
44 <h4 class="configsection">Node-specific Configuration Directives</h4>
45 <p id="context_NODE">
46 <a href="#NODE_NODE">NODE</a>
47 <a href="#NODE_POSITION">POSITION</a>
48 <a href="#NODE_LABEL">LABEL</a>
49 <a href="#NODE_TARGET">TARGET</a>
50 <a href="#NODE_USESCALE">USESCALE</a>
51 <a href="#NODE_MAXVALUE">MAXVALUE</a>
52 <a href="#NODE_ICON">ICON</a>
53 <a href="#NODE_LABELOFFSET">LABELOFFSET</a>
54 <a href="#NODE_LABELFONT">LABELFONT</a>
55 <a href="#NODE_COLORS">*COLOR</a>
56 <a href="#NODE_INFOURL">INFOURL</a>
57 <a href="#NODE_OVERLIBGRAPH">OVERLIBGRAPH</a>
58 <a href="#NODE_OVERLIBWIDTH">OVERLIBWIDTH</a>
59 <a href="#NODE_OVERLIBHEIGHT">OVERLIBHEIGHT</a>
60 <a href="#NODE_OVERLIBCAPTION">OVERLIBCAPTION</a>
61 <a href="#NODE_NOTES">NOTES</a>
62 <a href="#NODE_SET">SET</a>
63 </p>
64 <h4 class="configsection">Link-specific Configuration Directives</h4>
65 <p id="context_LINK">
66 <a href="#LINK_LINK">LINK</a>
67 <a href="#LINK_NODES">NODES</a>
68 <a href="#LINK_TARGET">TARGET</a>
69 <a href="#LINK_USESCALE">USESCALE</a>
70 <a href="#LINK_WIDTH">WIDTH</a>
71 <a href="#LINK_BANDWIDTH">BANDWIDTH</a>
72 <a href="#LINK_BWLABEL">BWLABEL</a>
73 <a href="#LINK_BWLABELPOS">BWLABELPOS</a>
74 <a href="#LINK_BWFONT">BWFONT</a>
75 <a href="#LINK_INCOMMENT">INCOMMENT</a>
76 <a href="#LINK_OUTCOMMENT">OUTCOMMENT</a>
77 <a href="#LINK_COMMENTFONT">COMMENTFONT</a>
78 <a href="#LINK_COLORS">*COLOR</a>
79 <a href="#LINK_INFOURL">INFOURL</a>
80 <a href="#LINK_OVERLIBGRAPH">OVERLIBGRAPH</a>
81 <a href="#LINK_OVERLIBWIDTH">OVERLIBWIDTH</a>
82 <a href="#LINK_OVERLIBHEIGHT">OVERLIBHEIGHT</a>
83 <a href="#LINK_OVERLIBCAPTION">OVERLIBCAPTION</a>
84 <a href="#LINK_NOTES">NOTES</a>
85 <a href="#LINK_VIA">VIA</a>
86 <a href="#LINK_ARROWSTYLE">ARROWSTYLE</a>
87 <a href="#LINK_SET">SET</a>
88 </p>
89 <h4 class="configsection">Global Configuration Directives</h4>
90 <p id="context_GLOBAL">
91 <a href="#GLOBAL_BACKGROUND">BACKGROUND</a>
92 <a href="#GLOBAL_WIDTH">WIDTH</a>
93 <a href="#GLOBAL_HEIGHT">HEIGHT</a>
94 <a href="#GLOBAL_HTMLOUTPUTFILE">HTMLOUTPUTFILE</a>
95 <a href="#GLOBAL_IMAGEOUTPUTFILE">IMAGEOUTPUTFILE</a>
96 <a href="#GLOBAL_FONTDEFINE">FONTDEFINE</a>
97 <a href="#GLOBAL_FONT">*FONT</a>
98 <a href="#GLOBAL_COLORS">*COLOR</a>
99 <a href="#GLOBAL_TIMEPOS">TIMEPOS</a>
100 <a href="#GLOBAL_TITLE">TITLE</a>
101 <a href="#GLOBAL_TITLEPOS">TITLEPOS</a>
102 <a href="#GLOBAL_KILO">KILO</a>
103 <a href="#GLOBAL_HTMLSTYLE">HTMLSTYLE</a>
104 <a href="#GLOBAL_SCALE">SCALE</a>
105 <a href="#GLOBAL_KEYPOS">KEYPOS</a>
106 <a href="#GLOBAL_KEYSTYLE">KEYSTYLE</a>
107 <a href="#GLOBAL_SET">SET</a>
108 </p>
109 </div></div>
110 
111 
112 <h1 id="s_scope_NODE" class="configsection">Node-specific Configuration Directives</h1>
113 <div class="referenceentry">
114<h2><a name="NODE_NODE">NODE</a></h2>
115<div class="definition">NODE <em class="meta">nodename</em>
116</div>
117<div class="description">
118<p>The initial definition of a NODE. This must come before any other configuration related to this node.</p><p>The 'nodename' is used in link definitions to specify which nodes the link joins. The nodename is must be a single
119 word, with no spaces.</p><p>There is one special node name, 'DEFAULT', which allows for the setting of defaults.
120 All nodes that are defined after this one in the configuration file will use the parameters
121 of this node as a starting point. For this reason, it is best to define the DEFAULT node at the
122 top of the configuration file, if you intend to use it.</p>
123</div>
124<div class="changes">
125<h3>Change History</h3>
126<dl>
127<dt>0.7</dt>
128<dd>Added DEFAULT node.</dd>
129</dl>
130</div>
131</div>
132 <div class="referenceentry">
133<h2><a name="NODE_POSITION">POSITION</a></h2>
134<div class="definition">POSITION <em class="meta">x-coord</em> <em class="meta">y-coord</em>
135</div>
136<div class="definition">POSITION <em class="meta">nodename</em> <em class="meta">x-coord</em> <em class="meta">y-coord</em>
137</div>
138<div class="description">
139<p>Specifies where to place the node on the map. Coordinates are in pixel units, with the origin at the top-left of the map.</p><p>Optionally, you can also specify another node that the coordinates are relative to. This allows you to have 'sub-nodes' that follow a master node around as you alter the map. Relative nodes can be relative to other relative nodes, as long as the node at the end of the chain is not relatively positioned!</p>
140</div>
141<div class="examples">
142<h3>Examples</h3>
143<div class="example">
144<h5>Example of a 'sub-node', that will be 20 pixels above the main node, wherever that gets moved to. It is used to show additional information about the main node.</h5>
145<pre>
146 NODE main_node
147 POSITION 200 320
148 LABEL MAIN
149 
150 NODE sub_node
151 POSITION main_node 0 -20
152 LABEL {nodes:main_node:invalue}
153 </pre>
154</div>
155</div>
156<div class="changes">
157<h3>Change History</h3>
158<dl>
159<dt>0.9</dt>
160<dd>Add relative position from other nodes.</dd>
161</dl>
162</div>
163</div>
164 <div class="referenceentry">
165<h2><a name="NODE_LABEL">LABEL</a></h2>
166<div class="definition">LABEL <em class="meta">labeltext</em>
167</div>
168<div class="description">
169<p>Specifies a label for the node. Everything to the end of the line is used.</p><p>If the node has an <a href="#NODE_ICON">ICON</a> defined as well, then you can specify the position of the label relative to the node's centre-point by using <a href="#NODE_LABELOFFSET">LABELOFFSET.</a> </p><p>The text for the label can contain <a href="advanced.html#tokens">special tokens</a> to show map data.</p><p>This is drawn using the font specified by <a href="#NODE_LABELFONT">LABELFONT</a> in the colours specified by LABELFONTCOLOR, LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR.</p>
170</div>
171<div class="changes">
172<h3>Change History</h3>
173<dl>
174<dt>0.9</dt>
175<dd>Added 'special token' support.</dd>
176</dl>
177</div>
178</div>
179 <div class="referenceentry">
180<h2><a name="NODE_TARGET">TARGET</a></h2>
181<div class="definition">TARGET <em class="meta">targetspec</em>
182</div>
183<div class="description">
184<p>Specifies where to look for the current "throughput"
185 information for this <a href="#NODE_NODE">NODE.</a> You can also specify multiple targets, which will then be added together to make the aggregate result
186which is then displayed. Specify the targets on one TARGET line, seperated with a space. If a targetspec starts with a '-', then it's value will be <i>subtracted</i> from the final result instead.</p><p>It's important to note, especially for NODEs, that the value that is used does not have to be bandwidth. You can use data for temperature, session-counts, CPU usage or anything else you can get data for.</p><p>The actual contents of the <em>targetspec</em> depend on the data source plugins that are
187 available. <a href="targets.html">The standard plugins are documented here</a>.</p>
188</div>
189<div class="examples">
190<h3>Examples</h3>
191<div class="example">
192<h5>Using multiple data sources for one link</h5>
193<pre>TARGET link1a.rrd link1b.rrd</pre>
194</div>
195<div class="example">
196<h5>Taking the input from one file, and output from another</h5>
197<pre>TARGET poot.rrd:-:DS1 poot2.rrd:DS0:-</pre>
198</div>
199<div class="example">
200<h5>A suitable tab-delimited data file</h5>
201<pre>link1 3M 4M
202link2 66K 1.8M
203link3 34.6K 113</pre>
204</div>
205</div>
206<div class="changes">
207<h3>Change History</h3>
208<dl>
209<dt>0.91</dt>
210<dd>Added 'negative' datasources.</dd>
211<dt>0.9</dt>
212<dd>Added plugin data sources, node targets, and added new plugins.</dd>
213<dt>0.8</dt>
214<dd>Added ability to specify multiple targets. Added tab-delimited data source. Added 'ignore' DS name.</dd>
215<dt>0.5</dt>
216<dd>Added ability to specify DS names.</dd>
217</dl>
218</div>
219</div>
220 <div class="referenceentry">
221<h2><a name="NODE_USESCALE">USESCALE</a></h2>
222<div class="definition">USESCALE <em class="meta">scalename</em>
223</div>
224<div class="definition">USESCALE <em class="meta">scalename</em> <em class="meta">{in,out}</em>
225</div>
226<div class="description">
227<p>Specify which <a href="#GLOBAL_SCALE">SCALE</a> to use to decide the colour of this node.</p><p>After the percentage usage is calculated (using BANDWIDTH/MAXVALUE and data from the <a href="#NODE_TARGET">TARGET</a> line),
228 the colour is decided by looking up the percentage against this <a href="#GLOBAL_SCALE">SCALE.</a> If there is no USESCALE
229 line, then the default scale is used.</p><p>For nodes, you can also specify a scalename of 'none'. This stops the node's colour from changing at all. This is useful if you want to
230 use the <a href="#NODE_TARGET">TARGET</a> line to fetch data that is used in the <a href="#NODE_LABEL">LABEL</a> or <a href="#NODE_ICON">ICON</a> of the node, for example, without changing the colour of the node itself.</p>
231</div>
232<div class="changes">
233<h3>Change History</h3>
234<dl>
235<dt>0.9</dt>
236<dd>Added named scales and USESCALE.</dd>
237</dl>
238</div>
239</div>
240 <div class="referenceentry">
241<h2><a name="NODE_MAXVALUE">MAXVALUE</a></h2>
242<div class="definition">MAXVALUE <em class="meta">max-value</em>
243</div>
244<div class="definition">MAXVALUE <em class="meta">max-in-value</em> <em class="meta">max-out-value</em>
245</div>
246<div class="description">
247<p>Specifies the maximum value(s) for the node, in the same way that <a href="#LINK_BANDWIDTH">BANDWIDTH</a> does for a <a href="#LINK_LINK">LINK.</a> These are used to calculate the percentage usage value, which in turn is used to decide the NODE's colour, if it has a <a href="#NODE_TARGET">TARGET</a> defined.</p><p>The default value is 100, which has the effect of not changing the input value ( (n/100)*100 = n ).</p>
248</div>
249<div class="changes">
250<h3>Change History</h3>
251<dl>
252<dt>0.9</dt>
253<dd>Added TARGET and MAXVALUE for nodes.</dd>
254</dl>
255</div>
256</div>
257 <div class="referenceentry">
258<h2><a name="NODE_ICON">ICON</a></h2>
259<div class="definition">ICON <em class="meta">iconimagefile</em>
260</div>
261<div class="definition">ICON <em class="meta">maxwidth</em> <em class="meta">maxheight</em> <em class="meta">iconimagefile</em>
262</div>
263<div class="definition">ICON none</div>
264<div class="description">
265<p>Specifies an icon to use for the node.</p><p>The filename can either be a full path to the image, or a relative one. </p><p>The icon file must be in PNG, JPEG or GIF format. Alpha-transparency within the icon should be honoured by Weathermap for PNG icons, to create irregular shapes.</p><p>If you specify the word 'none' as the icon filename, then no icon is used. This is useful if you have specified an ICON in the DEFAULT <a href="#NODE_NODE">NODE,</a> and want to override that for a few special cases.</p><p>The second form allows you to specify a maximum width and height for the icon. If the PNG file that you specify is bigger or smaller than this size, then it is automatically scaled up (or down) in proportion, so that it fits into a box of the size you specify.</p><p>The size of the icon image is used by <a href="#NODE_LABELOFFSET">LABELOFFSET</a> to decided how far to move the label, if you use compass-point offsets.</p><p>The text for the filename can contain <a href="advanced.html#tokens">special tokens</a> to select an icon based on map data.</p>
266</div>
267<div class="changes">
268<h3>Change History</h3>
269<dl>
270<dt>0.9</dt>
271<dd>Added 'special token' support.</dd>
272<dt>0.9</dt>
273<dd>Added JPEG and GIF support.</dd>
274<dt>0.9</dt>
275<dd>Added special icon 'none', and automatic scaling.</dd>
276</dl>
277</div>
278</div>
279 <div class="referenceentry">
280<h2><a name="NODE_LABELOFFSET">LABELOFFSET</a></h2>
281<div class="definition">LABELOFFSET <em class="meta">compass-point</em>
282</div>
283<div class="definition">LABELOFFSET <em class="meta">x-offset</em> <em class="meta">y-offset</em>
284</div>
285<div class="description">
286<p>If you specify an <a href="#NODE_ICON">ICON,</a> and also a <a href="#NODE_LABEL">LABEL,</a> then you will find that the label is often hard to read.
287 LABELOFFSET allows you to move the position of the <a href="#NODE_LABEL">LABEL,</a> so that it's not directly over the centre
288 of the node anymore. </p><p>You can specify a compass-point (e.g. LABELOFFSET S). The compass-point method takes the size of the
289 <a href="#NODE_ICON">ICON,</a> and uses that as the offset distance in the direction you specify. This way, you can change your
290 icon for something of a different size, and not need to change all your offsets. You can use the main
291 8 points of the compass: N, E, S, W, NE, SE, NW, SW.</p><p>For more control, you can specify an integer offset for the x and y positions of the label (e.g. LABELOFFSET -10 -20) instead.</p>
292</div>
293<div class="changes">
294<h3>Change History</h3>
295<dl>
296<dt>0.7</dt>
297<dd>Originally added LABELOFFSET</dd>
298</dl>
299</div>
300</div>
301 <div class="referenceentry">
302<h2><a name="NODE_LABELFONT">LABELFONT</a></h2>
303<div class="definition">LABELFONT <em class="meta">fontnumber</em>
304</div>
305<div class="description">
306<p>Specify the font used for drawing the LABEL.</p><p>Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using the <a href="#GLOBAL_FONTDEFINE">FONTDEFINE</a> directive.</p><p><img src="../images/font-sizes.png"></img>The built-in GD fonts.</p>
307</div>
308<div class="changes">
309<h3>Change History</h3>
310<dl>
311<dt>0.7</dt>
312<dd>Global NODEFONT became per-node LABELFONT.</dd>
313<dt>0.6</dt>
314<dd>Originally added NODEFONT.</dd>
315</dl>
316</div>
317</div>
318 <div class="referenceentry">
319<h2><a name="NODE_COLORS">*COLOR</a></h2>
320<div class="definition">LABELFONTCOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
321</div>
322<div class="definition">LABELFONTSHADOWCOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
323</div>
324<div class="definition">LABELBGCOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
325</div>
326<div class="definition">LABELOUTLINECOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
327</div>
328<div class="description">
329<p>Specify the colours used for drawing the LABEL.</p><p>red, green and blue are numbers from 0 to 255.</p><p>LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR have an additional option - 'none' - which stops that element of the <a href="#NODE_LABEL">LABEL</a> being drawn. LABELFONTSHADOWCOLOR defaults to 'none'.</p>
330</div>
331<div class="changes">
332<h3>Change History</h3>
333<dl>
334<dt>0.8</dt>
335<dd>Added LABELFONTCOLOR, LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR.</dd>
336</dl>
337</div>
338</div>
339 <div class="referenceentry">
340<h2><a name="NODE_INFOURL">INFOURL</a></h2>
341<div class="definition">INFOURL <em class="meta">url</em>
342</div>
343<div class="description">
344<p>Creates a hyperlink in the HTML output.</p><p>If you are using the HTML output facility, then a link is added to the
345 &lt;map&gt; section of the HTML so that when you click on the node, you are
346 taken to the url specified here.</p>
347</div>
348</div>
349 <div class="referenceentry">
350<h2><a name="NODE_OVERLIBGRAPH">OVERLIBGRAPH</a></h2>
351<div class="definition">OVERLIBGRAPH <em class="meta">url</em>
352</div>
353<div class="description">
354<p>Creates a popup image in the HTML output.</p><p>If you are using the HTML output facility, and <a href="#GLOBAL_HTMLSTYLE">HTMLSTYLE</a> is set to 'overlib', then a link is added to the
355 &lt;map&gt; section of the HTML so that when you move the mouse pointer over the the node, a box will pop up
356 containing the image that you specify. Typically used to link to historical data in your network monitoring system.</p><p>If a <a href="#NODE_NOTES">NOTES</a> line is also specified for a node, then the image specified here appears with the <a href="#NODE_NOTES">NOTES</a> text underneath it.</p>
357</div>
358<div class="examples">
359<h3>Examples</h3>
360<div class="example">
361<h5>Typical use of OVERLIBGRAPH</h5>
362<pre>OVERLIBGRAPH http://www.yoursite.net/mrtg/router1-cpu-daily.png</pre>
363</div>
364</div>
365</div>
366 <div class="referenceentry">
367<h2><a name="NODE_OVERLIBWIDTH">OVERLIBWIDTH</a></h2>
368<div class="definition">OVERLIBWIDTH <em class="meta">imagewidth</em>
369</div>
370<div class="description">
371<p>Specify the width, in pixels of the graph image referred to by <a href="#NODE_OVERLIBGRAPH">OVERLIBGRAPH</a> line.</p><p>This is an optional extra that allows the OverLib library to make a better job of
372 positioning the 'popup' image so that it doesn't appear off the edge of the screen.
373 Typically, you would use this once, in the DEFAULT <a href="#NODE_NODE">NODE.</a> If you use this, you must
374 also use <a href="#NODE_OVERLIBHEIGHT">OVERLIBHEIGHT,</a> for either to have any effect.</p>
375</div>
376<div class="changes">
377<h3>Change History</h3>
378<dl>
379<dt>0.7</dt>
380<dd>Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.</dd>
381</dl>
382</div>
383</div>
384 <div class="referenceentry">
385<h2><a name="NODE_OVERLIBHEIGHT">OVERLIBHEIGHT</a></h2>
386<div class="definition">OVERLIBHEIGHT <em class="meta">imagewidth</em>
387</div>
388<div class="description">
389<p>Specify the width, in pixels of the graph image referred to by <a href="#NODE_OVERLIBGRAPH">OVERLIBGRAPH</a> line.</p><p>This is an optional extra that allows the OverLib library to make a better job of
390 positioning the 'popup' image so that it doesn't appear off the edge of the screen.
391 Typically, you would use this once, in the DEFAULT <a href="#NODE_NODE">NODE.</a> If you use this, you must
392 also use <a href="#NODE_OVERLIBWIDTH">OVERLIBWIDTH,</a> for either to have any effect.</p>
393</div>
394<div class="changes">
395<h3>Change History</h3>
396<dl>
397<dt>0.7</dt>
398<dd>Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.</dd>
399</dl>
400</div>
401</div>
402 <div class="referenceentry">
403<h2><a name="NODE_OVERLIBCAPTION">OVERLIBCAPTION</a></h2>
404<div class="definition">OVERLIBCAPTION <em class="meta">caption text</em>
405</div>
406<div class="description">
407<p>Specify the caption used for the popup HTML 'window' if you have also specified an <a href="#NODE_OVERLIBGRAPH">OVERLIBGRAPH</a> line. By default, this is the name of the NODE.</p><p>The text for the caption can contain <a href="advanced.html#tokens">special tokens</a> to show map data.</p>
408</div>
409<div class="changes">
410<h3>Change History</h3>
411<dl>
412<dt>0.9</dt>
413<dd>Originally added OVERLIBCAPTION.</dd>
414</dl>
415</div>
416</div>
417 <div class="referenceentry">
418<h2><a name="NODE_NOTES">NOTES</a></h2>
419<div class="definition">NOTES <em class="meta">notes text</em>
420</div>
421<div class="description">
422<p>Specifies the text or HTML notes for a node. </p><p>The <em>notes text</em> appears in a popup box when the user hovers their mouse over the node. If an <a href="#NODE_OVERLIBGRAPH">OVERLIBGRAPH</a> is specified too, then the text appears below the graph.</p><p>The map <a href="#GLOBAL_HTMLSTYLE">HTMLSTYLE</a> must be set to 'overlib' to enable any of the mouse-hover functionality.</p>
423</div>
424<div class="changes">
425<h3>Change History</h3>
426<dl>
427<dt>0.9</dt>
428<dd>Originally added NOTES.</dd>
429</dl>
430</div>
431</div>
432 <div class="referenceentry">
433<h2><a name="NODE_SET">SET</a></h2>
434<div class="definition">SET <em class="meta">hintname</em> <em class="meta">hintvalue</em>
435</div>
436<div class="description">
437<p>Specifies a value for a <em>hint variable</em>.</p><p>Hint Variables allow the user to pass settings to the internals of Weathermap that
438 wouldn't normally need to be changed, or that aren't part of the core Weathermap application.
439 Examples are: small rendering changes, parameters for datasources plugins and similar.</p><p>Hint Variables are either Global for the map, or assigned to a specific link or node.</p><p>There is more about Hint Variables in the <a href="advanced.html">Advanced Topics</a> section.</p>
440</div>
441<div class="changes">
442<h3>Change History</h3>
443<dl>
444<dt>0.9</dt>
445<dd>Originally added SET.</dd>
446</dl>
447</div>
448</div>
449 
450 
451 <h1 id="s_scope_LINK" class="configsection">Link-specific Configuration Directives</h1>
452 <div class="referenceentry">
453<h2><a name="LINK_LINK">LINK</a></h2>
454<div class="definition">LINK <em class="meta">linkname</em>
455</div>
456<div class="description">
457<p>The first line of a LINK definition.</p><p>The linkname must
458 be unique within the map, and must not contain spaces. The only place it currently appears is
459 in the small title-bar of a popup graph if you specify an
460 <a href="#LINK_OVERLIBGRAPH">OVERLIBGRAPH</a> without an <a href="#LINK_OVERLIBCAPTION">OVERLIBCAPTION,</a> however.</p><p>There is one special link name, 'DEFAULT', which allows for the setting of defaults.
461 All links that are defined after this one in the configuration file will use the parameters
462 of this link as a starting point. For this reason, it is best to define the DEFAULT link at the
463 top of the configuration file, if you intend to use it.</p>
464</div>
465</div>
466 <div class="referenceentry">
467<h2><a name="LINK_NODES">NODES</a></h2>
468<div class="definition">NODES <em class="meta">nodename{:compassoffset}</em> <em class="meta">nodename{:compassoffset}</em>
469</div>
470<div class="definition">NODES <em class="meta">nodename{:xoffset:yoffset}</em> <em class="meta">nodename{:xoffset:yoffset}</em>
471</div>
472<div class="description">
473<p>These are the NODEs that this link joins. There can be
474 only two. They are the 'nodename's from the <a href="#NODE_NODE">NODE</a> line for
475 each node.</p><p>Optionally, you can add an offset after a nodename, to move the location of that end of the link. This can help with crowded areas of the map, and also in making parallel links. Valid offsets are named after compass-points: N,S,E,W,NE,NE,SE,SW, or they can be numeric values, to indicate the relative position in pixels from the centre of the node.</p><p>The order of the nodes is significant. When reading data sources, the flow from the first node to the second is considered 'out' and from second-to-first is 'in'.</p>
476</div>
477<div class="examples">
478<h3>Examples</h3>
479<div class="example">
480<h5>Defining a simple link</h5>
481<pre>LINK mylink
482 NODES node1 node2</pre>
483</div>
484<div class="example">
485<h5>Two parallel links, using offsets</h5>
486<pre>LINK firstlink
487 NODES node1:E node2:E
488 
489LINK secondlink
490 NODES node1:W node2:W</pre>
491</div>
492<div class="example">
493<h5>An offset link using pixel offsets</h5>
494<pre>LINK firstlink
495 NODES node1:-10:10 node2:20:12
496 </pre>
497</div>
498</div>
499<div class="changes">
500<h3>Change History</h3>
501<dl>
502<dt>0.9</dt>
503<dd>Added numeric pixel offsets.</dd>
504<dt>0.8</dt>
505<dd>Added ability to specify node offset.</dd>
506</dl>
507</div>
508</div>
509 <div class="referenceentry">
510<h2><a name="LINK_TARGET">TARGET</a></h2>
511<div class="definition">TARGET <em class="meta">targetspec</em>
512</div>
513<div class="description">
514<p>Specifies where to look for the current throughput
515 information for this <a href="#LINK_LINK">LINK.</a> You can also specify multiple targets, which will then be added together to make the aggregate bandwidth
516which is then displayed. Specify the targets on one TARGET line, seperated with a space. If a targetspec starts with a '-', then it's value will be <i>subtracted</i> from the final result instead.</p><p>The actual contents of the <em>targetspec</em> depend on the data source plugins that are
517 available. <a href="targets.html">The standard plugins are documented here</a>.</p>
518</div>
519<div class="examples">
520<h3>Examples</h3>
521<div class="example">
522<h5>Using multiple data sources for one link</h5>
523<pre>TARGET link1a.rrd link1b.rrd</pre>
524</div>
525<div class="example">
526<h5>Taking the input from one file, and output from another</h5>
527<pre>TARGET poot.rrd:-:DS1 poot2.rrd:DS0:-</pre>
528</div>
529<div class="example">
530<h5>A suitable tab-delimited data file</h5>
531<pre>link1 3M 4M
532link2 66K 1.8M
533link3 34.6K 113</pre>
534</div>
535</div>
536<div class="changes">
537<h3>Change History</h3>
538<dl>
539<dt>0.91</dt>
540<dd>Added 'negative' datasources.</dd>
541<dt>0.9</dt>
542<dd>Added plugin data sources, node targets, and added new plugins.</dd>
543<dt>0.8</dt>
544<dd>Added ability to specify multiple targets. Added tab-delimited data source. Added 'ignore' DS name.</dd>
545<dt>0.5</dt>
546<dd>Added ability to specify DS names.</dd>
547</dl>
548</div>
549</div>
550 <div class="referenceentry">
551<h2><a name="LINK_USESCALE">USESCALE</a></h2>
552<div class="definition">USESCALE <em class="meta">scalename</em>
553</div>
554<div class="description">
555<p>Specify which <a href="#GLOBAL_SCALE">SCALE</a> to use to decide the colour of this link.</p><p>After the percentage usage is calculated (using <a href="#LINK_BANDWIDTH">BANDWIDTH</a> and data from the <a href="#LINK_TARGET">TARGET</a> line),
556 the colour is decided by looking up the percentage against this <a href="#GLOBAL_SCALE">SCALE.</a> If there is no USESCALE
557 line, then the default scale is used.</p>
558</div>
559<div class="changes">
560<h3>Change History</h3>
561<dl>
562<dt>0.9</dt>
563<dd>Added named scales and USESCALE.</dd>
564</dl>
565</div>
566</div>
567 <div class="referenceentry">
568<h2><a name="LINK_WIDTH">WIDTH</a></h2>
569<div class="definition">WIDTH <em class="meta">width</em>
570</div>
571<div class="description"><p>Specifies the width of this link when drawn, in pixels.</p></div>
572</div>
573 <div class="referenceentry">
574<h2><a name="LINK_BANDWIDTH">BANDWIDTH</a></h2>
575<div class="definition">BANDWIDTH <em class="meta">max-bandwidth</em>
576</div>
577<div class="definition">BANDWIDTH <em class="meta">max-in-bandwidth</em> <em class="meta">max-out-bandwidth</em>
578</div>
579<div class="description">
580<p>Specifies the maximum throughput of this link, in bits per second.</p><p>This is used to calculate the percentage utilisation, which in turn is used to make the
581colour for the link arrow, and optionally the label on the link.</p><p>The second form allows you to have 'asymmetric' links, like an ADSL, where the first number is the maximum
582bandwidth from node1 to node2 and the second is the maximum from node2 to node1, as they are
583given in the <a href="#LINK_NODES">NODES</a> line.</p><p>Bandwidths can also use K,M,G and T suffixes to specify large values. Also see the <a href="#GLOBAL_KILO">KILO</a> global option though.</p>
584</div>
585<div class="examples">
586<h3>Examples</h3>
587<div class="example">
588<h5>A typical ADSL line (as seen from the CPE)</h5>
589<pre>BANDWIDTH 2M 256K</pre>
590</div>
591</div>
592<div class="changes">
593<h3>Change History</h3>
594<dl>
595<dt>0.9</dt>
596<dd>Added MAXVALUE as a synonym to match NODE MAXVALUE. No change in functionality.</dd>
597<dt>0.5</dt>
598<dd>Added support for decimals in BANDWIDTH specifications.</dd>
599<dt>0.4</dt>
600<dd>Added support for K,M,G,T suffixes on bandwidth specs. Changed bandwidth from bytes to bits.</dd>
601</dl>
602</div>
603</div>
604 <div class="referenceentry">
605<h2><a name="LINK_BWLABEL">BWLABEL</a></h2>
606<div class="definition">BWLABEL <em class="meta">formatname</em>
607</div>
608<div class="description">
609<p>Specifies the type of 'bandwidth' label shown on each link.</p><p>The default is 'percent', but you can also have 'none', 'unformatted' or 'bits'.
610 'bits' shows the actual bandwidth, formatted using K,M,T,G suffixes where appropriate.
611 'unformatted' takes the value from the <a href="#LINK_TARGET">TARGET</a> and displays it without any formatting -
612 this can be useful for mapping things other than bandwidth.
613 'none' hides the bandwidth label altogether.
614 </p>
615</div>
616<div class="changes">
617<h3>Change History</h3>
618<dl>
619<dt>0.8</dt>
620<dd>Added unformatted format.</dd>
621<dt>0.7</dt>
622<dd>Changed from global BWLABELS to per-link BWLABEL.</dd>
623</dl>
624</div>
625</div>
626 <div class="referenceentry">
627<h2><a name="LINK_BWLABELPOS">BWLABELPOS</a></h2>
628<div class="definition">BWLABELPOS <em class="meta">inposition</em> <em class="meta">outposition</em>
629</div>
630<div class="description">
631<p>Specifies the position of the 'bandwidth' labels shown on each link.</p><p>The two position values are percentages along the link arrow, from the first to the second node. Therefore <tt>BWLABELPOS 75 25</tt> is the default.</p>
632</div>
633<div class="changes">
634<h3>Change History</h3>
635<dl>
636<dt>0.9</dt>
637<dd>Added BWLABELPOS</dd>
638</dl>
639</div>
640</div>
641 <div class="referenceentry">
642<h2><a name="LINK_BWFONT">BWFONT</a></h2>
643<div class="definition">BWFONT <em class="meta">fontnumber</em>
644</div>
645<div class="description">
646<p>Specify the font used for drawing the <a href="#LINK_BWLABEL">BWLABEL</a> boxes.</p><p>Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using the <a href="#GLOBAL_FONTDEFINE">FONTDEFINE</a> directive.</p><p><img src="../images/font-sizes.png"></img>The built-in GD fonts.</p>
647</div>
648</div>
649 <div class="referenceentry">
650<h2><a name="LINK_INCOMMENT">INCOMMENT</a></h2>
651<div class="definition">INCOMMENT <em class="meta">string</em>
652</div>
653<div class="description">
654<p>Specifies a comment for the input side of a LINK.</p><p>The link comment appears as text running alongside the link arrow. The font used is governed by <a href="#LINK_COMMENTFONT">COMMENTFONT</a> and the colour by COMMENTFONTCOLOR.</p><p>The text for the comment can contain <a href="advanced.html#tokens">special tokens</a> to show map data.</p><p>The <a href="#LINK_COMMENTFONT">COMMENTFONT</a> <em>must be a TrueType font</em> as these are the only font type to support rotating text.</p>
655</div>
656<div class="changes">
657<h3>Change History</h3>
658<dl>
659<dt>0.9</dt>
660<dd>Added link comments</dd>
661</dl>
662</div>
663</div>
664 <div class="referenceentry">
665<h2><a name="LINK_OUTCOMMENT">OUTCOMMENT</a></h2>
666<div class="definition">OUTCOMMENT <em class="meta">string</em>
667</div>
668<div class="description">
669<p>Specifies a comment for the output side of a LINK.</p><p>The link comment appears as text running alongside the link arrow. The font used is governed by <a href="#LINK_COMMENTFONT">COMMENTFONT</a> and the colour by COMMENTFONTCOLOR.</p><p>The text for the comment can contain <a href="advanced.html#tokens">special tokens</a> to show map data.</p><p>The <a href="#LINK_COMMENTFONT">COMMENTFONT</a> <em>must be a TrueType font</em> as these are the only font type to support rotating text.</p>
670</div>
671<div class="changes">
672<h3>Change History</h3>
673<dl>
674<dt>0.9</dt>
675<dd>Added link comments</dd>
676</dl>
677</div>
678</div>
679 <div class="referenceentry">
680<h2><a name="LINK_COMMENTFONT">COMMENTFONT</a></h2>
681<div class="definition">COMMENTFONT <em class="meta">fontnumber</em>
682</div>
683<div class="description">
684<p>Specify the font used for drawing the <a href="#LINK_INCOMMENT">INCOMMENT</a> and <a href="#LINK_OUTCOMMENT">OUTCOMMENT</a> text.</p><p>Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using the <a href="#GLOBAL_FONTDEFINE">FONTDEFINE</a> directive.</p><p>For Link Comments, you <em>must</em> define a TrueType font. These are the only font that can rotate text through any angle, as required by comments.</p><changes>
685 <change version="0.9">Added link comments</change>
686 </changes>
687</div>
688</div>
689 <div class="referenceentry">
690<h2><a name="LINK_COLORS">*COLOR</a></h2>
691<div class="definition">OUTLINECOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
692</div>
693<div class="definition">BWOUTLINECOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
694</div>
695<div class="definition">BWFONTCOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
696</div>
697<div class="definition">BWBOXCOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
698</div>
699<div class="definition">COMMENTCOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
700</div>
701<div class="description">
702<p>Specify the colours used for drawing the link.</p><p>red, green and blue are numbers from 0 to 255.</p><p>OUTLINECOLOR, BWOUTLINECOLOR and BWBOXCOLOR have an additional option - 'none' - which stops that element of the link being drawn. </p><p>The colours are used as follows:<ul><li>OUTLINECOLOR is the colour of the line around the edge of the arrow.</li>
703 <li>BWOUTLINECOLOR is the colour of the line surrounding the 'bandwidth label' box</li>
704 <li>BWBOXCOLOR is the background colour for the same box</li>
705 <li>BWFONTCOLOR is the colour used for text within that box</li>
706 <li>COMMENTCOLOR is the colour used for the text produced by <a href="#LINK_INCOMMENT">INCOMMENT</a> and <a href="#LINK_OUTCOMMENT">OUTCOMMENT,</a> along the side of a link arrow</li></ul></p>
707</div>
708<div class="changes">
709<h3>Change History</h3>
710<dl>
711<dt>0.9</dt>
712<dd>Added COMMENTCOLOR.</dd>
713<dt>0.8</dt>
714<dd>Added OUTLINECOLOR, BWOUTLINECOLOR, BWFONTCOLOR and BWBOXCOLOR.</dd>
715</dl>
716</div>
717</div>
718 <div class="referenceentry">
719<h2><a name="LINK_INFOURL">INFOURL</a></h2>
720<div class="definition">INFOURL <em class="meta">url</em>
721</div>
722<div class="description">
723<p>Creates a hyperlink in the HTML output.</p><p>If you are using the HTML output facility, then a link is added to the
724 &lt;map&gt; section of the HTML so that when you click on the (weathermap) link, you are
725 taken to the url specified here.</p>
726</div>
727</div>
728 <div class="referenceentry">
729<h2><a name="LINK_OVERLIBGRAPH">OVERLIBGRAPH</a></h2>
730<div class="definition">OVERLIBGRAPH <em class="meta">url</em>
731</div>
732<div class="description">
733<p>Creates a popup image in the HTML output.</p><p>If you are using the HTML output facility, and <a href="#GLOBAL_HTMLSTYLE">HTMLSTYLE</a> is set to 'overlib', then a link is added to the
734 &lt;map&gt; section of the HTML so that when you move the mouse pointer over the the (weathermap) link, a box will pop up
735 containing the image that you specify. Typically used to link to historical data in your network monitoring system.</p><p>If a <a href="#LINK_NOTES">NOTES</a> line is also specified for a link, then the image specified here appears with the <a href="#LINK_NOTES">NOTES</a> text underneath it.</p>
736</div>
737<div class="examples">
738<h3>Examples</h3>
739<div class="example">
740<h5>Typical use of OVERLIBGRAPH</h5>
741<pre>OVERLIBGRAPH http://www.yoursite.net/mrtg/router1-link2-daily.png</pre>
742</div>
743</div>
744<div class="changes">
745<h3>Change History</h3>
746<dl>
747<dt>0.0pre</dt>
748<dd>Odd fact: This command, and the accompanying code to generate overlib imagemaps, were the first modification I ever made to the GRNET perl weathermap,
749 and was what got me interested in writing my own version.</dd>
750</dl>
751</div>
752</div>
753 <div class="referenceentry">
754<h2><a name="LINK_OVERLIBWIDTH">OVERLIBWIDTH</a></h2>
755<div class="definition">OVERLIBWIDTH <em class="meta">imagewidth</em>
756</div>
757<div class="description">
758<p>Specify the width, in pixels of the graph image referred to by <a href="#LINK_OVERLIBGRAPH">OVERLIBGRAPH</a> line.</p><p>This is an optional extra that allows the OverLib library to make a better job of
759 positioning the 'popup' image so that it doesn't appear off the edge of the screen.
760 Typically, you would use this once, in the DEFAULT link. If you use this, you must
761 also use <a href="#LINK_OVERLIBHEIGHT">OVERLIBHEIGHT,</a> for either to have any effect.</p>
762</div>
763<div class="changes">
764<h3>Change History</h3>
765<dl>
766<dt>0.7</dt>
767<dd>Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.</dd>
768</dl>
769</div>
770</div>
771 <div class="referenceentry">
772<h2><a name="LINK_OVERLIBHEIGHT">OVERLIBHEIGHT</a></h2>
773<div class="definition">OVERLIBHEIGHT <em class="meta">imagewidth</em>
774</div>
775<div class="description">
776<p>Specify the width, in pixels of the graph image referred to by <a href="#LINK_OVERLIBGRAPH">OVERLIBGRAPH</a> line.</p><p>This is an optional extra that allows the OverLib library to make a better job of
777 positioning the 'popup' image so that it doesn't appear off the edge of the screen.
778 Typically, you would use this once, in the DEFAULT link. If you use this, you must
779 also use <a href="#LINK_OVERLIBWIDTH">OVERLIBWIDTH,</a> for either to have any effect.</p>
780</div>
781<div class="changes">
782<h3>Change History</h3>
783<dl>
784<dt>0.7</dt>
785<dd>Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.</dd>
786</dl>
787</div>
788</div>
789 <div class="referenceentry">
790<h2><a name="LINK_OVERLIBCAPTION">OVERLIBCAPTION</a></h2>
791<div class="definition">OVERLIBCAPTION <em class="meta">caption text</em>
792</div>
793<div class="description">
794<p>Specify the caption used for the popup HTML 'window' if you have also specified an <a href="#LINK_OVERLIBGRAPH">OVERLIBGRAPH</a> line. By default, this is the name of the LINK.</p><p>The text for the caption can contain <a href="advanced.html#tokens">special tokens</a> to show map data.</p>
795</div>
796<div class="changes">
797<h3>Change History</h3>
798<dl>
799<dt>0.9</dt>
800<dd>Originally added OVERLIBCAPTION.</dd>
801</dl>
802</div>
803</div>
804 <div class="referenceentry">
805<h2><a name="LINK_NOTES">NOTES</a></h2>
806<div class="definition">NOTES <em class="meta">notes text</em>
807</div>
808<div class="description">
809<p>Specifies the text or HTML notes for a link. </p><p>The <em>notes text</em> appears in a popup box when the user hovers their mouse over the link. If an <a href="#LINK_OVERLIBGRAPH">OVERLIBGRAPH</a> is specified too, then the text appears below the graph.</p><p>The map <a href="#GLOBAL_HTMLSTYLE">HTMLSTYLE</a> must be set to 'overlib' to enable any of the mouse-hover functionality.</p>
810</div>
811<div class="changes">
812<h3>Change History</h3>
813<dl>
814<dt>0.9</dt>
815<dd>Originally added NOTES.</dd>
816</dl>
817</div>
818</div>
819 <div class="referenceentry">
820<h2><a name="LINK_VIA">VIA</a></h2>
821<div class="definition">VIA <em class="meta">x-coord</em> <em class="meta">y-coord</em>
822</div>
823<div class="description">
824<p>Specify an additional point that a link must pass through.</p><p>A link normally goes in a straight line between the two nodes listed in the <a href="#LINK_NODES">NODES</a> configuration line.
825 If you need it to go around something else, or to seperate two parallel links so that the bandwidth labels
826 are all visible, you can make the link curve.</p><p>If you specify multiple VIA lines, then the link will pass through each in turn, in the order they are specified.</p>
827</div>
828<div class="changes">
829<h3>Change History</h3>
830<dl>
831<dt>0.8</dt>
832<dd>Originally added VIA.</dd>
833</dl>
834</div>
835</div>
836 <div class="referenceentry">
837<h2><a name="LINK_ARROWSTYLE">ARROWSTYLE</a></h2>
838<div class="definition">ARROWSTYLE <em class="meta">stylename</em>
839</div>
840<div class="definition">ARROWSTYLE <em class="meta">width</em> <em class="meta">length</em>
841</div>
842<div class="description">
843<p>Specifies the style of arrowhead used for drawing links.</p><p>The default is 'classic' which has a wide arrowhead. You can also choose 'compact' which gives narrower heads.</p><p>Finally, you can get finer control by adjusting the size yourself. The width and length of the head are in units of link-width.</p><p>Classic is equivalent to '4 2' and Compact is equivalent to '1 1'.</p>
844</div>
845<div class="changes">
846<h3>Change History</h3>
847<dl>
848<dt>0.8</dt>
849<dd>Added custom numeric form.</dd>
850<dt>0.7</dt>
851<dd>First added.</dd>
852</dl>
853</div>
854</div>
855 <div class="referenceentry">
856<h2><a name="LINK_SET">SET</a></h2>
857<div class="definition">SET <em class="meta">hintname</em> <em class="meta">hintvalue</em>
858</div>
859<div class="description">
860<p>Specifies a value for a <em>hint variable</em>.</p><p>Hint Variables allow the user to pass settings to the internals of Weathermap that
861 wouldn't normally need to be changed, or that aren't part of the core Weathermap application.
862 Examples are: small rendering changes, parameters for datasources plugins and similar.</p><p>Hint Variables are either Global for the map, or assigned to a specific link or node.</p><p>There is more about Hint Variables in the <a href="advanced.html">Advanced Topics</a> section.</p>
863</div>
864<div class="changes">
865<h3>Change History</h3>
866<dl>
867<dt>0.9</dt>
868<dd>Originally added SET.</dd>
869</dl>
870</div>
871</div>
872 
873 
874 <h1 id="s_scope_GLOBAL" class="configsection">Global Configuration Directives</h1>
875 <div class="referenceentry">
876<h2><a name="GLOBAL_BACKGROUND">BACKGROUND</a></h2>
877<div class="definition">BACKGROUND <em class="meta">imagefile</em>
878</div>
879<div class="description">
880<p>Specify an PNG, JPEG or GIF image file to be used as a background image.</p><p>Any <a href="#GLOBAL_WIDTH">WIDTH</a> and <a href="#GLOBAL_HEIGHT">HEIGHT</a> specifications will be ignored - the map will take the size of the background.</p>
881</div>
882<div class="changes">
883<h3>Change History</h3>
884<dl>
885<dt>0.9</dt>
886<dd>Added JPEG and GIF support for backgrounds.</dd>
887</dl>
888</div>
889</div>
890 <div class="referenceentry">
891<h2><a name="GLOBAL_WIDTH">WIDTH</a></h2>
892<div class="definition">WIDTH <em class="meta">map-width</em>
893</div>
894<div class="description">
895<p>Specifies the width of the map image in pixels.</p><p>If a <a href="#GLOBAL_BACKGROUND">BACKGROUND</a> is specified, and the imagefile is successfully loaded, then
896 any WIDTH specified is ignored.
897 If neither a <a href="#GLOBAL_BACKGROUND">BACKGROUND</a> or WIDTH is specified, then the default WIDTH is 800 pixels.</p>
898</div>
899</div>
900 <div class="referenceentry">
901<h2><a name="GLOBAL_HEIGHT">HEIGHT</a></h2>
902<div class="definition">WIDTH <em class="meta">map-height</em>
903</div>
904<div class="description">
905<p>Specifies the height of the map image in pixels.</p><p>If a <a href="#GLOBAL_BACKGROUND">BACKGROUND</a> is specified, and the imagefile is successfully loaded, then
906 any HEIGHT specified is ignored.
907 If neither a <a href="#GLOBAL_BACKGROUND">BACKGROUND</a> or HEIGHT is specified, then the default HEIGHT is 600 pixels.</p>
908</div>
909</div>
910 <div class="referenceentry">
911<h2><a name="GLOBAL_HTMLOUTPUTFILE">HTMLOUTPUTFILE</a></h2>
912<div class="definition">HTMLOUTPUTFILE <em class="meta">htmlfile</em>
913</div>
914<div class="description">
915<p>This specifies the name of the HTML file that will be generated. </p><p>The equivalent command-line option takes precedence over this configuration line, if both are used. If you are generating maps using the Cacti plugin, then this directive is ignored.</p>
916</div>
917<div class="changes">
918<h3>Change History</h3>
919<dl>
920<dt>0.7</dt>
921<dd>Added HTMLOUTPUTFILE.</dd>
922</dl>
923</div>
924</div>
925 <div class="referenceentry">
926<h2><a name="GLOBAL_IMAGEOUTPUTFILE">IMAGEOUTPUTFILE</a></h2>
927<div class="definition">IMAGEOUTPUTFILE <em class="meta">imagefile</em>
928</div>
929<div class="description">
930<p>This specifies the name of the PNG, JPEG or GIF file that will be generated. The format chosen is based on the file-extension. </p><p>The equivalent command-line option takes precedence over this configuration line, if
931 both are used. </p><p>If you are generating maps using the Cacti plugin, then this directive is ignored.
932You can set the output format in the Cacti Settings page.</p>
933</div>
934<div class="changes">
935<h3>Change History</h3>
936<dl>
937<dt>0.9</dt>
938<dd>Added JPEG and GIF support.</dd>
939<dt>0.7</dt>
940<dd>Added IMAGEOUTPUTFILE.</dd>
941</dl>
942</div>
943</div>
944 <div class="referenceentry">
945<h2><a name="GLOBAL_FONTDEFINE">FONTDEFINE</a></h2>
946<div class="definition">FONTDEFINE <em class="meta">fontnumber</em> <em class="meta">gdfontfile</em>
947</div>
948<div class="definition">FONTDEFINE <em class="meta">fontnumber</em> <em class="meta">ttffontfile</em> <em class="meta">fontsize</em>
949</div>
950<div class="description">
951<p>Defines a custom font to be used for text within the map.</p><p>By default, the GD library used by Weathermap has 5 fonts, numbered 1-5. FONTDEFINE allows you to
952 define new font numbers, and link them to fonts in two other formats.</p><p>The first format is 'GD fonts', which are a bitmapped format used by GD alone. They are not scalable, and are also
953 platform-specific (they use a different byte-order depending on the host). You should specify the full filename including any extensions.</p><p>The second format is TrueType fonts, which are scalable, standard and generally a lot nicer! This time, you need to specify the
954 size that the font should be rendered at. The size is in pixels. You can load the same font into multiple fontnumbers with
955 different sizes to use in different parts of a map.</p><p>The freetype library used in PHP makes a somewhat complex set of rules for where it will search for truetype fonts. The two easiest options are:
956 <ul><li>Use the full absolute path to your .ttf file</li>
957 <li>Keep your .ttf files in the Weathermap directory, and use the first part of the filename only, with no '.ttf' on the end.</li></ul>
958 The full set of rules is <a href="http://www.boutell.com/gd/manual2.0.33.html#gdImageStringFT">available here</a></p><p>Regardless of the format, the newly defined font can be used anywhere that you'd normally use a font number (for example, <a href="#LINK_BWFONT">BWFONT</a> or KEYFONT).
959 </p>
960</div>
961<div class="examples">
962<h3>Examples</h3>
963<div class="example">
964<h5>Defining a new Truetype font, with the font file in the weathermap directory</h5>
965<pre>FONTDEFINE 10 VeraBd 16</pre>
966</div>
967</div>
968<div class="changes">
969<h3>Change History</h3>
970<dl>
971<dt>0.8</dt>
972<dd>First added FONTDEFINE</dd>
973</dl>
974</div>
975</div>
976 <div class="referenceentry">
977<h2><a name="GLOBAL_FONT">*FONT</a></h2>
978<div class="definition">TITLEFONT <em class="meta">fontnumber</em>
979</div>
980<div class="definition">KEYFONT <em class="meta">fontnumber</em>
981</div>
982<div class="definition">TIMEFONT <em class="meta">fontnumber</em>
983</div>
984<div class="description">
985<p>Specify the fonts used for various text. </p><p>Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using the <a href="#GLOBAL_FONTDEFINE">FONTDEFINE</a> directive.</p><p><img src="../images/font-sizes.png"></img>The built-in GD fonts.</p>
986</div>
987<div class="changes">
988<h3>Change History</h3>
989<dl>
990<dt>0.8</dt>
991<dd>Originally added TIMEFONT.</dd>
992<dt>0.7</dt>
993<dd>Originally added TIMEFONT.</dd>
994<dt>0.6</dt>
995<dd>Originally added KEYFONT.</dd>
996</dl>
997</div>
998</div>
999 <div class="referenceentry">
1000<h2><a name="GLOBAL_COLORS">*COLOR</a></h2>
1001<div class="definition">BGCOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
1002</div>
1003<div class="definition">TIMECOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
1004</div>
1005<div class="definition">TITLECOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
1006</div>
1007<div class="definition">KEYTEXTCOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
1008</div>
1009<div class="definition">KEYOUTLINECOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
1010</div>
1011<div class="definition">KEYBGCOLOR <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
1012</div>
1013<div class="description">
1014<p>Specify the colours used for drawing the global elements of the map.</p><p>red, green and blue are numbers from 0 to 255.</p><p>LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR have an additional option - 'none' - which stops that element of the <a href="#NODE_LABEL">LABEL</a> being drawn. LABELFONTSHADOWCOLOR defaults to 'none'.</p>
1015</div>
1016<div class="changes">
1017<h3>Change History</h3>
1018<dl>
1019<dt>0.8</dt>
1020<dd>Added TIMECOLOR, TITLECOLOR, KEYTEXTCOLOR, KEYOUTLINECOLOR and KEYBGCOLOR.</dd>
1021<dt>0.7</dt>
1022<dd>Added BGCOLOR.</dd>
1023</dl>
1024</div>
1025</div>
1026 <div class="referenceentry">
1027<h2><a name="GLOBAL_TIMEPOS">TIMEPOS</a></h2>
1028<div class="definition">TIMEPOS <em class="meta">x-pos</em> <em class="meta">y-pos</em>
1029</div>
1030<div class="definition">TIMEPOS <em class="meta">x-pos</em> <em class="meta">y-pos</em> <em class="meta">formatstring</em>
1031</div>
1032<div class="description">
1033<p>Specifies where to draw the timestamp on the map.</p><p>If no TIMEPOS line is given, then the timestamp is drawn in the top-right corner. To hide it completely, set y to be <nobr>-200</nobr> or so.</p><p>You can optionally specify an additional parameter to change the text of the timestamp. This text can
1034 contain special tokens which are substituted with parts of the current time. The default timestamp
1035 text is <nobr><tt>Created: %b %d %Y %H:%M:%S</tt></nobr>. The tokens used are those accepted by the PHP strftime
1036 function. For a full list see the <a href="http://www.php.net/manual/en/function.strftime.php">PHP manual page</a>.</p>
1037</div>
1038<div class="changes">
1039<h3>Change History</h3>
1040<dl>
1041<dt>0.6</dt>
1042<dd>Added ability to change text.</dd>
1043<dt>0.5</dt>
1044<dd>Originally added TIMEPOS</dd>
1045</dl>
1046</div>
1047</div>
1048 <div class="referenceentry">
1049<h2><a name="GLOBAL_TITLE">TITLE</a></h2>
1050<div class="definition">TITLEPOS <em class="meta">titlestring</em>
1051</div>
1052<div class="description">
1053<p>Specifies the title text. </p><p>The TITLE is shown in file-selectors for both the editor and the Cacti plugin. If you'd like the title to be shown on the map too, then add <a href="#GLOBAL_TITLEPOS">TITLEPOS</a> line also.</p>
1054</div>
1055<div class="changes">
1056<h3>Change History</h3>
1057<dl>
1058<dt>0.8</dt>
1059<dd>Originally added TITLEPOS.</dd>
1060</dl>
1061</div>
1062</div>
1063 <div class="referenceentry">
1064<h2><a name="GLOBAL_TITLEPOS">TITLEPOS</a></h2>
1065<div class="definition">TITLEPOS <em class="meta">x-pos</em> <em class="meta">y-pos</em>
1066</div>
1067<div class="definition">TITLEPOS <em class="meta">x-pos</em> <em class="meta">y-pos</em> <em class="meta">headingstring</em>
1068</div>
1069<div class="description">
1070<p>Specifies the position of the title text. </p><p>If no TITLEPOS line is given, then no title is drawn. You can optionally specify an additional parameter, to change the title. Any text after the second coordinate is taken as a new TITLE.</p>
1071</div>
1072<div class="changes">
1073<h3>Change History</h3>
1074<dl>
1075<dt>0.8</dt>
1076<dd>Originally added TITLEPOS.</dd>
1077</dl>
1078</div>
1079</div>
1080 <div class="referenceentry">
1081<h2><a name="GLOBAL_KILO">KILO</a></h2>
1082<div class="definition">KILO <em class="meta">number</em>
1083</div>
1084<div class="description">
1085<p>Specifies base value for kilo, mega and giga abbreviations. </p><p>Both <a href="#LINK_BANDWIDTH">BANDWIDTH</a> and <a href="#LINK_BWLABEL">BWLABEL</a> can use K,M,G,T as abbreviations for thousands, millions and so on. You can define what the multiple used is. The default is 1000.</p>
1086</div>
1087<div class="changes">
1088<h3>Change History</h3>
1089<dl>
1090<dt>0.4</dt>
1091<dd>Originally added KILO.</dd>
1092</dl>
1093</div>
1094</div>
1095 <div class="referenceentry">
1096<h2><a name="GLOBAL_HTMLSTYLE">HTMLSTYLE</a></h2>
1097<div class="definition">HTMLSTYLE <em class="meta">formatname</em>
1098</div>
1099<div class="description">
1100<p>Specifies the HTML output style. </p><p>When HTML output is enabled, there are two variations, which you can choose between. 'static' is a basic HTML page with client-side imagemap, but no 'pop up' graphs. 'overlib' adds the use of the OverLib library to the page, so that pop up graphs can work, too. This requires Javascript, which is why 'static' is the default.</p>
1101</div>
1102</div>
1103 <div class="referenceentry">
1104<h2><a name="GLOBAL_SCALE">SCALE</a></h2>
1105<div class="definition">SCALE <em class="meta">min</em> <em class="meta">max</em> <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
1106</div>
1107<div class="definition">SCALE <em class="meta">scalename</em> <em class="meta">min</em> <em class="meta">max</em> <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em>
1108</div>
1109<div class="definition">SCALE <em class="meta">min</em> <em class="meta">max</em> <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em> <em class="meta">red2</em> <em class="meta">green2</em> <em class="meta">blue2</em>
1110</div>
1111<div class="definition">SCALE <em class="meta">scalename</em> <em class="meta">min</em> <em class="meta">max</em> <em class="meta">red</em> <em class="meta">green</em> <em class="meta">blue</em> <em class="meta">red2</em> <em class="meta">green2</em> <em class="meta">blue2</em>
1112</div>
1113<div class="description">
1114<p>Defines one 'span' within the link colour-coding table.</p><p>SCALE is used to specify how LINKs are colour-coded according to their percent usage.
1115 If the percentage usage falls between min and max then the colour specified by red, green and blue is used to colour the link.
1116 Colour values are between 0 and 255. Percentages are between 0 and 100, obviously.</p><p>If you specify <i>two</i> colours on the line (the third and fourth forms above), then the colour chosen for the link will be calculated as
1117 a proportion between the two colours. You can avoid specifying many SCALE lines this way.</p><p>Without a <i>scalename</i>, the SCALE line will add a definition to the scale named 'DEFAULT'. If you define any other named scales, you can then use the <a href="#LINK_USESCALE">USESCALE</a> directive to specify that a particular <a href="#NODE_NODE">NODE</a> or <a href="#LINK_LINK">LINK</a> use your new scale.</p><p>If you don't add <i>any</i> SCALE lines to a configuration file, then a default set is added for you, but as soon as you add one, you'll need to make enough to cover the whole 0-100 range to get nice colours.
1118 Any percentage not matched by SCALE rules is rendered in grey.</p><p>You can specify a colour for an <em>exact</em> percentage (e.g. zero) by using that value for both the min and max values. The scale lines are sorted by min then max, and scanned from top to bottom. The first match wins.</p>
1119</div>
1120<div class="examples">
1121<h3>Examples</h3>
1122<div class="example">
1123<h5>Setting up a (very simple) colour scale. Colours run smoothly from green to red.</h5>
1124<pre>SCALE 0 100 0 255 0 255 0 0</pre>
1125</div>
1126<div class="example">
1127<h5>The default scale set</h5>
1128<pre>SCALE 1 10 140 0 255
1129SCALE 10 25 32 32 255
1130SCALE 25 40 0 192 255
1131SCALE 40 55 0 240 0
1132SCALE 55 70 240 240 0
1133SCALE 70 85 255 192 0
1134SCALE 85 100 255 0 0</pre>
1135</div>
1136</div>
1137<div class="changes">
1138<h3>Change History</h3>
1139<dl>
1140<dt>0.9</dt>
1141<dd>Added named scales.</dd>
1142<dt>0.9</dt>
1143<dd>Added considtently sorted scales.</dd>
1144<dt>0.8</dt>
1145<dd>Added interpolated scale colours.</dd>
1146<dt>0.5</dt>
1147<dd>Changed to allow min and max to be fractional.</dd>
1148</dl>
1149</div>
1150</div>
1151 <div class="referenceentry">
1152<h2><a name="GLOBAL_KEYPOS">KEYPOS</a></h2>
1153<div class="definition">KEYPOS <em class="meta">x-pos</em> <em class="meta">y-pos</em>
1154</div>
1155<div class="definition">KEYPOS <em class="meta">x-pos</em> <em class="meta">y-pos</em> <em class="meta">headingstring</em>
1156</div>
1157<div class="definition">KEYPOS <em class="meta">scalename</em> <em class="meta">x-pos</em> <em class="meta">y-pos</em>
1158</div>
1159<div class="definition">KEYPOS <em class="meta">scalename</em> <em class="meta">x-pos</em> <em class="meta">y-pos</em> <em class="meta">headingstring</em>
1160</div>
1161<div class="description">
1162<p>Specifies the position of the key, or legend, that shows what each colour-range in a scale means. If a scalename is not given,
1163 then "DEFAULT" is assumed.
1164 If no KEYPOS line is given for a scale, then no legend is drawn - handy if you have many many colour ranges.</p><p>You can optionally specify an additional parameter, to change the heading above the colours in
1165 the key. This can be used to change the language of the map, for example. If a scalename is given, then you <em>must also specify a title</em> - there is no useful default title for non-DEFAULT scales.</p>
1166</div>
1167<div class="changes">
1168<h3>Change History</h3>
1169<dl>
1170<dt>0.9</dt>
1171<dd>Added support for multiple SCALEs.</dd>
1172<dt>0.6</dt>
1173<dd>Added ability to change text.</dd>
1174</dl>
1175</div>
1176</div>
1177 <div class="referenceentry">
1178<h2><a name="GLOBAL_KEYSTYLE">KEYSTYLE</a></h2>
1179<div class="definition">KEYSTYLE <em class="meta">stylename</em>
1180</div>
1181<div class="definition">KEYSTYLE <em class="meta">stylename</em> <em class="meta">size</em>
1182</div>
1183<div class="definition">KEYSTYLE <em class="meta">scalename</em> <em class="meta">stylename</em>
1184</div>
1185<div class="definition">KEYSTYLE <em class="meta">scalename</em> <em class="meta">stylename</em> <em class="meta">size</em>
1186</div>
1187<div class="description">
1188<p>Specifies the style of the key, or legend, that shows what each colour-range means. If a scalename is not given,
1189 then "DEFAULT" is assumed. Valid stylenames are: 'classic', 'horizontal' and 'vertical'.</p><p>Classic has a line for each <a href="#GLOBAL_SCALE">SCALE</a> range defined. 'vertical' and 'horizontal' are fixed-size, showing a
1190 continuous block from 0-100% usage, which is much more useful when gradient SCALEs are used, or when you have
1191 a large number of <a href="#GLOBAL_SCALE">SCALE</a> lines in one scale.</p><p>
1192 For 'horizontal' and 'vertical' styles, you can optionally add an additional parameter, which specifies the longer dimension of the legend in pixels. That is, for a horizontal legend, it specifies the width. The other dimension is calculated from the size of the font used (see KEYFONT).
1193 </p><p><img src="../images/keystyle-classic.png"></img>Classic Style</p><p><img src="../images/keystyle-horizontal.png"></img>Horizontal Style</p><p><img src="../images/keystyle-vertical.png"></img>Vertical Style</p>
1194</div>
1195<div class="changes">
1196<h3>Change History</h3>
1197<dl>
1198<dt>0.9</dt>
1199<dd>Added support for multiple key styles.</dd>
1200</dl>
1201</div>
1202</div>
1203 <div class="referenceentry">
1204<h2><a name="GLOBAL_SET">SET</a></h2>
1205<div class="definition">SET <em class="meta">hintname</em> <em class="meta">hintvalue</em>
1206</div>
1207<div class="description">
1208<p>Specifies a value for a <em>hint variable</em>.</p><p>Hint Variables allow the user to pass settings to the internals of Weathermap that
1209 wouldn't normally need to be changed, or that aren't part of the core Weathermap application.
1210 Examples are: small rendering changes, parameters for datasources plugins and similar.</p><p>Hint Variables are either Global for the map, or assigned to a specific link or node.</p><p>There is more about Hint Variables in the <a href="advanced.html">Advanced Topics</a> section.</p>
1211</div>
1212<div class="examples">
1213<h3>Examples</h3>
1214<div class="example">
1215<h5>Enabling 'bulging link mode' in the link-rendering code.</h5>
1216<pre>SET link_bulge 1</pre>
1217</div>
1218</div>
1219<div class="changes">
1220<h3>Change History</h3>
1221<dl>
1222<dt>0.9</dt>
1223<dd>Originally added SET.</dd>
1224</dl>
1225</div>
1226</div>
1227 
1228 
1229</div></body>
1230</html>

Powered by WebSVN 2.2.1