DOCSEARCHbyAlgolia
Submit Docs

hyperglass

repository·main·Indexed 20 days ago

https://github.com/thatmattlove/hyperglass

A modern network looking glass platform (version 2.0.4) that enables network operators to provide diagnostic tools such as BGP queries, Ping, and Traceroute to users. It features a React-based web UI built with Next.js and Chakra UI, a REST API with OpenAPI documentation, and support for major network operating systems including Arista EOS, BIRD, Cisco, FRRouting, Huawei VRP, Juniper Junos, Mikrotik, Nokia SR OS, OpenBGPD, TNSR, and VyOS.

Tokens
20.8K
Snippets
71
Records
106
Agent score
73%

What's inside hyperglass

  1. What is hyperglass?

    main
    hyperglass is an open source network looking glass designed for network engineers. It provides unattended visibility into an operator's network for customers, peers, and other network operators. It is designed to be a faster, easier, and more secure way to provide looking glass services.

  2. Overview of Hyperglass features

    main

    Hyperglass is a network looking glass platform designed to allow network operators to provide customers, peers, or the public with tools to view network elements or run tests from their network.

    Key capabilities include:

    • Network Tests: BGP Route, BGP Community, BGP AS Path, Ping, and Traceroute. You can also add custom commands via configuration directives.
    • Protocol Support: Full IPv6 support.
    • Multi-Device Queries: Ability to query multiple devices simultaneously.
    • Platform Support: Built-in support for major network operating systems including Arista EOS, BIRD, Cisco (IOS, NX-OS, IOS-XR), FRRouting, Huawei VRP, Juniper Junos, Mikrotik, Nokia SR OS, OpenBGPD, TNSR, and VyOS.
    • Security & Control: Access-list/prefix-list style query control to whitelist or blacklist query targets, and optional access via an SSH proxy/jump server.
    • Extensibility: Highly customizable features, themes, UI/API text, error messages, and commands.
    • API & UI: Provides a REST API with automatic OpenAPI documentation and a modern, responsive React-based UI (using NextJS and Chakra UI).

  3. Overview of hyperglass-ui

    main

    The hyperglass-ui package provides the user interface for Hyperglass. It is built using the following technology stack:

    • React: For building the component-based UI.
    • Next.js: As the underlying framework for routing and rendering.
    • Chakra UI: For the design system and component styling.

  4. Key features of hyperglass

    main

    hyperglass provides a wide range of network diagnostic and management features, including:

    • Network Diagnostics: BGP Route, BGP Community, BGP AS Path, Ping, and Traceroute.
    • Protocol Support: Full IPv6 support.
    • Customization: Highly customizable features, themes, UI/API text, error messages, and commands.
    • Platform Support: Built-in support for various network platforms and configurable support for others.
    • Connectivity: Optional access to devices via an SSH proxy/jump server.
    • Network Isolation: VRF support and Access List/prefix-list style query control to whitelist or blacklist query targets on a per-VRF basis.
    • API & UI: REST API with automatic, configurable OpenAPI documentation and a modern, responsive UI.
    • Advanced Querying: Ability to query multiple devices simultaneously and browser-based DNS-over-HTTPS resolution of FQDN queries.

  5. What is a directive in Hyperglass?

    main

    A directive is a configuration that defines how one or more commands should be executed on a device in response to a query. It acts as a bridge between a user's query and the actual device commands.

    A directive defines:

    • The specific command(s) to run on the device.
    • The type of UI fields (text input or select) required for the query.
    • Whether the command supports multiple values.
    • Help information and validation rules for the input.
    • How the directive is grouped in the UI.

  6. What are hyperglass Plugins and how do they work

    main

    Starting in version 2.0, hyperglass supports custom plugins that are associated with a directive. Plugins allow you to intercept and modify the lifecycle of a query at two specific stages:

    1. Input Plugins: These run before the query is sent to a device. They can be used to apply custom validation logic to the user input or to transform the input (e.g., converting a CIDR prefix into a network and mask).
    2. Output Plugins: These run after the device returns data but before it is displayed to the user. They are useful for tasks like redacting sensitive information from the output text.

    To use a plugin, you must define a class that inherits from either InputPlugin or OutputPlugin and then reference the file path of that plugin within your directives.yaml configuration under the plugins key for a specific directive.

  9. Define directive rules and actions

    main

    A rule determines if a query target matches specific conditions to trigger a command. If a rule matches, the specified action (permit or deny) is applied.

    Rule Parameters

    ParameterTypeDefaultDescription
    conditionStringA regex pattern or an IP prefix to match against.
    actionStringpermitEither permit or deny the directive target.
    commandsList of StringsCommands to run. {target} is replaced by the query target.

    Validation Types

    IP Rule Validation

    When the condition is an IP prefix, you can use these parameters to control prefix length matching:

    • ge: Minimum prefix length (e.g., 8).
    • le: Maximum prefix length (e.g., 24).
    • allow_reserved: Allow RFC1918, etc. (default false).
    • allow_unspecified: Allow 0.0.0.0 or :: (default false).
    • allow_loopback: Allow 127.0.0.0/8 or ::1 (default false).

    Regex Validation

    To validate input using a regular expression, provide the pattern as the condition string.

    No Validation

    To allow any input to pass through to the command, set the condition to null.

    your-directive:
    name: BGP Route
    rules:
        - condition: "192.0.2.0/24"
          action: deny
        - condition: "0.0.0.0/0"
          command: "show ip bgp {target}"

  10. Understand Hyperglass configuration files

    main

    Hyperglass uses three primary configuration files to manage application behavior, device data, and custom commands:

    • config: Manages application-wide settings such as logging, web UI customization (logos, colors), and other global parameters.
    • devices: Contains the list of your devices and their specific associated configurations.
    • directives: Defines custom directives (commands) used to interact with devices.

    While documentation examples typically use YAML, Hyperglass also supports TOML, JSON, and Python files.

  11. Understand platform support in hyperglass

    main

    hyperglass uses Netmiko for SSH/telnet device interaction. While any platform supported by Netmiko can technically be used, hyperglass only provides built-in directives for a specific subset of platforms.

    If you use a Netmiko-supported platform that is not explicitly listed in the hyperglass built-in directives, you must add a custom directive for every command you want to expose to the system.

  12. Quickstart hyperglass with sample devices

    main

    If you want to quickly preview the hyperglass interface using fake device data, use the provided sample configuration and run Docker Compose.

    1. Copy the sample devices configuration to /etc/hyperglass/devices.yaml.
    2. Run docker compose up from the /opt/hyperglass directory.
    3. Access the interface at http://localhost:8001.
    cp /opt/hyperglass/.samples/sample_devices.yaml /etc/hyperglass/devices.yaml
cd /opt/hyperglass
docker compose up