WebSVN - weathermap - Blame - Rev 116

<div class="license"><p>PHP Weathermap is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.</p>

53

54

<p>PHP Weathermap is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.</p>

55

56

<p>You should have received a copy of the GNU General Public License along with PHP Weathermap; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA</p>

57

<p>Parts of this software distribution are by other authors. Please see the README file for attribution and license details.</p>

</div>

<div id="enclose">

<div class="card-right" style="width: 290px;">

62

<h2 class="card-title">PHP Weathermap</h2>

63

<p class="card-photo"><img src="../images/weathermap-mini.png" /></p>

64

      <p class="card-desc">Sample output from php-weathermap, using data collected by Cacti and MRTG.<br /><a href="../images/weathermap-example.png">Larger version</a></p>

65

</div>

66

67

<h2><a name="introduction" id="introduction">Introduction</a></h2><p>PHP Weathermap is one of <a href=

68

"#alternatives">many</a> implementations of the same basic

69

idea - take data from your network devices and use it to

70

provide a single-page overview of the current state of

71

network, like the one to the right. It complements a tool

72

like <a href="http://www.mrtg.org">MRTG</a>, <a href=

73

"http://cricket.sourceforge.net/">Cricket</a> or <a href=

74

"http://www.cacti.net/">Cacti</a>, that provide in-depth

75

graphing, and historical information, and can use data from

76

those systems to produce it's maps. In fact, it

77

<i>requires</i> some other data-collection source, as it does

78

no device-polling on it's own.</p>

79

80

<p>This particular version is written in PHP, and it can read statistics data from

81

MRTG-produced HTML files, plain tab-seperated text files and from RRD files, such as those

82

produced by newer MRTG setups, Cacti (my favourite) or

83

another tool. It can also generate HTML 'holder' files for

84

the map images, which can include 'DHTML' overlays of

85

historical data and links into your other

86

      monitoring/statistics system. It also has a interactive map editor, so you can largely avoid the text configuration files, if you prefer.</p>

87

<p>To get a better idea of what is possible, see the <a href="#example">example map</a> that comes with this manual.</p>

88

<h3>Requirements</h3>

89

<p>Based on lessons learned with the perl version, this one

90

has a very restricted set of dependencies - you'll need a

91

recentish PHP (>4.3.0 I think) including the CLI version

92

      and the 'gd' extension with PNG, TrueColour and FreeType support. You will need command-line (<i>aka shell/ssh/telnet</i>) access to

93

the server which will host the maps.

94

<p>To read RRD files, you'll need the rrdtool command-line program. </p>

95

<p>Apart from the

96

gd module, these requirements are the same as for Cacti,

97

which is the most-tested partner stats system.</p>

98

    <p>To use the Cacti plugin, you will need a recent version of Cacti, and the matching Cacti Plugin Architecture, from <a href="http://cactiusers.org/">Jimmy Conner's Cactiusers.org</a>.</p>

99

100

<h2><a name="support">Support</a></h2>

101

102

<p>There are two mailing lists for php-weathermap:<dl>

103

<dt>php-weathermap@thingy.com</dt>

104

                <dd>General discussion of weathermap-related issues, bug reports and development. Fairly low traffic currently. Typically contains discussion of test or beta versions too, when they are circulating.</dd>

105

<dt>php-weathermap-announce@thingy.com</dt>

106

<dd>Very low volume list for new version announcements and other similarly rare events!</dd>

107

</dl>

108

                More information about how to subscribe to the mailing lists is <a href="http://www.network-weathermap.com/support/mailinglists">at the website</a>.</p>

109

                <p>Also, if you have an RSS reader, you can subscribe to the <a href="http://www.network-weathermap.com/appcast.rss">'appcast' feed for php-weathermap</a> which contains roughly the same content as the -announce mailing list.</p>

110

111

<h2><a name="installation" id="installation">Installation Guide</a></h2>

112

113

<p>How to install Weathermap depends on how you intend to use it:

114

<ul>

115

<li><a href="install-cacti-editor.html">As a Cacti Plugin, with the web-based editor</a></li>

116

<li><a href="install-cacti.html">As a Cacti Plugin</a></li>

117

<li><a href="install-cli-editor.html">As a standalone command-line tool, with the web-based editor</a></li>

118

<li><a href="install-cli.html">As a standalone command-line tool</a></li>

119

</ul>

120

</p>

121

<h2><a name="running" id="running">Running Weathermap</a></h2>

122

123

<p>There are two ways to run Weathermap.</p><p>If you are using the Cacti plugin, then it will be run

124

for you as part of the Cacti poller cycle. You don't need to do anything special apart from add

125

your map configuration files, as explained in the <a href="cacti-plugin.html">Cacti plugin</a> notes.</p>

126

<p>If you are using weathermap as a standalone tool, you do it using the command line version. See the

127

          <a href="cli-reference.html">CLI Reference</a> for all possible options, but a good starting point is something like:</p>

128

<div class="shell">

129

<pre>php ./weathermap --config myconfigfile.conf --output mymap.png --htmloutput mymap.html</pre>

130

</div>

131

        <p>You can skip the htmloutput and output parts if you have HTMLOUTPUTFILE and IMAGEOUTPUTFILE lines in your configuration file.</p>

132

        <p>Usually, people want to run weathermap regularly (it's not a requirement though!). To do that, you need to create a 'cron job' or 'Task Scheduler Task' to

133

        run a command-line like the one above on a regular basis. You probably already have a similar task setup to collect the data

134

that weathermap is reading. This is the same kind of thing.</p>

135

136

<h2><a name="basics" id="basics">Basics</a></h2>

137

138

<p>The weathermap is defined by a plain-text file

139

which by default is called weathermap.conf (you can have many

140

configurations, and choose between them with command-line switches).

141

By default, weathermap will read that file, and produce a

142

single PNG file called weathermap.png.</p>

143

144

<p>The configuration file has three sections: Node definitions, Link

145

definitions and Global settings. There is an <a href=

146

"#example">example of a complete file</a> at the bottom of

this page.</p>

<h3>Nodes</h3>

<div class="shell">

<pre>

NODE nycore1

LABEL NYC

POSITION 30 30

</pre><b>A simple NODE</b>

157

</div><p>Nodes are the points on your network that are joined

158

together. Depending on the detail in the map, they might be

159

cities or individual routers. In a basic map, a node has 3

160

pieces of information - an internal name which must be unique

161

to this node, it's position from the top-left corner of the

162

map, in pixels, and optionally a label, which will appear

163

within the box marking the position of the node. Nodes

164

without a label don't appear on the map at all, but can still

165

be used as an endpoint for a link.</p>

<h3>Links</h3>

<div class="shell">

170

<pre>

171

LINK backbone1

172

NODES nycore1 paix1

173

BANDWIDTH 3M

174

TARGET ../my-mrtg-data/backbone1.html

175

</pre><b>A simple LINK</b>

176

</div><p>Links are the network routes between the Nodes.

177

Typically they are actual network links, but they can be

178

anything that you can get numbers for that make sense on map.</p>

179

180

<p>An absolute minimal link has 3 pieces of information too.

181

They are the unique internal name for this link, and unique

182

node names for the two endpoints. To show current usage on

183

the map, you'll need to give two more pieces: the maximum

184

bandwidth on the link, and a way to get the current

185

throughput. The BANDWIDTH is measured in bits/sec, and can

186

include the usual K,M,G and T suffixes for large values. The

187

data-source is given in the TARGET line, and can be one of

188

189

<ul>

190

<li>MRTG-generated HTML file (which contains a special HTML

191

comment at the bottom with the current values)</li>

192

<li>Cacti-generated RRD file</li>

193

<li>Some other RRD file, provided you know how it is

194

structured internally.</li>

195

</ul> One important note: the order of the nodes in the NODES

196

line is significant. The first node is considered to be the

197

'local' one when thinking about the data source in the

198

TARGET. 'out' will be 'out' relative to the first node. If

199

you find the map shows all your data flowing in the wrong

200

direction, try swapping the order of the nodes here.</p>

201

202

<h3>Global Settings</h3><p>These settings usually live at the

203

top of the text file, and specify basic information about the

204

map. The minimum settings are:</p>

205

206

<div class="shell">

<pre>

WIDTH 800

HEIGHT 600

</pre>

</div><p>This is specifies the size of the map in pixels. If you

212

want something a bit fancier than a plain white background,

213

you can make up a background image to use in PNG format. In

214

that case, the map will be the size of the background image:</p>

215

216

<div class="shell">

217

<tt>BACKGROUND western-europe.png</tt>

218

</div><p>There are also settings to set which fonts and colours are used for various

219

elements of the map, where to position the colour-legend (if at all), what files

220

          to output, and more advanced layout techniques. The full list is in the <a href="config-reference.html">Config Reference</a>.</p>

221

222

223

<h2><a name="example" id="example">A Sample

224

Config</a></h2>Here's a sample configuration, and <a href=

225

"../example/example.html">here's what it produces (modified to work a little better)</a>. The data

226

isn't live in the output, but it gives you an idea of what

227

can be done. The initial background image is <a href=

228

      "../example/background.png">here</a>. The configuration file is also in the docs directory of the distribution, should you want it.

229

230

<div class="shell">

231

<pre>

232

# some initial comments...

233

#

234

# This sample configuration file demonstrates most of the basic features of

235

# PHP Weathermap, along with some of the cosmetic and layout changes possible

236

#

237

#

238

BACKGROUND background.png

239

HTMLOUTPUTFILE example.html

240

IMAGEOUTPUTFILE example.png

241

TITLE Network Overview

HTMLSTYLE overlib

KEYPOS 10 400

# define some new TrueType fonts - built-in ones go from 1 to 5, so start high

246

FONTDEFINE 100 VeraIt 8

247

FONTDEFINE 101 Vera 12

248

FONTDEFINE 102 Vera 9

KEYFONT 102

LINK DEFAULT

BANDWIDTH 100M

BWLABEL bits

BWFONT 100

OVERLIBWIDTH 395

OVERLIBHEIGHT 153

WIDTH 4

NODE DEFAULT

LABELFONT 101

NODE transit

POSITION 400 180

LABEL TRANSIT

# a little splash of background colour for these nodes

NODE isp1

POSITION 250 100

LABEL ISP1

INFOURL http://www.isp1.com/support/lookingglass.html

272

LABELBGCOLOR 255 224 224

NODE isp2

POSITION 550 100

LABEL ISP2

INFOURL http://www.isp2.net/portal/

278

LABELBGCOLOR 224 255 224

NODE core

POSITION 400 300

LABEL core

INFOURL https://core.mynet.net/admin/

NODE customer1

LABEL xy.com

POSITION 150 370

NODE customer2

LABEL ww.co.uk

POSITION 250 450

NODE infra

LABEL INFRASTRUCTURE

295

POSITION 450 450

296

297

# this node has an icon, and so we push the label to the South edge of it, so it

298

# can still be read

NODE sync

LABEL Sync

ICON my_router.png

LABELOFFSET S

LABELFONT 2

POSITION 550 370

# the icon is taken from a Nagios icon pack:

306

#   http://www.nagiosexchange.org/Image_Packs.75.0.html?&amp;tx_netnagext_pi1[p_view]=110&amp;tx_netnagext_pi1[page]=10%3A10

NODE site1

LABEL site1

POSITION 700 220

NODE site2

LABEL site2

POSITION 750 420

LINK sync-core

NODES sync core

TARGET data/sync_traffic_in_259.rrd

319

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=256&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=300

320

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=256

321

#

322

# Site1 has two E1s, so we use NODE-offsets to allow them to run parallel

#

LINK sync-site1a

NODES sync:N site1:W

327

WIDTH 3

328

TARGET data/sync_traffic_in_257.rrd

329

BANDWIDTH 2M

330

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=254&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=

331

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=126

332

333

LINK sync-site1b

334

NODES sync:E site1:SE

335

WIDTH 3

336

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=255&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=

337

TARGET data/sync_traffic_in_258.rrd

338

BANDWIDTH 2M

339

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=56

340

341

#

342

# site2 also has two links, but this time we use the VIA to curve the links

#

LINK sync-site2a

NODES sync site2

WIDTH 3

VIA 650 380

TARGET data/sync_traffic_in_251.rrd

349

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=248&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=300

350

BANDWIDTH 1M

351

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=252

LINK sync-site2b

NODES sync site2

WIDTH 3

VIA 650 420

TARGET data/sync_traffic_in_252.rrd

358

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=228&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=300

359

BANDWIDTH 1M

360

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=561

361

362

#

363

# ISP 1 has a several links, again, but they prefer to see one arrow, and the aggregate bandwidth

364

# so we use multiple TARGETs on one line, here, to sum the data

LINK transit-isp1

NODES transit isp1

TARGET data/trans1_traffic_in_352.rrd data/trans1_traffic_in_378.rrd data/trans1_traffic_in_420.rrd

369

BANDWIDTH 10M

370

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=355&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=

371

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=633

LINK transit-isp2

NODES transit isp2

TARGET data/trans1_traffic_in_438.rrd

376

BANDWIDTH 34M

377

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=433&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=300

378

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=265

LINK core-transit

NODES transit core

TARGET data/trans1_traffic_in_350.rrd

383

ARROWSTYLE compact

384

WIDTH 4

385

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=347&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=300

386

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=122

387

388

LINK cust1-core

389

NODES customer1 core

390

TARGET data/extreme_traffic_in_299.rrd

391

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=296&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=300

392

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=237

393

394

LINK cust2-core

395

NODES customer2 core

396

TARGET data/extreme_traffic_in_286.rrd

397

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=283&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=300

398

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=222

LINK infra-core

NODES infra core

TARGET data/extreme_traffic_in_294.rrd

403

        OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=291&amp;rra_id=0&amp;graph_nolegend=true&amp;graph_height=100&amp;graph_width=300

404

INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=228

405

406

</pre><b>A Sample Configuration File</b>

</div>

<h3><a name="alternatives" id="alternatives">Other

411

Weathermaps</a></h3><p>Obviously, you can't please everyone, so

412

here's a list of other weathermap or network visualisation

413

implementations that I know of. Some are open source, some

414

aren't. All of them have some subtle or interesting wrinkle

415

that the others don't. <a href="mailto:howie@thingy.com">Let

416

me know if you know of any others</a>.

417

418

<dl>

419

        <dt><a href="http://netmon.grnet.gr/weathermap/" class="ext">GRNET perl version</a> by Panagiotis Christias.</dt>

420

421

<dd>Support only for MRTG, or anything else that can

422

produce similar HTML files.</dd>

423

424

<dt><a href=

425

"http://wotsit.thingy.com/haj/cacti-weathermap.html">My own

426

perl weathermap</a></dt>

427

428

<dd>A forked/modified version of the GRNET one above, adds

429

imagemaps, DHTML, RRD-reading and a number of smaller

430

tweaks. No longer updated.</dd>

431

432

<dt><a class="ext" href=

433

"http://weathermap4rrd.tropicalex.net/">Weathermap4RRD</a></dt>

434

435

<dd>Another fork of the GRNET perl map. Also with (only?)

436

RRD support, and various graphical enhancements.

437

<i>Also</i> now with a PHP version!</dd>

438

439

<dt><a href=

440

"http://loadrunner.uits.iu.edu/weathermaps/abilene/" class=

441

"ext">Indiana University Abilene Weathermap</a></dt>

442

443

<dd>Another perl (i think) script, but with a rather

444

different map design. Can show error rates on links,

too.</dd>

<dt><a href=

"http://noc.asti.dost.gov.ph/docus/tools/how-to/weathermap.php"

449

class="ext">PREGINET Network Weathermap</a></dt>

450

451

<dd>Another perl open source map. Works by reading MRTG

452

logs, as far as I can tell.</dd>

453

454

<dt><a href="http://www.it.teithe.gr/~v13/">V13 netmap</a>

455

(click 'netmap' in the left hand panel - I love

456

frames)</dt>

457

458

<dd>Similar output to this program, but does all it's own

459

SNMP data collection.</dd>

</dl>

</p>

</div>

</div>

</body>

</html>