gpsmap

Plots your Cacti Devices on a map by latitude and longitude, colours each marker by Device status, and optionally draws coverage areas around Access Points. It suits networks whose Devices are spread across real geography: wireless operators, campus and metro networks, and anyone who needs to see where a fault is rather than only which Device is down.

The map is generated by the poller and written to disk as XML, so opening the Maps tab reads a static file instead of querying the database.

Features

• Devices plotted by latitude and longitude, coloured by Up, Recovering, Down, Disabled or Undefined status

• Per Device Template marker icons for the Up, Recovering and Down states

• Coverage overlay drawing an area around Access Points, sized to reach the furthest Device sharing the Access Point's group number, and optionally limited to an arc

• Drill down by subnet, from the first octet through to individual Devices

• KML export alongside the XML, so the same data opens in Google Earth

• Configurable map centre, zoom, refresh interval and marker combining

Requirements

Component	Requirement
Cacti	1.2.15 or later
PHP	8.0 or later, as Cacti 1.2 requires
Database	MySQL or MariaDB, as Cacti requires
Browser	Any current browser with JavaScript enabled
External	A Google Maps API key, and a Content Security Policy that permits Google's map scripts

Cacti 1.2.15 is the floor because it introduced the Content-Security Alternate Sources setting. Without that setting the map cannot load its JavaScript, and there is no workaround inside Cacti.

Installation

1. Copy the plugin into Cacti's plugins directory as gpsmap.

2. Give the Data Collector write access to plugins/gpsmap/XML. The directory name is uppercase, which matters on case sensitive filesystems. Under SELinux it also needs a context both the web server and the poller can write.

3. Install and enable the plugin under Console -> Configuration -> Plugins.

4. Grant users the View Maps realm, and Configure Maps for anyone who should edit Map Templates, under Console -> Utilities -> User Management.

Installing adds seven columns to Cacti's host table (latitude, longitude, GPScoverage, start, stop, groupnum, rdistance) and creates the gpsmap_templates table. Uninstalling deliberately leaves both in place so coordinates survive an accidental removal.

Configuration

Three things must all be true before a Device appears on the map. Most "nothing is showing" reports are one of them missing.

1. A Google Maps API key

Obtain a key from the Google Maps Platform and enter it under Console -> Configuration -> Settings -> Maps. Google requires a billing account even within the free tier. Without a key nothing renders.

2. A Content Security Policy that allows it

Cacti's default policy permits scripts only from the Cacti web server itself. The map loads its JavaScript from Google, so until the policy is widened the Maps tab is blank and the only evidence is a Refused to load the script message in the browser console.

Under Console -> Configuration -> Settings -> General:

Setting	Value
Content-Security Alternate Sources	https://maps.googleapis.com https://maps.gstatic.com
Content-Security Script Policy	Allow both unsafe-eval and Non-Nonced Inline JavaScript

Both are required. The Google loader calls eval(), so permitting the alternate sources alone is not enough.

If Cacti sits behind a reverse proxy that sets its own Content-Security-Policy header, that header replaces Cacti's rather than merging with it. Reproduce the whole policy at the proxy, not just the two hosts, or the map stays blank with Cacti's own settings correct.

3. A Map Template and Device coordinates

Under Console -> Templates -> Map, add each Device Template that should be mapped. For each one, choose the marker icons for the Up, Recovering and Down states, and mark whether the Template represents an Access Point. A Device whose Device Template is not listed here never appears, regardless of its coordinates.

Then edit a Device and set its latitude and longitude under Map Settings. A Device left at 0.000 for either value is treated as unplaced and is skipped.

Access Points take three further values:

Field	Meaning
Group ID	Devices sharing this number determine how far the coverage area extends; 0 disables
Starting Degree	Start of the coverage arc, 0 to 360
Stopping Degree	End of the coverage arc, 0 to 360
Specify Radius	Fixed radius, instead of deriving it from group members
Overlay Inclusion	Whether this Device counts towards an Access Point's coverage area

Marker icons are read from plugins/gpsmap/images/icons. Any png, jpg, jpeg or gif placed there is offered in the Map Template dropdowns, but a name is only drawn on the map if it starts with a letter or underscore and contains only letters, digits and underscores. See Troubleshooting.

Map settings

Setting	Effect
Initial Latitude / Longitude	Where the map centres on load
Initial Elevation	Starting zoom, 0 to 12
Map Refresh	Reloads the map after this many minutes; set to the poller interval, or 0 to disable
Tab Radius	Distance within which nearby markers are combined into one tabbed popup
Display Disabled Devices	Whether disabled Devices are drawn
Coverage Overlay	Whether Access Point coverage areas are drawn
Quality	Number of segments used to draw a coverage circle; above 15 is smoother, high values slow the browser
Geolocation URL	Service used to resolve a Device's approximate location

How it works

Understanding the order of events explains most of what can go wrong.

1. The poller runs and Cacti calls the plugin's poller_bottom hook.

2. The plugin selects every Device whose Device Template appears in gpsmap_templates, resolves each hostname to an address, and discards any Device without coordinates or whose name does not resolve to IPv4.

3. It writes plugins/gpsmap/XML/all.xml, all.kml and all-top.html, then repeats for each subnet prefix so the drill-down views are prebuilt.

4. Opening the Maps tab serves a page that loads Google's map library and fetches the matching .xml file over HTTP.

Nothing appears until a poll cycle has completed after configuration. If plugins/gpsmap/XML is empty, the poller has not run or cannot write there.

Troubleshooting

The Maps tab is blank. Almost always the Content Security Policy rather than a fault in the plugin. Open the browser console: a Refused to load the script entry naming maps.googleapis.com means the two settings above have not been applied. If the console instead shows a JavaScript syntax error, an icon filename is the likely cause; see below.

The map draws but no Devices appear. Check in order: the Device Template is listed under Templates -> Map; the Device has non-zero coordinates; a poll cycle has completed since both were set; and plugins/gpsmap/XML contains files newer than the last poll.

Some Devices are missing. A Device is skipped when it has no coordinates, when its hostname does not resolve to an IPv4 address, when its Device Template is not in Map Templates, or when it is disabled and Display Disabled Devices is off.

The XML directory is empty. The Data Collector cannot write to it. Check ownership, permissions and SELinux context. The Cacti log records a failure for each file it could not write.

A chosen icon does not appear. An icon's name is emitted as a JavaScript identifier, so files whose base name is not a plain identifier, such as ap.v2.png, my-icon.png or 2fast.png, are skipped when the map is drawn. They are still offered in the Map Template dropdowns, so the Template saves cleanly and the marker then falls back to the default. Rename the file so it starts with a letter or underscore and uses only letters, digits and underscores.

Markers overlap or hide each other. Raise Tab Radius so nearby Devices combine into one popup with a tab per Device.

Support

Report problems as GitHub issues, including your Cacti version, plugin version, PHP version, and anything the browser console reports. A blank page with no console output is a different problem from a blank page with a Refused to load the script error, and the console tells them apart.

General discussion belongs on the Cacti forums.

Licence

GPL v2 or later. See LICENSE.

Originally written by Andrew Aloia, extended by Wixiweb, and maintained by The Cacti Group.