WeathermapNG — Network Visualization for LibreNMS

A modern network weathermap plugin for LibreNMS that provides real-time network topology visualization with animated traffic flow.

• Real-time Visualization: Live traffic data with animated flow indicators
• Professional Editor: 3-panel layout with toolbox, canvas, and properties sidebar
• Via Points & Curved Links: Route links through intermediate waypoints with straight, angled, or Catmull-Rom curved paths
• Zoom, Pan & Minimap: Mouse-wheel zoom, middle-click pan, click-to-navigate minimap
• Keyboard Shortcuts: Ctrl+S save, Ctrl+Z/Y undo/redo, arrow nudge, Delete, +/-/0 zoom
• Undo/Redo: 50-state history with full node and link state tracking
• Dark/Light Mode: Auto-detects LibreNMS theme and matches it
• Grid Snapping: Toggle snap-to-grid for precise node alignment
• RRD-based Traffic Data: Real-time bandwidth from LibreNMS RRD files
• Server-Sent Events: Live updates without polling (streamed inline from the render controller)
• Admin-Only Authorization: All 24 mutation endpoints require admin (hasGlobalAdmin(), isAdmin(), level ≥ 10, or hasRole('admin')); read endpoints are open to every authenticated user
• Import/Export: JSON format for backup and sharing maps
• Embed Support: Embed maps in dashboards with live updates
• Map Templates: Built-in templates for common network topologies
• Map Tags & Filtering: Organize maps with tags from the editor and filter the index gallery by tag
• Per-Map Default Styles: Configure default node/link colors and link width/via style per map; stored in map options and applied at render time without mutating node/link data
• Operational Diagnostics: Admin page with health checks, route registration, writable paths, and resource counts
• Map Versioning: Snapshot storage, history, restore, compare, and delete workflows
• LLDP/CDP Auto-Discovery: Automatically seed map topology from LibreNMS neighbor data
• Editor Bulk Operations: Multi-select, marquee, bulk delete with undo, group drag and nudge
• Viewport Culling: Large-map pan/zoom performance — off-screen nodes and links are skipped
• CPU/Memory Overlay: Node CPU and memory utilization displayed in the embed view
• RRD Graph Hover: Hover nodes/links for inline LibreNMS time-series graphs
• Alert Integration: Active alert badges with severity coloring and click-through to alert details
• Kiosk/NOC Wall Mode: Fullscreen display with auto-cycling between maps
• Nested Maps / Drill-Down: Click a summary node to navigate to a detailed sub-map (campus → building → rack); breadcrumb bar tracks the hierarchy
• Legacy Weathermap Import: Read PHP Weathermap-style .conf files (round-trip export included)
• Common Topology Templates: Built-in Data Center, WAN/MPLS, Campus, and Branch Office templates with pre-placed topology
• Accessibility: ARIA labels on icon-only controls, keyboard focus visibility, and form labels across index, editor, and embed views
• Render Diagnostics: ?debugDots=1 overlays particle positions and transform state; ?debugDots=2 adds a full render-pipeline panel (map data, transport, transforms, canvas geometry, browser zoom)

Three commands get you running on a native LibreNMS install:

cd /opt/librenms/html/plugins
git clone https://github.com/lance0/weathermapNG.git WeathermapNG
sudo chown -R librenms:librenms /opt/librenms/html/plugins/WeathermapNG
sudo -u librenms -H bash -lc 'cd /opt/librenms/html/plugins/WeathermapNG && ./quick-install.sh'

The script installs dependencies, registers the Composer package with LibreNMS, sets up database tables, configures permissions, and enables the plugin. Run it as the librenms user — running as root can leave root-owned Composer files behind. just install LIBRENMS_PATH=/opt/librenms runs the same quick-install.sh flow — a thin wrapper for the command above.

A Docker-based install is available for development and testing. See INSTALL.md for the full Docker setup.

Try the plugin without real LibreNMS devices — demo mode generates smooth, deterministic simulated traffic (per-id sine waves, jitter-free):

echo "WEATHERMAPNG_DEMO_MODE=true" >> /opt/librenms/.env
php /opt/librenms/html/plugins/WeathermapNG/database/seed-demo.php

See INSTALL.md for details and sample topologies.

1. Open the plugin at https://your-librenms/plugin/WeathermapNG
2. Create a map — click "Create New Map", pick a template, or import an existing map
3. Configure the name, title, dimensions, tags, and default node/link styles
4. Design in the canvas editor: add devices from the right sidebar, drag to position, draw links between nodes
5. Save — your map is live with real-time traffic data
6. Troubleshoot via the admin Diagnostics page if anything looks off

• LibreNMS (latest stable)
• PHP 8.2+
• Composer
• MySQL/MariaDB

Drop a map into any dashboard with an iframe:

<iframe src="https://your-librenms/plugin/WeathermapNG/embed/1"
        width="800" height="600" frameborder="0">
</iframe>

Optional query parameters: metric (percent/in/out/sum), sse=0 (force polling), nav=0 (disable pan/zoom), scale=bytes, debugDots=1/2 (render diagnostics). See the Embed Viewer Guide.

cd /opt/librenms
php artisan route:list | grep -iE 'weathermap|wmng'
php artisan cache:clear
php artisan view:clear

If no WeathermapNG routes are listed, register the plugin as a Composer path package:

cd /opt/librenms
composer config repositories.weathermapng '{"type":"path","url":"html/plugins/WeathermapNG","options":{"symlink":true}}'
FORCE=1 composer require 'librenms/weathermapng:*' --with-dependencies --no-interaction
php artisan package:discover
php artisan optimize:clear
php artisan config:clear

LibreNMS validate.php may report wmng_* tables as extra tables — those belong to WeathermapNG and should not be dropped. It may also report utf8mb4_bin collation warnings on JSON-backed columns such as wmng_map_templates.config, wmng_nodes.meta, wmng_maps.options, and wmng_links.style; those are expected for the current schema.

If an older install left duplicate WeathermapNG rows in LibreNMS' plugins table, rerun quick-install.sh or php database/setup.php as the librenms user — both normalize plugin registration and remove stale duplicates.

sudo chown -R librenms:librenms /opt/librenms/html/plugins/WeathermapNG

• Verify the map has valid device and port associations.
• Check that the LibreNMS user can read the relevant RRD files.
• If you use the optional poller (bin/map-poller.php), check its cron entry and logs.
• Use demo mode to separate rendering issues from live data issues.

More troubleshooting in INSTALL.md.

cd /opt/librenms/html/plugins/WeathermapNG
git pull
composer install --no-dev --optimize-autoloader
php database/setup.php
cd /opt/librenms
FORCE=1 composer require 'librenms/weathermapng:*' --with-dependencies --no-interaction
php artisan package:discover
php artisan optimize:clear
php artisan route:clear
php artisan view:clear
php artisan config:clear
php artisan cache:clear
php artisan route:list | grep -iE 'weathermap|wmng'

• Installation Guide — detailed setup, Docker, demo mode, and troubleshooting
• Deployment Guide
• API Documentation
• Embed Viewer Guide
• Performance Notes
• Roadmap
• Release Notes
• Versioning Guide
• Contributing

WeathermapNG follows a modular service-oriented architecture:

SSE is handled inline in RenderController::sse — there is no separate streaming service.

Common workflows are exposed via just (brew install just):

just setup                                       # install PHP/Composer dependencies (idempotent)
just lint                                        # syntax-check all PHP sources
just test                                        # full PHPUnit suite (no coverage)
just test-one LegacyConfServiceTest              # run one test class
just check                                       # lint + test — the "PR-ready" gate
just install LIBRENMS_PATH=/opt/librenms          # full plugin install (wraps quick-install.sh)
just update LIBRENMS_PATH=/opt/librenms           # update an existing install (wraps deploy.sh)
just validate-install LIBRENMS_PATH=/opt/librenms # post-install deployment check
just verify                                      # verify plugin structure / install readiness
just verify-deployment URL=http://localhost:18080 # smoke-check a deployed plugin over HTTP
just dev-up                                      # docker dev stack with plugin mounted live
just dev-stop                                    # stop the dev stack (data volumes preserved)
just dev-reset                                   # reset the dev stack including data volumes (destructive)
just test-install                                # full docker install test suite
just test-install-local INSTALL_DIR=/opt/librenms # host-path install test suite
just visual URL=http://localhost:18080           # render screenshots (needs a running stack)
just tag v1.13.1                                 # bump VERSION + VersionMetadataTest + tag + push

visual takes URL as a recipe parameter; pass OUTDIR as an environment variable (OUTDIR=/tmp/shots just visual) to override the output directory — the recipe's two default-quoted parameters suppress inline descriptions in just 1.x.

Run just --list for the full recipe list. Each recipe is a thin facade over an existing entrypoint (quick-install.sh, deploy.sh, verify.php, tests/*.sh); only setup contains logic of its own.

vendor/bin/phpunit
./tests/docker-test.sh     # full docker install suite
./tests/install-test.sh    # host-path install suite

Pull requests welcome. Please follow PSR-12 coding standards and include tests.

• Issues: GitHub Issues
• Community: community.librenms.org

MIT License — see LICENSE