README

Turn “an interface is down” into “these partners, sites, devices, and services may be affected.”

Customer / Partner Impact is a LibreNMS dashboard widget for ISP and NOC environments. It correlates current device and interface failures with discovered topology, explicit device dependencies, business mappings, locations, and customer-facing ports.

The widget integrates with LibreNMS's native dashboard authentication, settings, AJAX refresh, and light/dark themes. It does not patch LibreNMS core source files.

Capabilities
How impact is calculated
Architecture
Installation
Dashboard setup
Configuration and mappings
Publishing
Project structure
Known limitations
Documentation

Capabilities

Area	Support
Incidents	Current device-down and administratively-up/interface-down conditions
Topology	LibreNMS discovered links plus explicit device dependencies
Safety	Iterative traversal, visited-device tracking, configurable maximum depth
Redundancy	Failed-edge removal and alternate-path detection
Mappings	Device groups, locations, devices, ports, aliases, and manual mappings
Correlation	Root-incident selection and downstream alert de-duplication
Impact	Partners, sites, downstream devices, customer-facing ports, and services
Trust	Confidence levels, redundancy state, and visible impact reasoning
UI	Native widget settings, automatic refresh, responsive layout, light/dark themes

How impact is calculated

For a failed interface with a discovered neighbor, the widget:

Builds a cached graph from active LibreNMS topology links.
Removes the failed device pair from that graph.
Walks the remote side with loop protection and a maximum depth.
Tests whether another route still reaches the root side.
Classifies reachable devices as redundant instead of unreachable.
Resolves mapped partners, customers, sites, ports, and service counts.
Assigns severity and confidence without presenting estimates as exact values.

For device-down incidents, explicit LibreNMS device dependencies establish downstream direction. The widget deliberately does not infer direction from hostnames.

Architecture

Component	Responsibility
`CustomerImpactController`	Widget settings, current failure detection, filtering, and response rendering
`NetworkTopologyService`	Cached graph construction, dependency traversal, loop protection, and alternate paths
`ImpactAnalysisService`	Affected resources, redundancy, service estimates, severity, confidence, and dependency tree
`CustomerMappingService`	Manual, group, location, device, port, and alias mappings
`IncidentCorrelationService`	Correlation-window-aware root incident de-duplication
`ImpactCacheService`	Separate topology and short-lived analysis caches

Installation

Stable release from Packagist

Once version 1.0.0 is published, install it directly from Packagist—no widget source clone or custom Composer repository is required:

cd /opt/librenms
sudo -u librenms env FORCE=1 ./scripts/composer_wrapper.php require drakelid/librenms-customer-impact-widget:^1.0 --with-all-dependencies --update-no-dev
sudo -u librenms php artisan vendor:publish --tag=customer-impact-config --force
sudo -u librenms php artisan migrate --force
sudo -u librenms php artisan optimize:clear

Development version from source

Before the first stable release, or when testing unreleased changes, keep the repository alongside LibreNMS:

/opt/
├── librenms/          # Existing LibreNMS installation
└── customer-impact/   # Development checkout

sudo git clone \
  https://github.com/Drakelid/customer.partner-impact-widget.git \
  /opt/customer-impact

sudo chown -R librenms:librenms /opt/customer-impact

sudo -u librenms \
  /opt/customer-impact/install.sh \
  /opt/librenms

The installer:

verifies the target LibreNMS directory;
backs up composer.json and composer.lock;
prefers LibreNMS's scripts/composer_wrapper.php;
registers /opt/customer-impact as a Composer path repository;
performs the intentional dependency change with FORCE=1;
installs without development dependencies;
publishes the widget configuration;
runs reversible database migrations; and
clears Laravel caches.

Important

Use the full installation and operations runbook for preflight checks, manual recovery, validation, upgrades, troubleshooting, and rollback.

Dashboard setup

After installation:

Sign in to LibreNMS.
Open Overview → Dashboard.
Select the desired dashboard and click Edit Dashboard.
Open Add Widget.
Select Customer / Partner Impact.
Open its settings and save the initial configuration.

Recommended initial settings:

Setting	Initial value
Refresh interval	60 seconds
Maximum topology depth	10
Correlation window	5 minutes
Root device groups	All/empty
Device-down incidents	Enabled
Interface-down incidents	Enabled
Minimum severity	All

No qualifying customer or partner impact detected is a successful empty state. It means the widget ran but found no matching current failures.

Configuration and mappings

The published configuration is:

/opt/librenms/config/customer-impact.php

It controls:

topology and analysis cache periods;
critical-interface alias detection;
customer-facing port detection;
alias-to-entity parsing; and
severity thresholds.

Business entities can be mapped to:

LibreNMS device groups;
locations;
individual devices;
individual ports; or
configurable interface aliases such as PARTNER: HK Fiber, SITE: Etne POP, and CUST: Acme AS.

Exact service counts require explicit entity data. When explicit counts are unavailable, the widget labels customer-port-derived values as estimates.

See Configure mappings for SQL examples and cache-clearing commands.

Publishing

The Packagist identity is:

drakelid/librenms-customer-impact-widget

Packagist derives releases from Git tags. The repository intentionally does not hard-code a version in composer.json.

See PUBLISHING.md for first submission, GitHub synchronization, semantic tagging, validation, and the release checklist.

Project structure

customer-impact/
├── config/
│   └── customer-impact.php
├── database/migrations/
├── resources/views/widgets/
├── src/
│   ├── Http/Controllers/
│   ├── Services/
│   └── CustomerImpactServiceProvider.php
├── tests/
├── .github/workflows/
│   └── composer-validate.yml
├── CHANGELOG.md
├── composer.json
├── install.sh
├── INSTALL.md
├── PUBLISHING.md
└── README.md

Known limitations

Device-down direction requires configured LibreNMS device dependencies.
Parallel physical members between the same device pair are currently represented as one device-level edge; LAG-aware modeling is future work.
BGP, packet-loss, and interface-error incident adapters are not enabled in version 1.
Interface-down duration remains unknown unless a reliable incident timestamp is available.
Device-group names are never hard-coded; administrators must map business entities or use alias rules.
Exact service counts require explicit mappings; all fallback counts are labelled as estimates.

Documentation

License

GPL-3.0-or-later. See composer.json for package metadata.

drakelid / librenms-customer-impact-widget

Maintainers

Package info

Statistics

Security