Skip to content

About

hyperglass is the network looking glass that tries to make the internet better.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

799 stars

Watchers

15 watching

Forks


Hyperglass logo

The network looking glass that tries to make the internet better.


Documentation   |   Upstream live demo

CI


Hyperglass is a network looking glass. It lets customers, peers and other engineers run BGP route, BGP community, BGP AS path, ping and traceroute queries from the routers you choose, through a web interface and a REST API, without touching the routers themselves. You decide which devices, commands, targets and result formats are public.

The community-maintained Hyperglass project incorporates the Ultraglass implementation. The Python package, CLI, configuration paths, environment variables and service names remain hyperglass. The migration is tracked in #390; the migration release is 3.0.0.

Add a router in four commands

The hyperglass onboard command writes the device entry, proves every published query against the live router, and tells you which features are still off. No hand-written YAML, no guessing at platform attributes, no finding out from a user that a query is broken.

hyperglass onboard device            # prompts for the router, validates it, writes devices.yaml
hyperglass onboard test core1        # runs every built-in query the router offers; PASS or FAIL per query
hyperglass onboard check             # reports feature settings and suggests the config lines to change
hyperglass onboard directive core1   # optional: build and test a custom command, then save it
Step What it does What you get
onboard device Asks for address, port, platform, credential, OS version, VRF and structured output. Prompts only for the attributes the platform's built-in commands use. Enter ? to list platform keys. A validated entry saved to devices.yaml with owner-only permissions. Other entries stay untouched.
onboard test DEVICE Sends every built-in IPv4 and IPv6 command the device offers, with default public targets you can override. One block per query showing the command sent, fallback use, device errors and parsed field coverage, then a PASS/FAIL summary. Exit code 1 on any failure.
onboard check Reads the configuration afresh and reports structured output, RPKI, cache, enrichment, server DNS, My IP, self-hosted fonts and per-device settings. A PASS/OFF/UNKNOWN table with a Set: line for every suggested change, as a dotted config path you paste into YAML.
onboard directive DEVICE Takes a directive ID, a command template with {target}, a target rule and a test target. Runs it once on the device. A tested custom directive saved to directives.yaml, ready to add to the device's directives list.

Every command accepts --json for scripting. Restart Hyperglass after a save so it loads the new entry. The full walkthrough with example sessions is in the device onboarding guide.

Features

Area Feature Details
Queries BGP route Look up an IPv4 or IPv6 prefix in the device's BGP table, optionally within a VRF.
Queries BGP community List routes carrying a BGP community value.
Queries BGP AS path List routes matching an AS path expression. Per-platform syntax is validated before the command is sent.
Queries Ping and traceroute IPv4 and IPv6, sourced from the device's configured source addresses.
Queries Custom directives Publish any device command with its own target rules, fixed-choice select fields, per-platform syntax and version-selected fallback commands.
Queries VRF queries Built-in VRF command forms for 16 platforms. Set vrf on the device entry.
Results Structured BGP tables Parsed route tables with prefix, next hop, AS path, communities, MED, local preference, weight, age and RPKI state, plus an interactive AS path graph. Explicit opt-in on every supported platform.
Results Structured traceroute Parsed hops with per-probe RTT, loss and best, worst and last statistics per hop.
Results RPKI validation Router-reported state, or external validation through Cloudflare or your own Routinator.
Results IP enrichment ASN, organisation, country and IXP metadata, inline or asynchronous. Router-provided traceroute hostnames are preserved. Hops without a hostname get a bounded reverse DNS lookup for public addresses.
Results Community policy Deny or permit listed communities, or append friendly names to them.
Results Text output Raw device output with configurable highlighting for devices that stay in text mode.
Devices 26 built-in platforms Directives and parsers included. See Supported platforms.
Devices Any Netmiko platform Configure other SSH or Telnet platforms with custom directives.
Devices HTTP devices Query devices that expose an HTTP API instead of a CLI.
Devices SSH proxy Reach devices through a jump host.
Devices Credentials Password or private-key authentication, enable secrets and per-device driver settings.
Devices OS version awareness Set os_version so version-specific command variants are chosen and fallbacks are logged.
Devices Connection tuning Per-device timeouts, connection retries and delay factors for slow or rate-limited CLIs.
Onboarding hyperglass onboard Create, test and check devices and custom directives from the CLI. See Add a router in four commands.
Onboarding Configuration validation Hyperglass refuses to start on a device entry that is missing an attribute its directives need, and names the field.
Onboarding Inspection commands hyperglass devices, directives, plugins, params and settings print the effective configuration.
Web UI Responsive interface Location, query type and target in one form. Multiple locations per query run concurrently.
Web UI Hostname targets Resolve hostnames with Cloudflare or Google DNS-over-HTTPS, a custom resolver URL, or the Hyperglass server's own resolver.
Web UI My IP Fill the target with the visitor's address. Server-seen by default, external lookup only after the visitor confirms, or hidden.
Web UI Branding Logo, theme colours, fonts, greeting modal, footer links and menus, OpenGraph image and every label and message.
Web UI Self-hosted fonts The UI build downloads fonts so visitors never contact Google Fonts.
API REST API Every published query is available at /api/query.
API OpenAPI docs Built-in interactive documentation with configurable title, descriptions and server URL.
Access control Target rules Prefix-list and access-list style rules per directive, including reserved, loopback and unspecified address handling.
Access control Request timeouts A configurable request_timeout bounds every device connection and command.
Operations Caching Redis-backed result cache with a configurable timeout.
Operations Logging File logs, SSH session logs, syslog, and HTTP webhooks for Slack, Microsoft Teams or any generic endpoint.
Operations Query samples Opt-in JSONL capture of raw and parsed query output, with size-based rotation, for debugging and parser fixtures.
Operations Support bundle hyperglass support-bundle gathers version, runtime and allowlisted error metadata locally. It excludes configuration and free-form log text. Nothing is sent automatically.
Operations Container images Build from the included Dockerfile and Compose configuration. Community image publication and scan gates are tracked in #388.
Operations Lab A Containerlab topology under lab/ feeds real routing tables to virtual routers for regression testing.

Supported platforms

Hyperglass ships directives and parsers for these 26 platforms. Netmiko provides the device connectivity, so other Netmiko platforms work with custom directives. Set structured_output: true to enable parsed output on each supported device. Omitted, null and false settings return text on every platform, including FRR, Juniper and Arista.

Platform platform key Structured BGP Structured traceroute Built-in VRF queries Notes
Arista EOS arista_eos Yes Yes Yes
Arrcus ArcOS arrcus_arcos Yes No built-in Yes BGP route lookups only. AS path, community, ping and traceroute are not yet built in.
Aruba AOS-CX aruba_aoscx Yes Yes Yes
BIRD bird Yes Yes No
Cisco IOS and IOS XE cisco_ios Yes Yes No Router needs ip bgp-community new-format.
Cisco IOS-XR cisco_xr Yes Yes No Connection retries default to 3.
Cisco NX-OS cisco_nxos Yes Yes No
NVIDIA Cumulus Linux cumulus_linux Yes Yes Yes
Dell OS9 (Force10) dell_force10 Yes Yes Yes AS path search is IPv4 only.
Dell SmartFabric OS10 dell_os10 Yes Yes Yes
Extreme EXOS extreme_exos Yes Yes Yes
Extreme VOSS extreme_vsp Text Yes Yes
Fortinet FortiGate fortinet Yes Yes No
FRRouting frr Yes Yes Yes
HPE Comware 7 hp_comware Yes Yes Yes
Huawei VRP huawei, huawei_vrpv8 Yes Yes Yes
IP Infusion OcNOS ipinfusion_ocnos Yes Yes Yes
Juniper Junos juniper Yes Yes No
MikroTik RouterOS and SwitchOS mikrotik_routeros, mikrotik_switchos Yes Yes RouterOS only RouterOS 6 and 7. Full-table AS path and community scans can exceed 90 seconds.
Nokia SR OS nokia_sros Text Yes No
OpenBGPD openbgpd Yes Yes No
Palo Alto PAN-OS paloalto_panos Yes Yes Yes vrf names the virtual router.
SONiC sonic Yes Yes Yes
TNSR tnsr Text Yes No BGP runs through dataplane shell sudo vtysh.
VyOS 1.4+ vyos Yes Yes Yes
VyOS 1.3 vyos_1_3 Text Yes No

Platform keys, per-platform notes and known limits are in the platforms guide.

Quick start

The repository includes a sample configuration with a fake device so you can see the application before connecting a router.

Docker

git clone https://github.com/hyperglass-community/hyperglass.git --depth=1
cd hyperglass
mkdir -p /etc/hyperglass
cp .samples/sample_devices.yaml /etc/hyperglass/devices.yaml
docker compose up

Compose pulls the published image that compose.yaml pins. To build the checkout instead, run docker compose -f compose.yaml -f compose.build.yaml up --build.

Open http://localhost:8001 once the containers are up. The sample device returns fake output. Then add your first real router with hyperglass onboard device inside the container.

.samples/sample_config.yaml is a complete config.yaml that sets every option, with a comment that explains each feature. Use it as a reference when you write your own.

Manual installation

Manual installation needs Python 3.11 or later and Redis 7. Install the ui extra for the web UI, with Node.js 22.13 and pnpm 11 for the frontend build. The optional performance extra enables uvloop. The full procedure is in the manual installation guide.

Documentation

The existing documentation site and live demo describe the upstream release. Repository guides describe the migration changes.

Community

Reporting bugs

Use the bug report form. Include the Hyperglass version, deployment method, steps to reproduce, expected and observed behaviour, relevant configuration with secrets removed, and the output of hyperglass onboard test or hyperglass support-bundle. Review either before attaching it. Do not include device passwords, private keys, tokens or unredacted internal addresses.

Reporting security vulnerabilities

Do not open a public issue for a security vulnerability. Report it privately as described in SECURITY.md.

Contributing

Read CONTRIBUTING.md before opening a pull request. Changes should keep the backend and UI checks passing, preserve IPv4 and IPv6 support, and avoid hard-coding text or deployment-specific values that administrators should be able to configure.

Acknowledgements

Hyperglass was created by Matt Love as thatmattlove/hyperglass. The community project continues that work under the Clear BSD License.

CONTRIBUTORS.md names the people whose code, pull requests, reports and reviews are part of each release.

Hyperglass uses Netmiko, Litestar, Pydantic, React, Next.js, Chakra UI, React Flow, and BGP.tools.

About

hyperglass is the network looking glass that tries to make the internet better.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

799 stars

Watchers

15 watching

Forks

Releases

Packages

Used by

Contributors

Languages