# PHP Weathermap v0.97a

#### Copyright © 2005-2010 Howard Jones, `howie@thingy.com`. (Website)

## Changes For This Version (0.97 to 0.97a)

Lots of bugs appeared the day after 0.97 was released! There are a few small features added, but mainly this is bugfixes.

### Fixes

- Incorrect action URL in 'map selector' combo box for Cacti users.
- cacti_graph_id set to 0 instead of ID, by rrd/poller_output and dsstats plugins (thanks sh0x)
- 'classic' legend drew 'hidden' colour values for things like key background colour. (thanks jmayniac)
- PHP 5.3 deprecated code in HTML_Imagemap.class.php
- 'Show Only First' option ignored in Cacti (thanks inko_nick)
- Editor deals with overlapping nodes on different ZORDERS properly.
- "property of non-object in editor.php line 466" while editing map properties (thanks to iNeo)
- no-data option on command-line didn't work
- Clone Node was broken in 0.97
- Maps with per-user permissions show up multiple times in map selector
- Removed incorrect warning about imagefilter and USEICONSCALE.
- string escaping bug with editor and direct config changes (thanks uhtred)
- --imageuri was ignored on command-line (thanks Marcus Stögbauer)
- links with targets containing spaces are broken by the editor (thanks Andreas Braun)
- deprecated jQuery function call in cacti-pick.php (thanks again Andreas Braun)

### Changes

- Group sorting is a bit more logical and the presentation nicer.
- cacti-integrate.php uses getopt to take more command-line params
- Updated jQuery to latest
- Number formatting will pick 1G over 1000M (and similar) (thanks cerbum)
- The editor is disabled by default - see top of editor.php (and install guide)

### New Features

- LINK WIDTH accepts decimals
- cacti-integrate.php can generate DSStats TARGETs too
- Simple VIA editing in editor (thanks to Zdolny)
- SCALE can accept G,M,K,T,m,u,n suffixes (for absolute scales)

## Changes For This Version (0.96a to 0.97)

### Fixes

- RRD Aggregation regexp was failing (thanks to shd)
- Scale numerals honour locale (thanks again, shd)
- THold plugin check failed with Thold 0.4.1 (PA 2.x, actually)
- Uninitialized variable in ReadData when plugin is disabled
- Zero-length link check didn't include offsets (thanks Ryan Botoluzzi)
- Cacti-pick should get right rra path for packagers that move the rra directory (e.g. Ubuntu, Debian *again*)
- DS plugins that return one value and a null should work properly
- "Strange" characters (e.g. /) in NODE and LINK names broke the imagemap.
- Map Style settings in editor were broken after internal defaults changes
- Imagemap no longer contains areas with no href defined
- SPLITPOS was ignored with VIASTYLE angled (thanks to uhtred)
- 'AICONOUTLINECOLOR none' is actually valid now (thanks to mgb & Leathon)
- readdir() loop never stops, on some systems (thanks to jerebernard)
- bad regexp in the MRTG DS plugin (thanks to Matt McMahon)
- 0.96 had a new 'time' DS plugin - now documented!
- NCFPC only complains about missing scale lines on NODEs for the variable that is in use.

### New Features

- USEICONSCALE no longer has special dependencies - and the colours are nicer too.
- Option of a dropdown selector to navigate between maps (in full-size view)
- Maps can be organised into groups in Cacti plugin. These appear
as tabs in the UI for viewing maps.
- Extra variables can be defined per-group, so all maps in a group can have similar settings (e.g. a "24hr average" tab).
- INCLUDE keyword to include a file of common definitions (based on work by BorisL)
(NOTE: this can confuse the editor sometimes - see the manual page for INCLUDE)
- Warning for maps that contain OVERLIBGRAPH but not 'HTMLSTYLE overlib'
- Warning for use of TEMPLATE not as the first line of an object (overwrites settings otherwise)
- SCALE will accept values below 0, and also above 100
- USESCALE has two new options: absolute and percent, which allows you to have a SCALE of absolute values
- New datasource plugin to support statistics from TheWitness's DSStats Cacti Plugin. This gets you daily,weekly,monthly and annual stats with no complicated rrdtool stuff.
- New converter to take a rrdtool-based map config and make it into a DSStats-based one
- static datasource can be used for negative values
- SNMP datasource has configurable timeout and retry values.
- SNMP datasource has option to give up on a failing host
- LABELOFFSET supports percentage compass offsets and radial offsets, like NODES does.
- Percentage compass offsets (NODES and LABELOFFSET) support > 100% offsets

## Changes For This Version (0.96 to 0.96a)

Just the usual post-release bug reports...

### Fixes

- New z-ordering code did not work correctly on PHP4. This broke (at least) the editor. (thanks toe_cutter)
- \n is no longer treated as a newline in TARGETs (thanks NetAdmin)
- KILO was broken completely between 0.95b and 0.96 (thanks Jethro Binks)
- Link comments in certain positions could cause div-by-zero errors. (thanks again Jethro)
- USEICONSCALE didn't colorise (broken between 0.95b and 0.96 again) (thanks colejv)
- Managed to make LABELOFFSET case-sensitive.

## Changes For This Version (0.95b to 0.96)

### Fixes

- Cacti poller_output support works more reliably/at all on Windows
- Renaming a node in the editor correctly handles other relatively-positioned nodes and vias
- Minor issue with CRLF in map title for Cacti Plugin
- CLI tool set --define options incorrectly.
- Oneway links don't draw the INCOMMENT anymore
- negative TIMEPOS didn't hide the timestamp
- DEFAULT SCALE covers 0-100 properly (Thanks Dan Fusselman)
- Scaled ICON in DEFAULT didn't get overwritten properly in nodes (Thanks Fabrizio Carusi)
- No more floating-point imagemap coords (Thanks Trond Aspelund)
- RRDtool regional output (. vs ,) workaround
- Cacti poller_output handles NaN more gracefully now
- SNMP datasource should work with Windows SNMP again
- MRTG datasource tried to stat() URLs
- Error reporting for CLI --define was bad. --help text was out of date.
- Editor will honour LABEL from NODE DEFAULT, if it is set.

### Changes

- Cacti plugin uses "processed" map title now (allows {} tokens in the title)
- A NODE with no POSITION is not drawn, instead of drawn at 0,0. Useful for templates.
- A LINK with no NODES is no longer an error. Also for templates.
- The link_bulge secret mode bulges each side of a link independently now
- whitespace is stripped from the beginning and end of each line before parsing

### New Features

- TEMPLATE allows a node or link to copy it's settings from another, instead of from DEFAULT.
- RRD datasource can take SET rrd_default_path to make configs a little easier to read.
- RRD datasource can take SET rrd_default_in_ds and rrd_default_out_ds for non-Cacti users.
- RRD datasource can get Cacti query information (in poller_output mode ONLY) - like ifAlias, ifSpeed etc
- RRD datasource can take the ifSpeed/ifHighSpeed from the above, and use it in the map.
- RRD datasource fills in Cacti cacti_path_rra and cacti_url with Cacti base path and URL
- RRD datasource can take global SET rrd_options to add extra options to rrdtool command lines
- SNMP datasource also stores the raw data from the SNMP agent in snmp_raw_in/snmp_raw_out
- SNMP datasource allows '-' as an OID, similar to '-' targets in RRDs.
- Control the drawing order with ZORDER.
- New artificial icons: nink, inpie and outpie. See ICON in manual.
- Warning for probably-incorrect BWLABELPOS where in<out
- New global SET variables to disable some common warnings you may not care about :-)
- Cacti management screen shows number of warnings for each map last time it ran
- Cacti management screen also has a link to the log entries for the map in question
- The TARGET aggregation thing can also take scale factors now: -5.5*myrrdfile.rrd
- Cacti plugin caches thumbnail sizes, improving thumbnail view rendering
- Cacti plugin allows adding the same map twice (more useful than it sounds)
- Cacti plugin allows setting of map-global variables in the management UI
- Cacti plugin allows settings of global map-global (across all maps) variables too
- Cacti plugin adds links in 'user' pages to management screen (if you are an admin)
- HTMLSTYLESHEET keyword allows you to specify a URL for a CSS stylesheet (CLI tool only)
- A few extra CSS id and class attributes, to make styling the page easier.
- New token: in/outscalecolor contains HTML colour code of node/link colours for use in NOTES
- New NODES offset type - angle+radius
- New NODES offset type - compass-point+percentage
- "KEYSTYLE inverted" - to get a thermometer-style vertical legend.
- "COMMENTSTYLE center" to make comments run along the centre of a link arrow. (and 'edge' for the usual)
- COMMENTFONTCOLOR accepts 'contrast' as an option, for when it's over a link
- VIASTYLE angled (or curved) - you can turn sharp corners now
- Comment (and pos) editing in editor (based on code by Zdolny)
- Editor Settings dialog works, and allows you to set grid-snap and some overlays
- SCALE allows 'none' as a colour (for non-gradients). Only affects LINKs so far.
- fping plugin allows for changing the number of pings.
- TARGET strings can be enclosed in quotes, to allow spaces in them (mainly for external ! scripts)
- "KEYSTYLE tags" - like classic, but uses the scale tags instead of percentages.
- scripts in random-bits to help with automatic/assisted mapping.
- lots more pretty pictures in the manual, so you can see what I mean.
- IMAGEURI keyword to match --image-uri command-line option (ignored in Cacti plugin)
- MINTIMEPOS and MAXTIMEPOS to track data source times

## Changes For This Version (0.941 to 0.95)

This release has a lot of changes - most of them are small 'polishing' tweaks, but there are a few interesting bigger ones too. Happily, although there are a quite a few more features, this release actually has less lines of code than 0.941, due to some internal cleaning up.

### Known Issues

- ININFOURL / OUTINFOURL, INOVERLIBGRAPH / OUTOVERLIBGRAPH are not handled well by the editor. If you edit a map that uses these, then the 'in' side of the link will be copied to the 'out' side. New editor will handle this better.

### Fixes

- KEYOUTLINECOLOR is actually used now (thanks to llow once more)
- Editor doesn't throw away WIDTH and HEIGHT with no BG image
- Cacti Data-source and Graph picker doesn't restrict scrolling or resizing anymore
- weathermap-cacti-rebuild.php to work on both Cacti 0.8.6 and 0.8.7
- weathermap-cacti-rebuild.php to flat-out fail if Cacti environment is wrong.
- SNMP DS plugin had a typo that stopped it working at all (and no-one noticed for almost a year :-) ). (thanks to Fratissier Christophe for pointing it out)
- Added some better controls into SNMP DS plugin. You can correctly pull interface oper/admin status, for example, now.

### Changes

- DS plugins are able to return negative results now (breaks user-developed DS plugins)
- the scale: prefix for the RRD DS plugin can take negative scale factors
- (internal) plugins are each created as a single object now. Result: the plugin can cache results internally.
- (internal) broke out some of the larger classes (node, link) into separate files.

### New Features

- You can add a 'tag' to a SCALE line, to be used in ICON or LABELs later.
- USEICONSCALE - colorize icon images (based on patches from llow)
- screenshot mode. "SET screenshot_mode 1" at the top of the map will anonymise all labels, comments and bwlabels.
- LABELFONTCOLOR can use a special value of 'contrast' to always contrast with the label colour.
- Artificial Icons. Special icon 'filenames' - 'box' 'round' 'rbox' create a shaped icon without any file. See ICON and AICONFILLCOLOR for more.
- Map titles show up in browser title now.
- a basic 'live view' function which generates a map on demand. Sometimes. It's not very useful.
- LABELANGLE allows you to rotate node labels to 90,180,270 degrees. Needs truetype font.
- improved data-source picker in editor: host filter
- improved data-source picker in editor: option to aggregate data sources
- Moved data-source picker changes across into the graph-picker for NODEs too.
- SPLITPOS keyword to control position of midpoint in links
- VIA can be positioned relative to NODEs (like NODEs can) (thanks again to llow)
- Weathermap has a hook in the map viewing page to allow other plugins to add code there
- .htaccess files bundled with Weathermap to restrict direct access to configs and output
- filenames for output are much less guessable now (may break external references to maps)
- You can use 'DUPLEX half' on a link to make the bandwidth percentage calculate work for half-duplex links
- ININFOURL / OUTINFOURL, INOVERLIBGRAPH / OUTOVERLIBGRAPH, INNOTES / OUTNOTES, INOVERLIBCAPTION / OUTOVERLIBCAPTION allow you to have different urls for the in and out side of links (based on idea from llow)
- OVERLIBGRAPH (and IN/OUT versions) can take multiple URLs separated by spaces (again from idea by llow)
- debug/warning log output contains the map name, and the debug output is marked DEBUG
- debug log output contains the calling function, file/line number, too. Making debugging-by-mail easier.
- fping: TARGET to do live pings of devices. See targets.html
- a very basic sample 'skeleton' DS plugin
- an additional check-gdbug.php to spot bad GD installs
- MRTG DS plugin can do a few new tricks. See TARGET and targets.html

## Changes For This Version (0.94 to 0.941)

### Fixes

- Added extra code to help discourage browser caching.
- Issue with '-' DS names again.
- Removed some extra chatty debugging code from poller_output

## Changes For This Version (0.93 to 0.94)

0.94 was released early, to fix the one small issue caused by files moving around in the recent Cacti 0.8.7 release. However, there are some nice new features even so - INBWFORMAT has been requested for quite a while, and so has poller_output support.

### Changes

- Finally a better tab image, and a red 'active' one too, for the Cacti plugin.

### New Features

- INBWFORMAT and OUTBWFORMAT allow you to format the text for BWLABEL, same as for COMMENTs
- New cactithold/cactimonitor data source plugin reads data from Cacti's Threshold plugin. (Original development for this plugin was paid for by Stellar Consulting - Thanks!)
- New LINKSTYLE command allows you to have one-way (one arrow) links.
- RRD DS can use Cacti's poller_output to get data without running RRDtool at all. (this also means it can work with the Boost plugin for large installations) See targets.html for more info on this one.
- Editor - Align horizontal and Align-vertical for links. Calculates link offsets to make link vertical/horizontal.

### Fixes

- "Full Screen Maps" mode in Cacti Plugin was broken by me adding the "View Only First" mode.
- Imagemaps for horiz/vert format legend were wrong in editor (thanks to Alex Moura for pointing this out)
- Changes for compatibility with Cacti 0.8.7's moved config file.

## Changes For This Version (0.92 to 0.93)

### Changes

- The auth realm names for Cacti have been changed to match ReportIt and Aggregate - easier to tell who does what (Plugin -> Weathermap: View Maps)
- Editor warns about older editor-config.php format now
- Formatted numbers (Mega, Kilo etc) now can include milli, micro and nano (m,u,n).

### New Features

- weathermap-cacti-plugin.php?action=viewmap&id=mapfilename works as well as a map number - useful for crosslinks
- Warning for duplicate node or link names
- unique code for each warning message, and a page to explain it on the website. Ugh.
- warning in editor file-selector so you can tell if the file is read-only
- click config filename to edit in editor from Cacti (thanks to streaker69)
- cactihost: DS plugin fetches a bunch of other stats from Cacti's DB now, too (like availability and response times)
- Picking Cacti sources from editor has a javascript "live filter" feature now (needs a little work)
- node coordinates are directly editable in the editor now
- File picker allows you to use an existing map as a template
- Editor now allows you to clone a node with all it's styling intact.
- When picking coordinates (new node, move node, move timestamp etc), you can see the coordinates
- Editor toolbar fixed to window, to make it easier to scroll around large maps
- RRD Datasource has improved warnings for non-existent DS names
- Editor allows you to edit raw text of nodes and links
- Editor link in management page (warnesj)
- Docs link in management page too (streaker69)
- Editor has a better warning for unwriteable files and directory now.
- When you come TO the editor from Cacti, the Change File goes BACK to Cacti
- "Show Only First" mode in Cacti UI - useful for heirarchies of maps with a parent.
- scale: prefix for RRD datasource - multiply/divide by any value as you read an rrd datasource

### Fixes

- RRD doesn't consider DSes other than the ones you named when finding a valid line.
- editor-generated node names are a bit shorter (and easier to read) now.
- keyboard focus switches nicely to the popup dialogs now.
- Non-unique IDs in imagemaps, in overlib mode.
- COMMENTPOS 0 doesn't kill everything anymore
- OVERLIB would behave incorrectly with PHP4 and relatively positioned nodes (Bernd Ziller)
- Better-validating HTML produced
- angled bwlabels have the correct imagemap
- divide-by-zero error for some (?) PHP versions in poller
- the key_hidezero secret setting hides the zero in a gradient in a classic scale too.

## Changes For This Version (0.91 to 0.92)

### New Features

- BWSTYLE allows you to align the BWLABEL boxes with their links. Looks nice!
- COMMENTPOS allows you to move comments, much like BWLABELPOS for BWLABELs
- The editor works the way you'd expect for defaults now.
- The editor does a bunch of clever maths when moving a node that is part of a curved link to make a sensible result (I like this one).
- The editor will let you pick an INFOURL and OVERLIBGRAPH for a NODE from your Cacti graphs (but not a TARGET yet).
- The editor doesn't require an `editor-config.php` anymore, but if you do have one, make sure it's based on the editor-config.php-dist in this version. This file has changed.
- Secret SET codes: key_hidepercent_scalename and key_hidezero_scalename
  You can set these at the top of the config file, for each scale (change scalename to the scale name). `SET key_hidezero_DEFAULT 1` hides the 0->0 line if there is one, in a 'classic' style legend for that scale. `SET key_hidepercent_scalename 1` hides the percentage signs in the 'classic' style legend for that scale.

### Fixes

- SET in a DEFAULT node or link wasn't inherited properly.
- weathermap.conf is a simple map again. I accidentally packaged my test map for 0.9 and 0.91
- Any unreadable files in the configs/ directory would kill the editor
- One PHP short_tag remained, which upsets some PHP installs (seems to be mainly Windows)

## Changes For This Version (0.9 to 0.91)

After all the big changes (below for 0.9), there are a whole bunch of bugs that no-one spotted in the testing, so this release is mostly a clean-up of those. There are a couple of small changes for new features, and a bit more diagnostic stuff for installation problems.

### New Features

- 'Quiet Mode' Logging - in the Cacti plugin, there is a new setting to make Weathermap log only errors in the standard 'LOW' logging setting.
- Subtractive Aggregation - if one of the clauses in a TARGET line begins with a '-', then that value is subtracted from the result instead of added. This can be useful to calculate a value that couldn't be measured directly. For example, Netscreen firewalls don't give per-policy bandwidth stats, so to find out how much traffic is going to the internet, and how much to a VPN, you can start with the total interface traffic, and take out the VPN traffic (which you can measure), to leave the Internet traffic.
- There is a new check.php script, that verifies some basic requirements of your PHP installation. It's mainly useful during installation, so it's described in the installation instructions.
- A couple of additional variables are available in the 'special string tokens' - 'inscalekey' and 'outscalekey' store the internal names of the SCALE line that was triggered for the 'in' and 'out' values of a map object. You can use this to do some things like changing icons based on a value, without needing to write a plugin yourself. It's pretty obscure, but could be handy.

### Fixes

- RRD bug with '-' DS names. This was fixed in 0.9pre3, but somehow slipped through.
- ReadConfig doesn't complain about KEYPOS DEFAULT -1 -1 (as written by WriteConfig) anymore
- The MRTG plugin made some assumptions that broke handling of MRTG html files on remote systems. It doesn't now.
- NOTES was not fully tested, and broke cactihost: targets, at least.
- KILO was broken - fixed now.
- BWLABELPOS was handled badly by the editor - it would swap them over

## Changes For This Version (0.82 to 0.9)

I've divided the changes up into chunks. Most of the serious work was done in the Structural Changes section, but there are plenty of things for everyone. These are brief descriptions - see the Config Reference for the full detail. I've mentioned the appropriate configuration keywords if there are any.

### Graphical Changes

These tend to be smaller things, but together they make a lot of useful additions.

#### Link comments

You can add a comment string which runs down the side of link arrows. This is intended for use for circuit references, or interface names. There are 4 new directives to make this happen: INCOMMENT, OUTCOMMENT, COMMENTFONT and COMMENTFONTCOLOR. You must use a TrueType COMMENTFONT to use this feature, as none of the other font types allow for rotation of text.

#### Bandwidth Label Positioning

You can now move the bandwidth labels (those little boxes) up and down the link arrow. You set a percentage position with BWLABELPOS.

#### Pixel-Offsets

You can make links end at arbitrary positions relative to a node now. Previously you could use compass-points, now you can also use pixels for the offsets in a NODES line

#### JPEG & GIF Support

If your GD library supports it, then Weathermap now understands JPEG and GIF files for BACKGROUND, ICON and IMAGEOUTPUTFILE.

#### NOTES & OVERLIBCAPTION

You can specify a caption string for the 'popup' overlib window now, per-node/link. You can also have HTML-formatted text in that window, with or without the graph. See NOTES and OVERLIBCAPTION.

#### New Legend Styles

The new KEYSTYLE directive allows you to choose between 'classic' and two new styles of Legend. The new styles are neater for showing gradient scales, or when you have a lot of different bands.

#### Relative Positioning

You can position a node relative to another node. This is handy for maintaining big rows of nodes, where only one needs to be fixed in position now.

Use it with String Tokens to make captions for your nodes, with additional information.

### Structural Changes

The internal structure of Weathermap has changed quite a lot in this version. It started as a few small changes, but each one showed that another was required.

#### Datasource Plugins

All the data-reading parts of Weathermap are now in plugins. This is to allow users to add their own external data sources more easily, without having to change the Weathermap code. All the previous TARGET strings will work as before, and I've added a few new ones for 0.9:

- static - if you need to fix a data value, you can do it without an external text file.
- cactihost - read the up/down status of a host in Cacti
- gauge - Read RRD values without any special treatment.

The RRD plugin also has some improvements in dealing with error conditions in this release.

There are planned plugins for Cacti (reading directly from the Cact database), Nagios Host Status, SNMP directly and others.

#### NODE Targets

NODEs can have data now. This means you can have them change colour according to a SCALE, just like a LINK does. Since a NODE only has one value, you can choose which one to use (of the two that a TARGET provides), with USEVALUE.

#### Multiple SCALEs

Because you probably don't want your nodes to change colour with the same values as your links, you can now have multiple SCALE sets too. The default one is DEFAULT, but you can define others and use them with USESCALE in a NODE or LINK section.

#### String Tokens

You can embed information from Weathermap, and from your own data, in almost any string in Weathermap. This allows you to do things like:

- Show percentage CPU usage in a node LABEL
- Change which ICON is used depending on a datasource value
- Add extra "sub-NODEs" around a NODE, with addional information
- Use generic TARGET, INFOURL, OVERLIBGRAPH lines in the DEFAULT link and node

#### Arbitrary Parameters

The new SET directive lets you define new 'variables' per-NODE, per-LINK or for the whole map. These can be used to give fine-tuning parameters to the data source plugins, and also as additional data in String Tokens.

### Cacti Plugin

Most of the Cacti Plugin changes are bugfixes or for more advanced users.

#### Non-Standard Poller Cycle Times

If you are using the "<5 minute poller" patch from TheWitness, then you may not want the time-consuming Weathermap process to run every poller cycle. There is now an option to choose how often Weathermap redraws it's maps, including 'Never'.

#### Async Map Generation

If you choose 'Never' above, then you need some way to redraw. The new `weathermap-cacti-rebuild.php` script allows you to run a separate cron job for Weathermap, but in the environment it would have inside the poller process.

#### Recalculate Now

If you have your permissions set up correctly, then you can force the redraw of all maps from within the Cacti UI, instead of waiting for a poller cycle.

### Editor

There are no new features in the Editor for 0.9, although a few annoying bugs have been squashed. I have big plans for the editor, but they are a whole project by themselves, so I've put it to one side. Otherwise 0.9 would never have appeared :-) Now this version is released, the Editor is one the main focus areas for the next release.

### Bugfixes

There were a lot of bugs fixed along the way. Most were new ones, but a few are things that existed in 0.82 too:

- Wierd bug in HTML_ImageMap if you have a lot of similarly-named NODEs or LINKs.
- Floating-point limits in SCALEs work correctly now. Also, you can specify a 0-0 SCALE line and it will always take precedence.
- Cacti plugin doesn't assume 'admin' user always exists, and that users are never deleted.
- Cacti plugin's Cycle mode works in IE now.
- KILO was ignored in some places.
- Editor will let you rename nodes now!
- Editor deals properly with ' in node labels
- Editor deals properly with pathnames containing '\' on Windows.
- Editor lets you pick JPG and GIF images too, since we now support them
- Close-together nodes don't crash the curve-drawing anymore