Repository navigation
Releases
v3.0.0-rc.2
This release candidate replaces 3.0.0-rc.1, which was not released. Lab testing of 3.0.0-rc.1 found defects that block it.
This is a release candidate. Use it to test an upgrade from 2.0.4; do not treat it as a stable release. The image is ghcr.io/hyperglass-community/hyperglass:3.0.0-rc.2. The latest tag does not move. Report a defect as a new issue that names this version.
Hyperglass 3.0.0 incorporates the Ultraglass 3.6.2 implementation through the staged migration in #390. It adds router support, structured results, configuration controls, onboarding and runtime recovery. The Python package, CLI, configuration paths, environment variables and service names remain hyperglass. Ultraglass release numbers are separate from Hyperglass release numbers.
Upgrading from 2.0.4
Back up config.yaml, devices.yaml and directives.yaml, then read Migrating from Hyperglass 2.0.4. These changes can require a configuration change:
- Structured output requires explicit
structured_output: trueon every supported platform, including FRR, Juniper aliases and Arista. Omitted,nullandfalsesettings return text. - Forwarding headers require a trusted proxy. Configure
web.client_ip.trusted_proxieswith the actual connecting proxy addresses. Setweb.client_ip.headeronly for a single-address header that the trusted proxy overwrites; otherwise Hyperglass processesX-Forwarded-Forfrom right to left. - My IP defaults to server-side detection. It returns
nullfor non-public addresses, including private proxy addresses, without automatically contacting a public service. Selectweb.my_ip: externalexplicitly to use the external lookup, oroffto hide the control. /api/dnsand/api/aspath/enrichare disabled by default.web.dns_provider.name: serverandweb.aspath_enrichment: trueenable them.- Server DNS uses a fixed public resolver and returns public A/AAAA answers only. Internal DNS resolution is unsupported.
- The default listen address is
::1. A reverse proxy must use[::1]:8001, orHYPERGLASS_HOSTmust name another address. - Docker Compose publishes the application directly. For host nginx, set
HYPERGLASS_BIND_ADDRESS=127.0.0.1and trust the proxy address seen inside the container. Keep the container listener atHYPERGLASS_HOST=0.0.0.0. - IP rules enforce
allow_loopback,allow_reservedandallow_unspecified. These options default tofalse. Address and prefix inputs normalize before validation;192.0.2.1/24, for example, becomes192.0.2.0/24. - BIRD AS-path queries accept ASN sequences with
^,$and_. OpenBGPD AS-path queries accept one ASN. Built-in BGP targets reject command syntax. - Cisco IOS and NX-OS IPv6 BGP Route queries require a prefix no longer than
/127. - Use
vyos_1_3for legacy VyOS commands. Set deviceos_versionfor version-specific commands, including RouterOS 6 and classic IOS IPv6 traceroute. - VRF identifiers accept command-safe names or numbers. Numeric values normalize to strings; spaces and slashes remain invalid. A VRF device offers only applicable built-ins and configured custom directives.
- Python 3.11 or later and Node.js 22.13 or later are required for a manual installation.
- Docker Compose pulls the published image and runs Valkey 8 as the
redisservice. It no longer builds the checkout, sodocker compose buildhas no effect; addcompose.build.yamlfor a source build. ExistingHYPERGLASS_REDIS_*settings keep their meaning, and the bundled cache starts empty. - The automatic worker count follows CPU affinity and the container CPU quota, and stops at eight. Set
HYPERGLASS_WORKERSto keep a higher count. - Custom directives quote substituted arguments on shell-backed platforms. Review templates that depend on shell expansion or that split one target into several arguments.
Security
- Reject control characters and line separators in query targets, including targets accepted by custom directives. Restrict IPv6 zone identifiers to letters, digits and hyphens before command construction (#392). Part of #383.
- Validate built-in directive targets again at the command boundary and quote shell-backed built-in arguments after target substitution (#393).
- Quote custom-directive arguments on shell-backed platforms, including fallback and VRF commands (#407).
- Limit the server DNS and ASN lookup endpoints with shared Redis request quotas, caches, concurrency leases and deadlines. Both endpoints are off by default; server DNS rejects non-public answers (#399).
- Read forwarding headers only from the proxies in
web.client_ip.trusted_proxies(#399). - Filter ArcOS BGP Route responses to the requested exact prefix in both text and structured modes. The device command still retrieves the full BGP instance. Malformed or incomplete responses return a parsing error instead of raw device output (#401).
- Support bundles export metadata only. They no longer include free-form messages or exception values (#402).
- Update Python, frontend and container dependencies from the migrated baseline, including patched image packages and transitive frontend dependencies (#394, #395).
Added
- Structured BGP tables and traceroute results across supported router platforms, with route attributes, hop timing and loss, communities and AS-path visualization. BGP stays text on platforms with traceroute-only structured support. See the platform reference for per-platform capabilities (#398, #400, #401).
- Built-in directives for
aruba_aoscx,arrcus_arcos,cumulus_linux,dell_force10,dell_os10,extreme_exos,extreme_vsp,fortinet,hp_comware,ipinfusion_ocnos,paloalto_panos,sonicandvyos_1_3(#400, #401). - VRF queries through built-in directives and device
vrfsettings (#397). - Named directive variables with fixed choices, required fields and optional command fragments. Selected values participate in query cache identity (#293, #397).
- Device
os_version, rulefallback_commandandfallback_os_versionsettings for version-specific commands and fallback after a device rejects the primary command (#397). - Named BGP communities through
structured.communities.mode: nameandnames, preserving unmatched community values (#313). - Routinator as an external RPKI backend, alongside Cloudflare, with batched validation and provider-aware caches (#398).
- Optional BGP and traceroute IP/ASN enrichment, inline or asynchronous. Global controls can disable structured BGP or traceroute independently (#398, #399).
- Mixed-vendor query selection, directive-variable controls and server-side DNS resolution in the UI (#174, #270, #399).
- The
hyperglass onboardcommand, which creates and tests device entries, checks feature settings and scaffolds custom directives (#402). - Support bundle export for defect reports (#402).
- Connection retry, readiness checks and state recovery for device transports (#396).
HYPERGLASS_WORKERSto set an explicit worker count, deviceconnect_retriesto control SSH connection retries, anddisable_paging: falseto suppress driver paging commands (#338, #396). Automatic sizing respects affinity and visible cgroup quotas, including inherited limits, and caps the worker count at eight, so a container on a high-core host no longer starts enough workers to exhaust its memory (#356, #357).- Optional SSH session logs and rotating JSONL query samples containing selected raw and parsed output. Both are disabled by default ([#336](https://github.com/hyperglass-community/hyperglass/issues/...
v2.0.4
2.0.4 - 2024-06-30
Fixed
- #264: Fixed issue where IPv6 traceroutes fail on Juniper devices due to
traceroute: wait must be >1 sec.error. Thanks @renatoornelas! - #267: Fixed issue where responses were incorrectly cached, resulting in no data being shown in the AS Path viewer.
- #268: Fixed issue where some Mikrotik commands failed to execute properly.
- #269: Updated documentation regarding
structured.rpki.mode. - Removed unnecessary logging statements which caused logging errors.
- Fixed issue where validation of structured BGP route data may have failed under certain conditions.
Changed
- Error responses are no longer cached.
v2.0.3
2.0.3 - 2024-06-16
Fixed
- #262: Fix issue where Mikrotik output was improperly parsed and displayed an error as a result.
- Fixed issue where incorrect error styles were displayed.
- Fixed issue where 'results' accordion component did not re-open when closed.
- Fixed issue where pattern-based directive rules failed validation.
Changed
- Set default logo width (back) to 50%, adjusted how the
web.logo.widthsetting is handled in the UI.
v2.0.2
2.0.2 - 2024-06-01
Fixed
- #257: Fix issue where if
web.location_display_modeis set todropdown(automatically or otherwise), the menu would remain open but become detached from the main element because the Query Type element came into view. - #253: Actually fix issue where configuration values were improperly prepended with the
HYPERGLASS_APP_PATHvalue. - #258: Center logo alignment on small screens.
- Fix broken license link in default credit menu.
Added
- Added license to docs.
- #254: Users may specify their own DNS over HTTPS provider if desired.
v2.0.1
2.0.1 - 2024-05-31
Fixed
- #244: Fix issue with UI build where UI build directory already existed and therefore could not be created.
- #249: Fix issue where configuration values were improperly prepended with the
HYPERGLASS_APP_PATHvalue. - #251: Fix issue where browser-based DNS resolution did not show, causing FQDN queries to fail due to validation.
- Fix issue where logo was improperly sized on small screens.
v2.0.0
2.0.0 - 2024-05-28
v2.0.0 is a major release of hyperglass. Many things have changed, and it is likely best to redeploy hyperglass in a new environment to migrate to v2.
Added
- Commands are now defined as directives, which is a configuration definition of one or more commands to run on a device. A directive defines:
- What command (or commands) to run on the device
- Type of UI field, text input or select
- If the field can accept multiple values
- Help information to show about the directive
- Validation rules
- hyperglass now supports Docker, and using Docker is the default and recommended method for deployment.
- The list of locations (devices) is displayed as a gallery when the number of devices is 5 or less. This is a default value and is configurable.
- hyperglass now supports custom input or output plugins.
- Input Plugins: Apply custom validation logic or transform user input before the query is sent to a device.
- Output Plugins: Interact with the output from a device before it's displayed to the user.
- #206: OpenBGPD is natively supported by hyperglass.
- #176: Custom javascript or HTML can be injected into the web page (for tracking applications such as Google Analytics).
- #173: Any output, such as BGP Communities, can be highlighted in the UI by defining highlight patterns.
- #155: A user can now use the "My IP" button to insert their own IP into the query target field.
- #143: Any HTTP endpoint may be configured as device from which to collect output.
Fixed
v1.0.4
Fixed
- #148: Update Debian/Ubuntu Python package name in installer and documentation.
- #151: Fix issue with Junos structured output parsing from d1160fe where hyperglass would always query both IPv4 and IPv6 for any query type.
Changed
- Improve handling of Junos XML errors. When a Junos device returns an error in the XML output, it will be displayed in the UI.
- Improve
hyperglass system-infooutput. NodeJS version is now included in the output.
v1.0.3
1.0.3 is a cosmetic release to factor in code-level changes related to the repository name change from checktheroads to thatmattlove.
v1.0.2
Fixed
- #150: Fix handling of BIRD AS_PATH/Community targets.