mirror of
https://github.com/thatmattlove/hyperglass.git
synced 2026-04-17 21:38:27 +00:00
eabd98b606
- Add new 'name' mode for BGP communities to append friendly names - New configuration option `structured.communities.mode: name` - Community mappings via `structured.communities.names` dictionary - Communities display as "65000:1000 - Upstream Any" in UI - Backward compatible with existing permit/deny modes - Enhance RPKI configuration documentation - Document both Cloudflare and Routinator backend options - Add `structured.rpki.backend` and `structured.rpki.rpki_server_url` parameters - Clarify Routinator web API endpoint usage vs RTR port - Add comprehensive configuration examples - Update structured output platform support - Document all supported platforms: Arista EOS, FRRouting, Huawei VRP, Juniper Junos, Mikrotik RouterOS/SwitchOS - Frontend enhancements - Parse comma-separated community format in UI components - Display friendly names alongside community codes - Maintain existing functionality for communities without names - Add validation and examples - Validate that 'name' mode has community mappings configured - Include example configuration and test cases - Generic examples using ASN 65000 instead of specific networks
106 lines
4.7 KiB
Text
106 lines
4.7 KiB
Text
import { Callout } from "nextra/components";
|
||
|
||
## Structured
|
||
|
||
Devices that support responding to a query with structured or easily parsable data can have their response data placed into an easier to read table (or JSON, when using the REST API). Currently, the following platforms have structured data supported in hyperglass:
|
||
|
||
- Arista EOS
|
||
- FRRouting
|
||
- Huawei VRP
|
||
- Juniper Junos
|
||
- Mikrotik RouterOS/SwitchOS
|
||
|
||
When structured output is available, hyperglass checks the RPKI state of each BGP prefix returned using one of two methods:
|
||
|
||
1. **From the router's perspective** - Uses the RPKI validation state as determined by the router itself
|
||
2. **From an external RPKI validation service** - Queries an external service to determine RPKI state independently
|
||
|
||
For external validation, hyperglass supports two backends:
|
||
- **Cloudflare**: Uses [Cloudflare's public RPKI service](https://rpki.cloudflare.com/) via GraphQL API
|
||
- **Routinator**: Connects to your own [Routinator](https://github.com/NLnetLabs/routinator) RPKI validator instance
|
||
|
||
Additionally, hyperglass provides the ability to control which BGP communities are shown to the end user.
|
||
|
||
| Parameter | Type | Default Value | Description |
|
||
| :----------------------------- | :-------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `structured.rpki.mode` | String | router | Use `router` to use the router's view of the RPKI state, or `external` to use an external validation service. |
|
||
| `structured.rpki.backend` | String | cloudflare | When using `external` mode, choose `cloudflare` or `routinator` as the validation backend. |
|
||
| `structured.rpki.rpki_server_url` | String | | When using `routinator` backend, specify the base URL of your Routinator server (e.g., `http://rpki.example.com:3323`). |
|
||
| `structured.communities.mode` | String | deny | Use `deny` to deny any communities listed, `permit` to _only_ permit communities listed, or `name` to append friendly names. |
|
||
| `structured.communities.items` | List of Strings | | List of communities to match (used by `deny` and `permit` modes). |
|
||
| `structured.communities.names` | Dict | | Dictionary mapping BGP community codes to friendly names (used by `name` mode). |
|
||
|
||
### RPKI Examples
|
||
|
||
#### Show RPKI State from the Device's Perspective
|
||
|
||
```yaml filename="config.yaml" copy {2}
|
||
structured:
|
||
rpki:
|
||
mode: router
|
||
```
|
||
|
||
#### Show RPKI State from Cloudflare's Public Service
|
||
|
||
```yaml filename="config.yaml" copy {2-4}
|
||
structured:
|
||
rpki:
|
||
mode: external
|
||
backend: cloudflare
|
||
```
|
||
|
||
#### Show RPKI State from a Custom Routinator Server
|
||
|
||
```yaml filename="config.yaml" copy {2-5}
|
||
structured:
|
||
rpki:
|
||
mode: external
|
||
backend: routinator
|
||
rpki_server_url: "http://rpki.example.com:8080"
|
||
```
|
||
|
||
<Callout type="info" emoji="ℹ️">
|
||
**Routinator URL Format**
|
||
|
||
The `rpki_server_url` should be the base URL of your Routinator HTTP web API endpoint. This is typically different from the RTR port (3323). The URL should not include the `/validity` path as hyperglass will append this automatically.
|
||
</Callout>
|
||
|
||
### Community Filtering Examples
|
||
|
||
#### Deny Listed Communities by Regex pattern
|
||
|
||
```yaml filename="config.yaml" {5-6}
|
||
structured:
|
||
communities:
|
||
mode: deny
|
||
items:
|
||
- '^65000:1\d+$' # don't show any communities starting with 65000:1. 65000:1234 would be denied, but 65000:4321 would be permitted.
|
||
- "65000:2345" # don't show the 65000:2345 community.
|
||
```
|
||
|
||
#### Permit only Listed Communities
|
||
|
||
```yaml filename="config.yaml" {5-6}
|
||
structured:
|
||
communities:
|
||
mode: permit
|
||
items:
|
||
- "^65000:.*$" # permit any communities starting with 65000, but no others.
|
||
- "1234:1" # permit only the 1234:1 community.
|
||
```
|
||
|
||
#### Append Friendly Names to Communities
|
||
|
||
```yaml filename="config.yaml" {2-10}
|
||
structured:
|
||
communities:
|
||
mode: name
|
||
names:
|
||
"65000:1000": "Upstream Any"
|
||
"65000:1001": "Upstream A (all locations)"
|
||
"65000:1101": "Upstream A Location 1"
|
||
"65000:1201": "Upstream A Location 2"
|
||
"65000:1002": "Upstream B (all locations)"
|
||
"65000:1102": "Upstream B Location 1"
|
||
"65000:2000": "IXP Any"
|
||
```
|