witine/lookingglass
1
0
Fork 0
forked from mirrors/thatmattlove-hyperglass
Code Issues Pull requests Releases Activity
lookingglass/docs/pages/configuration/config.mdx
thatmattlove 847e55098b update docs & examples
2024-03-20 00:57:11 -04:00

194 lines
14 KiB
Text
Raw Blame History

The `config.yaml` file is broken into multiple sections:
# Global
Top level parameters:
| Parameter | Type | Default Value | Description |
| :----------------- | :-------------- | :------------------------------- | :------------------------------------------------------------ |
| `org_name` | String | Beloved Hyperglass User | Your organization's name. |
| `plugins` | List of Strings | | List of hyperglass [plugins](/plugins) to load. |
| `primary_asn` | String | 65000 | Your organization's primary ASN. Used to set default UI text. |
| `request_timeout` | Number | 90 | Global timeout in seconds for all requests. |
| `site_description` | String | `org_name` Network Looking Glass | `<meta>` description, also used in the API documentation. |
| `site_title` | String | `org_name` | Browser title, also used in the default terms & conditions. |
#### Example with Defaults
```yaml filename="config.yaml"
org_name: Beloved Hyperglass User
plugins: []
primary_asn: 65000
request_timeout: 90
site_description: Beloved Hyperglass User Network Looking Glass
site_title: Beloved Hyperglass User
```
## Cache
hyperglass relies on [Redis](https://redis.io/) as an in-memory key/value store for configuration management and request/response caching. If Redis is already [installed](/installation) on your system, you should only need to set these parameters if you need to customize how hyperglass connects to Redis.
| Parameter | Type | Default Value | Description |
| :--------------- | :----- | :------------ | :----------------------------- |
| `cache.host` | String | localhost | Redis IP address or hostname. |
| `cache.port` | Number | 6379 | Redis TCP port. |
| `cache.database` | Number | 1 | Redis database number (0-15). |
| `cache.password` | String | | Redis password, if one is set. |
#### Example with Defaults
```yaml filename="config.yaml"
cache:
host: localhost
port: 6379
database: 1
password: null
```
## Docs
Behind the scenes, hyperglass uses [FastAPI](https://fastapi.tiangolo.com/), which automatically generates documentation for the hyperglass REST API. The `docs` section allows users to customize the look, feel, and text used for the REST API documentation.
| Parameter | Type | Default Value | Description |
| :----------------- | :------ | :----------------------------- | :---------------------------------------------------------------------------------------------- |
| `docs.base_url` | String | https://lg.example.com | Used for REST API samples. See the [demo](https://demo.hyperglass.dev/api/docs) for an example. |
| `docs.enable` | Boolean | `true` | Enable or disable the REST API documentation. |
| `docs.mode` | String | redoc | FastAPI supports two UI libraries/themes for autogenerated docs: `redoc` and `swagger`. |
| `docs.path` | String | /api/docs | Path to the REST API documentation. |
| `docs.title` | String | `site_title` API Documentation | API docs title. Uses the `site_title` parameter from the [global](#global) parameters. |
| `docs.description` | String | | API docs description. Appears below the title. |
The documentation for API endpoints follow a common schema:
- `devices`
- `info`
- `queries`
- `query`
### Schema
| Parameter | Type | Description |
| :------------ | :----- | :------------------------------------------------------------------------------- |
| `title` | String | API endpoint title, displayed as the header text above the API endpoint section. |
| `description` | String | API endpoint description, displayed inside each API endpoint section. |
| `summary` | String | API endpoint summary, displayed beside the API endpoint path. |
### Parameters
| Parameter | Default Value |
| :------------------------- | :------------------------------------------------------------------------------------------ |
| `docs.devices.title` | Devices |
| `docs.devices.description` | List of all devices/locations with associated identifiers, display names, networks, & VRFs. |
| `docs.devices.summary` | Devices List |
| `docs.info.title` | System Information |
| `docs.info.description` | General information about this looking glass. |
| `docs.info.summary` | System Information |
| `docs.queries.title` | Supported Queries |
| `docs.queries.description` | List of supported query types. |
| `docs.queries.summary` | Query Types |
| `docs.query.title` | Supported Query |
| `docs.query.description` | Request a query response per-location. |
| `docs.query.summary` | Query the Looking Glass |
#### Example with Defaults
```yaml filename="config.yaml"
docs:
base_url: https://lg.example.com
enable: true
mode: redoc
path: /api/docs
title: Beloved Hyperglass User Looking Glass API Documentation
description: null
# API Endpoints ↓
devices:
title: Devices
description: List of all devices/locations with associated identifiers, display names, networks, & VRFs.
summary: Devices List
info:
title: System Information
description: General information about this looking glass.
summary: System Information
queries:
title: Supported Queries
description: List of supported query types.
summary: Query Types
query:
title: Supported Query
description: Request a query response per-location.
summary: Query the Looking Glass
```
## Messages
hyperglass provides as much control over user-facing text/messages as possible. The following messages may be adjusted as needed:
| Parameter | Type | Default Value | Description |
| :------------------------------ | :----- | :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages.authentication_error` | String | Authentication error occurred. | Displayed when hyperglass is unable to authenticate to a device. Usually, this indicates a configuration error. |
| `messages.connection_error` | String | Error connecting to \{device_name\}: \{error\} | Displayed when hyperglass is unable to connect to a device. Usually, this indicates a configuration error. `{device_name}` and `{error}` will be used to display the device in question and the specific connection error. |
| `messages.general` | String | Something went wrong. | Displayed when errors occur that hyperglass didn't anticipate or handle correctly. Seeing this error message may indicate a bug in hyperglass. If you see this in the wild, try enabling [debug mode](#global) and review the logs to pinpoint the source of the error. |
| `messages.invalid_input` | String | \{target\} is not valid. | Displayed when a query target's value is invalid in relation to the corresponding query type. `{target}` will be used to display the invalid target. |
| `messages.invalid_query` | String | \{target\} is not a valid \{query_type\} target. | Displayed when a query target's value is invalid in relation to the corresponding query type. `{target}` and `{query_type}` may be used to display the invalid target and corresponding query type. |
| `messages.no_input` | String | \{field\} must be specified. | Displayed when a required field is not specified. `{field}` will be used to display the name of the field that was omitted. |
| `messages.no_output` | String | The query completed, but no matching results were found. | Displayed when hyperglass can connect to a device and execute a query, but the response is empty. |
| `messages.not_found` | String | \{type\} '\{name\}' not found. | Displayed when an object property does not exist in the configuration. `{type}` corresponds to a user-friendly name of the object type (for example, 'Device'), `{name}` corresponds to the object name that was not found. |
| `messages.request_timeout` | String | Request timed out. | Displayed when the [`request_timeout`](#global) time expires. |
| `messages.target_not_allowed` | String | \{target\} is not allowed. | Displayed when a query target is implicitly denied by a configured rule. `{target}` will be used to display the denied query target. |
##### Example
```yaml filename="config.yaml"
message:
general: Something with wrong.
```
## 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:
- Juniper Junos
- Arista EOS
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
2. From the perspective of [Cloudflare's RPKI Service](https://rpki.cloudflare.com/)
Additionally, hyperglass provides the ability to control which BGP communities are shown to the end user.
| Parameter | Type | Default Value | Description |
| :---------------------------- | :-------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------- |
| `structured.rpki` | String | router | Use `router` to use the router's view of the RPKI state (1 above), or `external` to use Cloudflare's view (2 above). |
| `structured.communities.mode` | String | deny | Use `deny` to deny any communities listed in `structured.communities.items`, or `permit` to _only_ permit communities listed. |
| `structured.communities.items | List of Strings | | |
#### Community Filtering Examples
##### Deny Listed Communities by Regex pattern
```yaml filename="config.yaml"
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"
structured:
communities:
mode: permit
items:
- '^65000:.*$' # permit any communities starting with 65000, but no others.
- '1234:1' # permit only the 1234:1 community.
```
### Caveats
#### Arista EOS
For whatever reason, Arista EOS does not supply certain details about routes in its JSON output when running commands `show ip bgp regex <pattern>` or `show ip bgp community <community>`. Specifically, the the route's timestamp and any attached communities are not supplied. When these commands are used with Arista EOS, hyperglass sets the timestamp to the current time, and the community to an empty list.
Reference in a new issue View git blame Copy permalink