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

add v2 docs, minor refactoring

Browse Source
This commit is contained in:
thatmattlove
2022-12-19 14:57:20 -05:00
parent fc3ba3a8be
commit f37eb9abf7
21 changed files with 742 additions and 355 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/pages/_meta.json
View File

@@ -2,6 +2,6 @@
"index": "hyperglass",
"introduction": "Introduction",
"installation": "Installation",
"basic-configuration": "Basic Configuration",
"configuration": "Configuration"
"configuration": "Configuration",
"plugins": "Plugins"
}

57
docs/pages/configuration.mdx Normal file
View File

@@ -0,0 +1,57 @@
import { Callout } from 'nextra-theme-docs';
Once you've gotten started with a basic configuration, you'll probably want to customize the look and feel of hyperglass by changing the logo or color scheme. Fortunately, there are _a lot_ ways to customize hyperglass.
## Configuration Files
| File Name | Purpose |
| :----------- | :------------------------------------------------------------------------- |
| `config` | Application-wide configuration such as logging, web UI customization, etc. |
| `devices` | Your devices and their associated configurations. |
| `directives` | Custom [directives](/configuration/directives-file-reference) (commands). |
<Callout type="info">
**File Extensions** <br />
All the examples in the docs are provided in [YAML](https://yaml.org/) format, but [TOML](https://toml.io/),
JSON, and Python files are also supported.
</Callout>
### Using a Python File
When using a Python file for a hyperglass configuration, one of the following methods may be used:
#### Define a Function Named `main`
```python
def main():
return {
"org_name": "Your Organization Name",
"web": {
"theme": {
"colors": {
"blue": "#0000ff",
}
}
}
}
# The main function can also be an async function.
async def main():
config = await some_function_to_fetch_config()
return config
```
#### Define a Dictionary Named `main`
```python
main = {
"org_name": "Your Organization Name",
"web": {
"theme": {
"colors": {
"blue": "#0000ff",
}
}
}
}
```

6
docs/pages/configuration/_meta.json
View File

@@ -1,4 +1,6 @@
{
"configuration-options": "Configuration Options",
"reference": "Configuration Reference"
"examples": "Examples",
"config-file-reference": "Config File Reference",
"devices-file-reference": "Devices File Reference",
"directives-file-reference": "Directives File Reference"
}

5
docs/pages/configuration/config-file-reference/_meta.json Normal file
View File

@@ -0,0 +1,5 @@
{
"index": "Config File",
"logging": "Logging & Webhooks",
"web-ui": "Web UI"
}

194
docs/pages/configuration/config-file-reference/index.mdx Normal file
View File

@@ -0,0 +1,194 @@
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.

90
docs/pages/configuration/config-file-reference/logging.mdx Normal file
View File

@@ -0,0 +1,90 @@
## 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`. |
#### 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>
```

288
docs/pages/configuration/reference/config.yaml.mdx → docs/pages/configuration/config-file-reference/web-ui.mdx
View File

@@ -1,293 +1,7 @@
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
## Web UI
hyperglass provides extensive customization options for the look and feel of the web UI.

46
docs/pages/configuration/configuration-options.mdx
View File

@@ -1,46 +0,0 @@
---
title: Configuration Options
description: Customize hyperglass to fit your needs.
---
import { Callout } from 'nextra-theme-docs';
Once you've gotten started with a basic configuration, you'll probably want to customize the look and feel of hyperglass by changing the logo or color scheme. Fortunately, there are _a lot_ ways to customize hyperglass.
## Configuration File
Create a file called `config.yaml` in `/etc/hyperglass`.
<Callout type="info">
**File Extensions** <br />
All the examples in the docs are provided in [YAML](https://yaml.org/) format, but [TOML](https://toml.io/)
and JSON are also supported.
</Callout>
### Common Examples
#### Change the title and organization name
```yaml filename="config.yaml"
site_title: Our super neat looking glass
org_name: Cool Company
```
#### Change the logo
```yaml filename="config.yaml"
web:
logo:
light: <path to logo image file to use in light mode>
dark: <path to logo image file to use in dark mode>
```
#### Change the color scheme
```yaml filename="config.yaml"
web:
theme:
colors:
primary: '#d84b4b'
secondary: '#118ab2'
```

107
docs/pages/configuration/devices-file-reference.mdx Normal file
View File

@@ -0,0 +1,107 @@
Each configured device may have the following parameters:
| Parameter | Type | Default Value | Description |
| :------------------ | :-------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | | Display name of the device. |
| `description` | String | | Description of the device, displayed as a subtle label. |
| `avatar` | String | | Path to an avatar/logo image for this site. Used when [`web.location_display_mode`](/config-file-reference/web-ui) is set to `gallery`. |
| `address` | String | | IPv4 address, IPv6 address, or hostname of the device. |
| `group` | String | | Group name, used to visually group devices in the UI. |
| `port` | Number | | TCP port on which to connect to the device. |
| `platform` | String | | Device platform/OS. Must be a [supported platform](/supported-platforms). |
| `structured_output` | Boolean | `true` | Disable structured output for a device that supports it. |
| `directives` | List of Strings | | Enable referenced directives configured in the [directives config file](/configuration/directives-file-reference). |
| `driver` | String | netmiko | Specify which driver to use for this device. Currently, only `netmiko` is supported. |
| `driver_config` | Mapping | | Mapping/dict of options to pass to the connection driver. |
| `attrs` | Mapping | | Mapping/dict of variables, as referenced in configured directives. |
| `credential` | Mapping | | Mapping/dict of a [credential configuration](#credential-onfiguration). |
| `http` | Mapping | | Mapping/dict of HTTP client options, if this device is connected via HTTP. |
| `proxy` | Mapping | | Mapping/dict of SSH proxy to use for this device's requests. |
## Credential Configuration
| Parameter | Type | Default Value | Description |
| :-------------------- | :----- | :------------ | :----------------------------------------------------- |
| `credential.username` | String | | Username to use for authentication to the device. |
| `credential.password` | String | | Password to use for authentication to the device. |
| `credential.key` | String | | Path to SSH key used for authentication to the device. |
## SSH Proxy Configuration
| Parameter | Type | Default Value | Description |
| :----------------- | :------ | :------------ | :---------------------------------------------------------------------- |
| `proxy.address` | String | | IPv4 address, IPv6 address, or hostname of SSH proxy. |
| `proxy.port` | Number | 22 | TCP port to use for connecting to the SSH proxy. |
| `proxy.platform` | String | linux_ssh | Currently, only `linux_ssh` is supported. |
| `proxy.credential` | Mapping | | Mapping/dict of a [credential configuration](#credential-onfiguration). |
## HTTP Configuration
| Parameter | Type | Default Value | Description |
| :---------------------- | :------ | :------------ | :--------------------------------------------------------------------------------------------------------------------- |
| `http.attribute_map` | Mapping | | Mapping/dict of hyperglass query fields as keys, and hyperglass query field replacements as values. |
| `http.basic_auth` | Mapping | | If basic authentication is required, provide a mapping/dict containing the basic authentication username and password. |
| `http.body_format` | String | json | Body format, options are `json` `yaml` `xml` `text` |
| `http.follow_redirects` | Boolean | `false` | Follow HTTP redirects from server. |
| `http.headers` | Mapping | | Mapping/dict of http headers to append to requests. |
| `http.method` | String | GET | HTTP method to use for requests. |
| `http.path` | String | / | HTTP URI/Path. |
| `http.query` | Mapping | | Mapping/Dict of URL Query Parameters. |
| `http.retries` | Number | 0 | Number of retries to perform before request failure. |
| `http.scheme` | String | https | HTTP schema, must be `http` or `https` |
| `http.source` | String | | Request source IP address. |
| `http.ssl_ca` | String | | Path to SSL CA certificate file for SSL validation. |
| `http.ssl_client` | String | | Path to client SSL certificates for request. |
| `http.timeout` | Number | 5 | Request timeout in seconds. |
| `http.verify_ssl` | Boolean | `true` | If `false`, invalid certificates for HTTPS hosts will be ignored. |
# Examples
## Simple
```yaml filename="devices.yaml"
devices:
- name: New York, NY
address: 192.0.2.1
platform: cisco_ios
credential:
username: you
password: your password
- name: San Francisco, CA
address: 192.0.2.2
platform: juniper
credential:
username: you
password: your password
```
## With Directives
```yaml filename="devices.yaml"
devices:
- name: New York, NY
address: 192.0.2.1
platform: cisco_ios
credential:
username: you
password: your password
directives:
- cisco-show-lldp-neighbors
```
## With an SSH Proxy
```yaml filename="devices.yaml"
devices:
- name: New York, NY
address: 192.0.2.1
platform: cisco_ios
credential:
username: you
password: your password
proxy:
address: 192.0.0.123
credential:
username: your proxy's username
password: your proxy's password
```

172
docs/pages/configuration/directives-file-reference.mdx Normal file
View File

@@ -0,0 +1,172 @@
## What is a directive?
A **directive** is a defined configuration for a **command** to run on a device. For example, a BGP Route query is a built-in directive. A directive defines:
- What command 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
Each directive has the following options:
| Parameter | Type | Default Value | Description |
| :------------------- | :-------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | | Display name of the directive. |
| `rules` | List of Rules | | List of [rule configs](#rules) |
| `field` | Mapping | | Mapping/dict of [fields config](#fields) |
| `info` | String | | File path to markdown-formatted help information about the directive. |
| `plugins` | List of Strings | | List of plugin names to use with this directive. |
| `groups` | List of Strings | | List of names by which directives are grouped in the UI. |
| `multiple` | Boolean | `false` | Command supports receiving multiple values. For example, Cisco IOS's `show ip bgp community` accepts multiple communities as arguments. |
| `multiple_separator` | String | `" "` | String by which multiple values are separated. For example, a list of values `[65001, 65002, 65003]` would be rendered as `65001 65002 65003` for when the command is run. |
## Rules
A rule is a way of saying "if a query target matches the rule's conditions, run this command".
| Parameter | Type | Default Value | Description |
| :---------- | :-------------- | :------------ | :--------------------------------------------------------------------------------------------- |
| `condition` | String | | Regular expression to match or IP prefix in which the value being evaluated must be contained. |
| `action` | String | permit | `permit` or `deny` the directive target when this rule is matched. |
| `commands` | List of Strings | | Commands to run when this rule matches. `{target}` is replaced with the query target. |
### IP Rule
| Parameter | Type | Default Value | Description |
| :------------------ | :------ | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ge` | Number | 0 | Prefix length greater than defined will be matched. |
| `le` | Number | 32,128 | `32` for IPv4 evaluations, `128` for IPv6 evaluations. Prefix length less than defined will be matched. |
| `allow_reserved` | Boolean | `false` | Allow reserved ([RFC1918](https://www.rfc-editor.org/rfc/rfc1918), [RFC5735](https://www.rfc-editor.org/rfc/rfc5735), [RFC5737](https://www.rfc-editor.org/rfc/rfc5737.html), etc.) addresses to pass validation. |
| `allow_unspecified` | Boolean | `false` | Allow unspecified addresses (`0.0.0.0` `::`) to pass validation. |
| `allow_loopback` | Boolean | `false` | Allow [loopback addresses](https://www.rfc-editor.org/rfc/rfc1700.html) (`127.0.0.0/8` `::1`) to pass validation. |
#### Examples
##### Require IPv4 Queries between /8 and /24
```yaml filename="directives.yaml"
your-directive:
name: IP Route
rules:
- condition: 0.0.0.0/0
ge: 8
le: 24
command: 'show ip route {target} {mask}'
```
Given a query target of 198.18.0.0/15, the command run on the device would be `show ip route 198.18.0.0 255.254.0.0`
##### Deny a Specific Prefix
```yaml
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}'
```
In this example, a query of any IP address or prefix contained within 192.0.2.0/24 will result in an error.
##### Run Multiple Commands
```yaml filename="directives.yaml"
your-directive:
name: BGP Communities
rules:
- condition: '65000:[0-9]+'
commands:
- 'show route table inet.0 community {target} detail'
- 'show route table inet6.0 community {target} detail'
```
In this example, a query of `65000:1` would result in the following commands being sent to the device:
```
show route table inet.0 community 65000:1 detail
show route table inet6.0 community 65000:1 detail
```
The output for both commands will be shown as the query result.
### Regex Validation
To validate input by regex pattern, just specify a regex pattern as the `condition`
```yaml filename="directives.yaml"
your-directive:
name: DNS Query
rules:
- condition: '^.+\.yourdomain\.com$'
```
### No Validation
```yaml filename="directives.yaml"
your-directive:
name: IP Route
rules:
- condition: null
command: show ip route {target}
```
In this example, any query would pass, regardless of query input. For instance, if a user selected this directive/query type and queried 'your mom', the real command sent to the device will be `show ip route your mom`.
## Fields
### Text Input
| Parameter | Type | Default Value | Description |
| :------------ | :----- | :------------ | :---------------------------------------------------- |
| `description` | String | | Field description, displayed as a label or help text. |
| `validation` | String | | Regex pattern to validate text input. |
### Select
| Parameter | Type | Default Value | Description |
| :------------ | :-------------- | :------------ | :---------------------------------------------------- |
| `description` | String | | Field description, displayed as a label or help text. |
| `options` | List of Options | | |
#### Options
Each select option uses the following schema:
| Parameter | Type | Default Value | Description |
| :------------ | :----- | :------------ | :------------------------------------------------------- |
| `description` | String | | Field description, displayed as a label or help text. |
| `name` | String | | If specified, will be used as the option's display name. |
| `value` | String | | Option value sent to the device. |
### Examples
Example of a text directive expecting a string value matching a regex pattern:
```yaml filename="directives.yaml"
your-directive:
name: IP Route
rules:
- condition: null
command: show ip route {target}
field:
validation: '[0-9a-f\.\:]+'
```
Example of a select directive:
```yaml filename="directives.yaml"
your-directive:
name: BGP Community
rules:
- condition: null
command: show ip bgp community {target}
field:
options:
- value: '65001:1'
description: Provider A Routes
- value: '65001:2'
description: Provider B Routes
```

5
docs/pages/configuration/examples/_meta.json Normal file
View File

@@ -0,0 +1,5 @@
{
"add-your-own-command": "Add Your Own Command",
"basic-configuration": "Basic Configuration",
"customize-the-ui": "Customize the UI"
}

37
docs/pages/configuration/examples/add-your-own-command.mdx Normal file
View File

@@ -0,0 +1,37 @@
While hyperglass does come with several built-in commands or [directives](/configuration/directives-file-reference), you can also add your own. For example, say you want to add a command that shows the BGP summary from a device:
## 1. Create the Directive
```yaml filename="directives.yaml"
show-bgp-summary:
name: BGP Summary
rules:
- condition: null
command: show bgp all summary
field: null
```
## 2. Associate the Directive with the Device
```yaml filename="devices.yaml"
devices:
- name: Your Router
address: 192.0.2.1
platform: cisco_ios
directives:
- show-bgp-summary
```
By default, all built-in directives are _also_ enabled. If you wish to _only_ enable directives you specify, you can use `builtins: false` as a directive:
```yaml filename="devices.yaml"
devices:
- name: Your Router
address: 192.0.2.1
platform: cisco_ios
directives:
- builtins: false
- show-bgp-summary
```
When this is specified, _only_ the `show-bgp-summary` directive will be enabled.

2
docs/pages/basic-configuration.mdx → docs/pages/configuration/examples/basic-configuration.mdx
View File

@@ -16,7 +16,7 @@ To get started, hyperglass only needs to know about your devices.
Create a file called `devices.yaml` in the directory `/etc/hyperglass`.
```yaml title="devices.yaml"
```yaml filename="devices.yaml"
devices:
- name: NYC Router 1
address: <IP address hyperglass will use to log into the router>

29
docs/pages/configuration/examples/customize-the-ui.mdx Normal file
View File

@@ -0,0 +1,29 @@
---
description: Customize hyperglass to fit your needs.
---
### Change the title and organization name
```yaml filename="config.yaml"
site_title: Our super neat looking glass
org_name: Cool Company
```
### Change the logo
```yaml filename="config.yaml"
web:
logo:
light: <path to logo image file to use in light mode>
dark: <path to logo image file to use in dark mode>
```
### Change the color scheme
```yaml filename="config.yaml"
web:
theme:
colors:
primary: '#d84b4b'
secondary: '#118ab2'
```

3
docs/pages/configuration/reference/_meta.json
View File

@@ -1,3 +0,0 @@
{
"config.yaml": "config.yaml"
}