mirror/checktheroads-hyperglass
1
0
Fork 0
mirror of https://github.com/checktheroads/hyperglass synced 2024-05-11 05:55:08 +00:00
Code Releases Activity
Files
fc3ba3a8bedadd3c74cbe32b71c1aa74f48621db
checktheroads-hyperglass/docs/pages/configuration/reference/config.yaml.mdx

578 lines
37 KiB
Plaintext
Raw Normal View History

clean up unused parameters and start work on 2.0.0 docs
2022-12-12 18:52:39 -05:00
import { Callout } from 'nextra-theme-docs';
import { Color } from '../../../components/color';
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 |
| :--------- | :----- | :------------ | :----------------------------- |
| `host` | String | localhost | Redis IP address or hostname. |
| `port` | Number | 6379 | Redis TCP port. |
| `database` | Number | 1 | Redis database number (0-15). |
| `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 |
| :------------ | :------ | :----------------------------- | :---------------------------------------------------------------------------------------------- |
| `base_url` | String | https://lg.example.com | Used for REST API samples. See the [demo](https://demo.hyperglass.dev/api/docs) for an example. |
| `enable` | Boolean | `true` | Enable or disable the REST API documentation. |
| `mode` | String | redoc | FastAPI supports two UI libraries/themes for autogenerated docs: `redoc` and `swagger`. |
| `path` | String | /api/docs | Path to the REST API documentation. |
| `title` | String | `site_title` API Documentation | API docs title. Uses the `site_title` parameter from the [global](#global) parameters. |
| `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
```
## Logging
Console, file, HTTP, and/or syslog logging configuration.
| Parameter | Type | Default Value | Description |
| :---------- | :----- | :------------ | :---------------------------------------------- |
| `directory` | String | /tmp | Path to directory where logs will be created. |
| `format` | String | text | Log text format, must be `text` or `json`. |
| `max_size` | String | 50MB | Maximum log file size before being overwritten. |
### Syslog
| Parameter | Type | Default Value | Description |
| :-------- | :----- | :------------ | :---------------------- |
| `host` | String | | Syslog target host. |
| `port` | Number | 514 | Syslog target UDP port. |
##### Syslog Example
```yaml filename="config.yaml"
logging:
syslog:
host: log.example.com
port: 514
```
### HTTP Logging
If enabled, logs will be sent by HTTP `POST` method.
| Parameter | Type | Default Value | Description |
| :----------- | :------ | :------------ | :---------------------------------------------- |
| `provider` | String | generic | Must be `generic`, `msteams`, or `slack`. |
| `host` | String | | URL |
| `headers` | Map | | |
| `params` | Map | | |
| `verify_ssl` | Boolean | true | Enable or disable SSL certificate verification. |
| `timeout` | Number | 5 | HTTP connection timeout in seconds. |
#### Authentication
Authentication is supported using HTTP basic authentication or an API key.
| Parameter | Type | Default Value | Description |
| :----------------------------- | :----- | :------------ | :--------------------------------------------------------------------------------------------------------- |
| `http.authentication.mode` | String | basic | Must be `basic` or `api_key`. |
| `http.authentication.username` | String | | Basic authentication username if `mode` is set to `basic`. |
| `http.authentication.password` | String | | Basic authentication password if `mode` is set to `basic`, or API key value if `mode` is set to `api_key`. |
| `http.authentication.header` | String | X-API-Key | Header name if `mode` is set to `api_key`. |
#### HTTP Logging Examples
##### Generic
```yaml filename="config.yaml"
logging:
http:
provider: generic
host: https://httpbin.org
headers:
x-special-header: super special header value
params:
source: hyperglass
verify_ssl: true
timeout: 5
authentication:
mode: basic
username: your username
password: super secret password
```
In the above example, hyperglass will send a `POST` request to `https://httpbin.org?source=hyperglass` with Basic Authentication headers set.
##### Microsoft Teams Webhook
```yaml filename="config.yaml"
logging:
http:
provider: msteams
host: <MS Teams webhook URL>
```
##### Slack
```yaml filename="config.yaml"
logging:
http:
provider: slack
host: <Slack webhook URL>
```
## 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.
## Web
hyperglass provides extensive customization options for the look and feel of the web UI.
| Parameter | Type | Default Value | Description |
| :-------------------------- | :----- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `web.location_display_mode` | String | auto | Show the locations field as a `dropdown`, `gallery`. When using `auto`, if there are more than 5 location groups, `dropdown` will be used. |
| `web.custom_javascript` | String | | Path to a javascript file that will be loaded with the website. |
| `web.custom_html` | String | | Path to a custom HTML file that will be loaded with the website and rendered beneath the app. |
### DNS over HTTPS
[DNS over HTTPS](https://www.rfc-editor.org/rfc/rfc8484) is used to look up an FQDN query target from the perspective of the user's browser.
| Parameter | Type | Default Value | Description |
| :------------------ | :----- | :------------ | :-------------------------------------- |
| `dns_provider.name` | String | cloudflare | Cloudflare or Google DNS are supported. |
### Logo
| Parameter | Type | Default Value | Description |
| :----------------- | :--------------- | :------------ | :------------------------------------------------- |
| `web.logo.light` | String | | Path to logo to show in light mode. |
| `web.logo.dark` | String | | Path to logo to show in dark mode. |
| `web.logo.favicon` | String | | Path to icon/logo from which to generate favicons. |
| `web.logo.width` | Number or String | 100% | Width of logo, either as pixels or a percentage. |
| `web.logo.height` | Number or String | | Height of logo, either as pixels or a percentage. |
##### Example
```yaml filename="config.yaml"
web:
logo:
light: /path/to/light-logo.svg
dark: /path/to/dark-logo.svg
favicon: /path/to/favicon.svg
width: 100%
height: null
```
### Greeting
The greeting is an optional modal/popup window that will present itself to users in the Web UI. It can be used for anything you want; for example:
- A data privacy acknowledgement that must be acknowledged prior to proceeding
- Information about your company
- Instructions on how to use hyperglass
| Parameter | Type | Default Value | Description |
| :---------------------- | :------ | :------------ | :--------------------------------------------------------------------------------------------------- |
| `web.greeting.enable` | Boolean | False | Enable or disable the greeting. |
| `web.greeting.file` | String | | Path to markdown or plain text file that contains greeting content. |
| `web.greeting.title` | String | Welcome | Text to be used as the greeting title. |
| `web.greeting.button` | String | Continue | Text to be used for the button that acknowledges/closes the greeting. |
| `web.greeting.required` | Boolean | False | If `true`, users cannot close the modal or run any queries until the greeting has been acknowledged. |
##### Example
```yaml filename="config.yaml"
web:
greeting:
enable: true
file: /path/to/your/file.md
title: Welcome
button: Continue
required: false
```
### OpenGraph
[OpenGraph](https://ogp.me/) is the thing that generates the pretty pictures, titles, and descriptions for links when you post them to sites/tools such as Facebook, Twitter, Slack, etc. By default, [this Opengraph image](/opengraph.jpg) is used, but you can provide your own image. You don't need to worry about sizing or formatting it properly, hyperglass will handle this for you.
| Parameter | Type | Default Value | Description |
| :-------------------- | :----- | :------------ | :---------------------------- |
| `web.opengraph.image` | String | | Path to your OpenGraph image. |
### Highlighting
hyperglass can highlight special values in your router output and provide users with additional information about the content. For example, your organization's BGP communities or IP address space can be visually highlighted, and a tooltip can be shown when a user hovers over the highlighted value.
Each value you wish to be highlighted is defined with the following schema:
| Parameter | Type | Default Value | Description |
| :-------- | :----- | :------------ | :------------------------------------------------------ |
| `pattern` | String | | RegEx pattern or string to match against router output. |
| `label` | String | | Tooltip value when the highlighted text is hovered. |
| `color` | String | | Color name from [`web.theme.colors`](#colors). |
##### Example
```yaml filename="config.yaml"
web:
highlight:
- pattern: '65000:1234'
label: Special snowflake community that does a thing
color: primary
- pattern: '^192\.0\.2\.[0-9]+$'
label: Magical IP Address
color: blue
```
### Menus
hyperglass can show completely-customizable menus in the footer. Each menu can be configured with the following schema:
| Parameter | Type | Default Value | Description |
| :-------- | :----- | :------------ | :------------------------------------------------------------------------------------------------------------------------- |
| `title` | String | | Menu title, will be the text that shows on footer. |
| `content` | String | | Plain text or markdown content of the menu or path to a file that contains plain text or markdown content. |
| `side` | String | left | Side of the footer with which the menu will be grouped. |
| `order` | Number | 0 | Optionally specify an order for each menu item. If not specified, menus will be rendered in the order they are configured. |
##### Example
```yaml filename="config.yaml"
web:
menus:
- title: Terms & Conditions
content:
| **Don't** break stuff!
_please_
side: right
order: 1
- title: Help
content: /path/to/help/file.md
side: left
order: 0
```
### Links
hyperglass can show customizable links to anything you think your users might find helpful. Each link can be configured with the following schema:
| Parameter | Type | Default Value | Description |
| :---------- | :------ | :------------ | :-------------------------------------------------------------------------------------------------------------------- |
| `title` | String | | Link text. |
| `url` | String | | Link URL. |
| `show_icon` | Boolean | True | If `true`, an icon indicating the link is an external link is shown. |
| `side` | String | left | Side of the footer with which the link will be grouped. |
| `order` | Number | 0 | Optionally specify an order for each link. If not specified, links will be rendered in the order they are configured. |
##### Example
```yaml filename="config.yaml"
web:
links:
- title: PeeringDB
url: https://www.peeringdb.com/65000
show_icon: true
side: right
order: 1
- title: Our Website
url: https://example.com
show_icon: false
side: left
order: 0
```
### Credit
| Parameter | Type | Default | Description |
| :-------- | :-----: | :-----: | :--------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the display of developer credit & link to hyperglass GitHub repository |
<Callout>
**Note from the Developer**
<br /> If your organization's policy allows, and you don't mind, I request that you keep `credit` enabled.
Remember: my goal for this project is get more networks to use looking glasses to make all of our lives
easier. Because it's primarily other network operators who will use this tool to begin with, I'd love
for any operators that use your looking glass to know where they can get their own.
</Callout>
### Text
Most of the text in the hyperglass UI can be overridden to suit your needs.
| Parameter | Type | Default Value | Description |
| :--------------------------- | :----- | :------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `web.text.title_mode` | String | logo_only | See [title mode section](#title-mode) |
| `web.text.title` | String | hyperglass | Title text. |
| `web.text.subtitle` | String | Network Looking Glass | Subtitle text. |
| `web.text.query_location` | String | Location | Text used to label the query location (router) field. |
| `web.text.query_type` | String | Query Type | Text used to label the query type (directive) field. |
| `web.text.query_target` | String | Target | Text used to label the query target field. |
| `web.text.fqdn_tooltip` | String | Use \{protocol\} | Tooltip text used when a user hovers over the FQDN tooltip. |
| `web.text.fqdn_message` | String | Your browser has resolved \{fqdn\} to | Text used when prompting a user to select a resolve IPv4 or IPv6 address for an FQDN query. |
| `web.text.fqdn_error` | String | Unable to resolve \{fqdn\} | Text used when an FQDN is not resolvable. |
| `web.text.fqdn_error_button` | String | Try Again | Button text used when an FQDN is not resolvable. |
| `web.text.cache_prefix` | String | Results cached for | Text displayed with the cache timeout countdown. |
| `web.text.cache_icon` | String | Cached from \{time\} UTC | Text used when a user hovers over the cache icon, which is displayed when a response was a cached response. `{time}` is replaced with the _original_ query's timestamp. |
| `web.text.complete_time` | String | Completed in \{seconds\} | Text used when a user hovers over the success icon for a query result. `{seconds}` will be replaced with 'n seconds' where n is the time a query took to complete. |
| `web.text.rpki_invalid` | String | Invalid | Text used in table output when a route's RPKI status is invalid. |
| `web.text.rpki_valid` | String | Valid | Text used in table output when a route's RPKI status is valid. |
| `web.text.rpki_unknown` | String | No ROAs Exist | Text used in table output when a route's RPKI status is unknown. |
| `web.text.rpki_unverified` | String | Not Verified | Text used in table output when a route's RPKI status is unverified. |
| `web.text.no_communities` | String | No Communities | Text used in table output when a route has no communities. |
| `web.text.ip_error` | String | Unable to determine IP Address | Error displayed if hyperglass is unable to determine the user's IP. |
| `web.text.no_ip` | String | No \{protocol\} Address | Text displayed if the user doesn't have an IP address of \{protocol\} (IPv4 or IPv6). |
| `web.text.ip_select` | String | Select an IP Address | Text used to label the IP Address selection for the user's IP. |
| `web.text.ip_button` | String | My IP | Text used for the user IP button. |
#### Title Mode
Available title modes are:
- `logo_only` only the logo is displayed, no title or subtitle will be visible.
- `text_only` only the title and subtitle are displayed, no logo will be visible.
- `logo_subtitle` only the logo and subtitle are displayed, no title will be visible.
- `all` logo, title, and subtitle will all be visible.
##### Example
```yaml filename="config.yaml"
web:
text:
title: Our Looking Glass
subtitle: Company Name, Inc.
title_mode: text_only
```
### Theme
hyperglass allows you to customize the colors and fonts used in the Web UI.
| Parameter | Type | Default Value | Description |
| :----------------------------- | :----- | :------------ | :--------------------------------------------------------------------------------------------------------------- |
| `web.theme.default_color_mode` | String | | Set hyperglass's default color mode. By default, the user's system preference is used. Must be `light` or `dark` |
#### Colors
##### Intrinsic Colors
| Parameter | Default Value |
| :------------------------ | :---------------------- |
| `web.theme.colors.black` | <Color hex="#000000" /> |
| `web.theme.colors.white` | <Color hex="#ffffff" /> |
| `web.theme.colors.dark` | <Color hex="#010101"/> |
| `web.theme.colors.light` | <Color hex="#f5f6f7"/> |
| `web.theme.colors.gray` | <Color hex="#c1c7cc"/> |
| `web.theme.colors.red` | <Color hex="#d84b4b"/> |
| `web.theme.colors.orange` | <Color hex="#ff6b35"/> |
| `web.theme.colors.yellow` | <Color hex="#edae49"/> |
| `web.theme.colors.green` | <Color hex="#35b246"/> |
| `web.theme.colors.blue` | <Color hex="#314cb6"/> |
| `web.theme.colors.teal` | <Color hex="#35b299"/> |
| `web.theme.colors.cyan` | <Color hex="#118ab2"/> |
| `web.theme.colors.pink` | <Color hex="#f2607d"/> |
| `web.theme.colors.purple` | <Color hex="#8d30b5"/> |
##### Functional Colors
| Parameter | Default Value |
| :--------------------------- | :--------------------- |
| `web.theme.colors.primary` | <Color hex="#118ab2"/> |
| `web.theme.colors.secondary` | <Color hex="#314cb6"/> |
| `web.theme.colors.success` | <Color hex="#35b246"/> |
| `web.theme.colors.warning` | <Color hex="#edae49"/> |
| `web.theme.colors.error` | <Color hex="#ff6b35"/> |
| `web.theme.colors.danger` | <Color hex="#d84b4b"/> |
###### Example
To override hyperglass's primary color, it's recommended to override its mapped intrinsic color. For example, to override the default primary color to <Color hex="#00ffff" noText /> cyan:
```yaml filename="config.yaml"
web:
theme:
colors:
cyan: '#00ffff'
```
#### Fonts
hyperglass's fonts are loaded from [Google Fonts](https://fonts.google.com/). Any Google font name may be specified to override the default fonts.
| Parameter | Type | Default Value | Description |
| :--------------------- | :----- | :------------ | :--------------------------------------------------------------------------------------- |
| `web.theme.fonts.body` | String | Nunito | Font for all standard body text, including headings. |
| `web.theme.fonts.mono` | String | Fire Code | Font for all monospace text such as inline code or code blocks, including device output. |
##### Example
```yaml filename="config.yaml"
web:
theme:
fonts:
body: Inter
```
Copy Permalink