witine/lookingglass
1
0
Fork 0
forked from mirrors/thatmattlove-hyperglass
Code Issues Pull requests Releases Activity

update docs

Browse source
This commit is contained in:
thatmattlove 2024-03-25 00:01:16 -04:00
parent 19bdfe74d0
commit e7e8b9b881
26 changed files with 640 additions and 413 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/components/color.tsx
View file

@ -5,15 +5,14 @@ type ColorProps = {
export const Color = (props: ColorProps) => {
const { hex, noText = false } = props;
console.log(props);
return (
<span className="color-swatch-container">
<span className={['nx-rounded-sm', 'color-swatch'].join(' ')} />
<code>{noText ? '' : hex}</code>
<span className={["nx-rounded-sm", "color-swatch"].join(" ")} />
<code>{noText ? "" : hex}</code>
<style jsx>{`
span.color-swatch-container {
display: inline-flex;
align-items: ${noText ? 'flex-end' : 'center'};
align-items: ${noText ? "flex-end" : "center"};
justify-content: space-between;
}
span.color-swatch {
@ -22,7 +21,7 @@ export const Color = (props: ColorProps) => {
height: 1.5rem;
width: 1.5rem;
padding: 0.5rem 0.5rem;
margin-right: ${noText ? 'unset' : '0.5rem'};
margin-right: ${noText ? "unset" : "0.5rem"};
}
`}</style>
</span>

36
docs/components/docs-button.tsx Normal file
View file

@ -0,0 +1,36 @@
import NextLink from "next/link";
import { Button } from "nextra/components";
const DocsIcon = () => (
<svg
width="16"
height="16"
fill="currentColor"
viewBox="0 0 16 16"
xmlns="http://www.w3.org/2000/svg"
className="bi bi-file-earmark-text-fill"
>
<title>Docs</title>
<path d="M9.293 0H4a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2V4.707A1 1 0 0 0 13.707 4L10 .293A1 1 0 0 0 9.293 0M9.5 3.5v-2l3 3h-2a1 1 0 0 1-1-1M4.5 9a.5.5 0 0 1 0-1h7a.5.5 0 0 1 0 1zM4 10.5a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5m.5 2.5a.5.5 0 0 1 0-1h4a.5.5 0 0 1 0 1z" />
</svg>
);
export interface DocsButtonProps extends React.ComponentProps<"button"> {
href: string;
side?: "left" | "right";
}
export const DocsButton = (props: DocsButtonProps) => {
const { href, side = "left", ...rest } = props;
return (
<NextLink href={href}>
<Button
title="Docs"
className={`nx-p-0 nx-m${side === "left" ? "r" : "l"}-2`}
{...rest}
>
<DocsIcon />
</Button>
</NextLink>
);
};

14
docs/components/not-supported-icon.tsx Normal file
View file

@ -0,0 +1,14 @@
export const NotSupported = (props: React.ComponentProps<"svg">) => (
<svg
xmlns="http://www.w3.org/2000/svg"
width="16"
height="16"
fill="#edae49"
viewBox="0 0 16 16"
{...props}
>
<title>Not Supported</title>
<path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z" />
<path d="M4.646 4.646a.5.5 0 0 1 .708 0L8 7.293l2.646-2.647a.5.5 0 0 1 .708.708L8.707 8l2.647 2.646a.5.5 0 0 1-.708.708L8 8.707l-2.646 2.647a.5.5 0 0 1-.708-.708L7.293 8 4.646 5.354a.5.5 0 0 1 0-.708z" />
</svg>
);

44
docs/components/platforms.tsx Normal file
View file

@ -0,0 +1,44 @@
import { Code, Table, Td, Th, Tr } from "nextra/components";
import platforms from "~/platforms.json";
import { NotSupported } from "./not-supported-icon";
import { Supported } from "./supported-icon";
export const SupportedPlatforms = () => (
<ul className="nx-mt-2 first:nx-mt-0 ltr:nx-ml-6 rtl:nx-mr-6">
{platforms.reduce<React.ReactNode[]>((final, platform) => {
if (platform.native) {
const element = (
<li key={platform.name}>
<Supported style={{ display: "inline", marginRight: "0.5rem" }} />
{platform.name}
</li>
);
final.push(element);
}
return final;
}, [])}
</ul>
);
export const PlatformTable = () => (
<Table>
<tbody>
<Tr>
<Th>Platform Keys</Th>
<Th>Natively Supported</Th>
</Tr>
{platforms.map((spec) => (
<Tr key={spec.keys.join("--")}>
<Td>
{spec.keys.map((key) => (
<Code className="nx-mx-2" key={key}>
{key}
</Code>
))}
</Td>
<Td align="center">{spec.native ? <Supported /> : <NotSupported />}</Td>
</Tr>
))}
</tbody>
</Table>
);

13
docs/components/supported-icon.tsx Normal file
View file

@ -0,0 +1,13 @@
export const Supported = (props: React.ComponentProps<"svg">) => (
<svg
xmlns="http://www.w3.org/2000/svg"
width="16"
height="16"
fill="#35b246"
viewBox="0 0 16 16"
{...props}
>
<title>Supported</title>
<path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0zm-3.97-3.03a.75.75 0 0 0-1.08.022L7.477 9.417 5.384 7.323a.75.75 0 0 0-1.06 1.06L6.97 11.03a.75.75 0 0 0 1.079-.02l3.992-4.99a.75.75 0 0 0-.01-1.05z" />
</svg>
);

1
docs/pages/configuration/_meta.json
View file

@ -1,4 +1,5 @@
{
"overview": "Overview",
"config": "Config File",
"devices": "Devices File",
"directives": "Directives File",

182
docs/pages/configuration/config.mdx
View file

@ -1,8 +1,11 @@
---
title: Configuration File
description: hyperglass config.yaml file reference
---
The `config.yaml` file is broken into multiple sections:
# Global
Top level parameters:
## Top Level Parameters
| Parameter | Type | Default Value | Description |
| :----------------- | :-------------- | :------------------------------- | :------------------------------------------------------------ |
@ -24,171 +27,18 @@ site_description: Beloved Hyperglass User Network Looking Glass
site_title: Beloved Hyperglass User
```
## Cache
## Other Configuration Sections
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 | Docs | Description |
| :----------- | :--------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `cache` | [Caching Docs](/configuration/config/caching.mdx) | Customize how hyperglass caches responses. |
| `logging` | [Logging Docs](/configuration/config/logging.mdx) | Customize file logging, syslog, webhooks, etc. |
| `messages` | [Messages Docs](/configuration/config/messages.mdx) | Customize messages shown to users. |
| `structured` | [Structured Output Docs](/configuration/config/structured-ouptput.mdx) | Customize how hyperglass handles structured output from devices. |
| `web` | [Web UI Docs](/configuration/config/web-ui.mdx) | Customize the look and feel of hyperglass's web UI. |
| 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. |
## Caveats
#### 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 | | List of communities to match. |
#### 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.
```
### Caveats
#### Arista EOS
### Arista EOS
For whatever reason, the tested version of 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.

4
docs/pages/configuration/config/_meta.json
View file

@ -1,4 +1,8 @@
{
"api-docs": "API Docs",
"caching": "Caching",
"logging": "Logging & Webhooks",
"messages": "Messages",
"structured-output": "Structured Output",
"web-ui": "Web UI"
}

73
docs/pages/configuration/config/api-docs.mdx Normal file
View file

@ -0,0 +1,73 @@
## API 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
```

16
docs/pages/configuration/config/caching.mdx Normal file
View file

@ -0,0 +1,16 @@
## Cache
hyperglass automatically caches responses to reduce the number of times devices are queried for the same information.
| Parameter | Type | Default Value | Description |
| :---------------- | :------ | :------------ | :------------------------------------------------------------------------------ |
| `cache.timeout` | Number | 120 | Number of seconds for which to cache device responses. |
| `cache.show_text` | Boolean | True | If true, an indication that a user is viewing cached information will be shown. |
### Example with Defaults
```yaml filename="config.yaml"
cache:
timeout: 120
show_text: true
```

23
docs/pages/configuration/config/messages.mdx Normal file
View file

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

59
docs/pages/configuration/config/structured-output.mdx Normal file
View file

@ -0,0 +1,59 @@
## 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
- Juniper Junos
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 | | List of communities to match. |
### RPKI Examples
#### Show RPKI State from the Device's Perspective
```yaml filename="config.yaml" copy {2}
structured:
rpki: router
```
#### Show RPKI State from a Public/External Perspective
```yaml filename="config.yaml" copy {2}
structured:
rpki: external
```
### 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.
```

106
docs/pages/configuration/devices.mdx
View file

@ -1,63 +1,64 @@
import { Callout } from "nextra-theme-docs";
import { SupportedPlatforms } from "~/components/platforms";
import { DocsButton } from "~/components/docs-button";
## Device Configuration Parameters
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`](configuration/config/web-ui.mdx) is set to `gallery`. |
| `avatar` | String | | Path to an avatar/logo image for this site. Used when [`web.location_display_mode`](/configuration/config/web-ui.mdx) 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](platforms.mdx). |
| `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.mdx). |
| `platform` | String | | Device platform/OS. Must be a [supported platform](/platforms.mdx). |
| `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.mdx). |
| `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` | Mapping | | Mapping/dict of a [credential configuration](/configuration/devices/credentials.mdx). |
| `http` | Mapping | | Mapping/dict of [HTTP client options](/configuration/devices/http-device.mdx), if this device is connected via HTTP. |
| `proxy` | Mapping | | Mapping/dict of [SSH proxy config](/configuration/devices/ssh-proxy.mdx) to use for this device's requests. |
## Credential Configuration
<Callout type="info">
| 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. |
hyperglass ships with predefined [directives](/configuration/directives.mdx) (commands) for the following [platforms](platforms.mdx):
## SSH Proxy Configuration
<SupportedPlatforms />
| 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). |
All built in directives require that the following `attrs` be defined on each device using the directive:
## HTTP Configuration
| Attribute | Value |
| :-------- | :-------------------------------------------------------- |
| `source4` | IPv4 address used to source Ping and Traceroute commands. |
| `source6` | IPv6 address used to source Ping and Traceroute commands. |
| 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. |
**Example**
# Examples
```yaml filename="devices.yaml" {5-7} copy
devices:
- name: New York, NY
address: 192.0.2.1
platform: cisco_ios
attrs:
source4: 192.0.2.1
source6: "2001:db8::1"
```
## Simple
</Callout>
<Callout type="warning">
If you do not utilize IPv6 in your network, you'll need to create your own directive that only
has IPv4 commands.
</Callout>
## Examples
### Simple
```yaml filename="devices.yaml" copy
devices:
@ -75,7 +76,7 @@ devices:
password: your password
```
## With Directives
### <DocsButton href="/configuration/directives.mdx"/> With Directives
In this example, an additional directive `cisco-show-lldp-neighbors` is added to the built-in directives.
@ -91,7 +92,7 @@ devices:
- cisco-show-lldp-neighbors
```
## Disable Built-in Directives
### <DocsButton href="/configuration/directives.mdx"/> Disable Built-in Directives
In this example, _only_ the `cisco-show-lldp-neighbors` directive will be available. Built-in directives are disabled.
@ -108,7 +109,7 @@ devices:
- cisco-show-lldp-neighbors
```
## Enable Specifc Built-in Directives
### <DocsButton href="/configuration/directives.mdx"/> Enable Specifc Built-in Directives
In this example, only specified built-in directives are made available.
@ -123,20 +124,3 @@ devices:
directives:
- builtin: [bgp_route, traceroute]
```
## With an SSH Proxy
```yaml filename="devices.yaml" copy {8-12}
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
```

5
docs/pages/configuration/devices/_meta.json Normal file
View file

@ -0,0 +1,5 @@
{
"credentials": "Credentials",
"http-device": "HTTP Device",
"ssh-proxy": "SSH Proxy"
}

35
docs/pages/configuration/devices/credentials.mdx Normal file
View file

@ -0,0 +1,35 @@
Each device must be configured with credentials with which hyperglass can log into the device and execute commands.
## 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. |
### Examples
#### Username & Password
```yaml filename="devices.yaml" copy {5-7}
devices:
- name: New York, NY
address: 192.0.2.1
platform: cisco_ios
credential:
username: you
password: your password
```
#### SSH Private Key
```yaml filename="devices.yaml" copy {5-7}
devices:
- name: San Francisco, CA
address: 192.0.2.2
platform: juniper
credential:
username: you
key: /path/to/your/ssh/key
```

85
docs/pages/configuration/devices/http-device.mdx Normal file
View file

@ -0,0 +1,85 @@
hyperglass supports collecting output from a generic HTTP endpoint.
## 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. |
### Example
#### Basic
The following example will send an HTTP POST request to `https://192.0.2/path/to/query/device` with HTTP basic authentication, and will not verify the SSL certificate.
```yaml filename="devices.yaml" copy
devices:
- name: New York, NY
address: 192.0.2.1
http:
path: /path/to/query/device
method: POST
verify_ssl: false
basic_auth:
username: you
password: your password
```
Given the following hyperglass query:
| Field | Value |
| :------------- | :------------------ |
| Query Target | `192.0.2.0/24` |
| Query Location | `your_location` |
| Query Type | `example_directive` |
The body of the request will be:
```json
{
"query_target": "192.0.2.0/24",
"query_location": "your_location",
"query_type": "example_directive"
}
```
#### Non-HTTPS Request
The following example will send an HTTP GET request to `http://192.0.2.1/path/to/query/device`:
```yaml filename="devices.yaml" {6} copy
devices:
- name: New York, NY
address: 192.0.2.1
http:
path: /path/to/query/device
scheme: http
```
#### Header Authentication
The following example will send an HTTP GET request to `https://192.0.2.1/path/to/query/device` with an `Authorization` header:
```yaml filename="devices.yaml" {6-7} copy
devices:
- name: New York, NY
address: 192.0.2.1
http:
path: /path/to/query/device
headers:
Authorization: your special token
```

30
docs/pages/configuration/devices/ssh-proxy.mdx Normal file
View file

@ -0,0 +1,30 @@
In cases where access to the devices is secured behind a "jump box" or other intermediary server/device, hyperglass can use SSH local port forwarding to SSH to an intermedary device first, and then 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](/configuration/config/credentials.mdx). |
### Examples
#### Use an SSH Proxy When Connecting to a Device
```yaml filename="devices.yaml" copy
devices:
- name: New York, NY
address: 192.0.2.1
credential:
username: you
password: your password
proxy:
address: 203.0.113.1
credential:
username: your proxy username
password: your proxy password
```
In the above example, the credentials `your proxy username`/`your proxy password` will be used to authenticate from the hyperglass server to the SSH proxy, and the credentials `you`/`your password` will be used to authentiate from the SSH proxy to the device.

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

@ -1,8 +1,14 @@
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:
import { Steps } from "nextra/components";
## 1. Create the Directive
## Add Your Own Command
```yaml filename="directives.yaml"
While hyperglass does come with several built-in [directives](/configuration/configuration/directives.mdx) (commands), you can also add your own. For example, say you want to add a command that shows the BGP summary from a device:
<Steps>
### Create the Directive
```yaml filename="directives.yaml" copy
show-bgp-summary:
name: BGP Summary
rules:
@ -11,9 +17,9 @@ show-bgp-summary:
field: null
```
## 2. Associate the Directive with the Device
### Associate the Directive with the Device
```yaml filename="devices.yaml"
```yaml filename="devices.yaml" {5-6} copy
devices:
- name: Your Router
address: 192.0.2.1
@ -22,9 +28,13 @@ devices:
- show-bgp-summary
```
</Steps>
## Default Directives
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"
```yaml filename="devices.yaml" {6-7} copy
devices:
- name: Your Router
address: 192.0.2.1
@ -34,4 +44,17 @@ devices:
- show-bgp-summary
```
When this is specified, _only_ the `show-bgp-summary` directive will be enabled.
In the above example, _only_ the `show-bgp-summary` directive will be enabled.
You can also selectively enable certain built-in directives:
```yaml filename="devices.yaml" {6} copy
devices:
- name: Your Router
address: 192.0.2.1
platform: cisco_ios
directives:
- builtins: [bgp_route, traceroute]
```
In the above example, _only_ the BGP Route and Traceroute built-in directives will be enabled.

2
docs/pages/configuration/examples/basic-configuration.mdx
View file

@ -14,8 +14,6 @@ To get started, hyperglass only needs to know about your devices.
## Simple Device Configuration
Create a file called `devices.yaml` in the directory `/etc/hyperglass`.
```yaml filename="devices.yaml"
devices:
- name: NYC Router 1

33
docs/pages/configuration/examples/customize-the-ui.mdx
View file

@ -2,28 +2,47 @@
description: Customize hyperglass to fit your needs.
---
### Change the title and organization name
import { DocsButton } from "../../../components/docs-button";
### <DocsButton href="/configuration/config" /> Change the Title and Organization Name
```yaml filename="config.yaml"
site_title: Our super neat looking glass
org_name: Cool Company
```
### Change the logo
### <DocsButton href="/configuration/config/web-ui#logo" /> Change the Logo
```yaml filename="config.yaml"
```yaml filename="config.yaml" {2-4} copy
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
### <DocsButton href="/configuration/config/web-ui#theme" /> Change the Color Scheme
```yaml filename="config.yaml"
```yaml filename="config.yaml" copy {3-5}
web:
theme:
colors:
primary: '#d84b4b'
secondary: '#118ab2'
primary: "#d84b4b"
secondary: "#118ab2"
```
### <DocsButton href="/configuration/config/web-ui#menus" /> Add a Link to the Footer
```yaml filename="config.yaml" copy
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
```

34
docs/pages/configuration.mdx → docs/pages/configuration/overview.mdx
View file

@ -1,34 +1,16 @@
import { Code, Table, Td, Th, Tr } from "nextra/components";
import { Callout } from "nextra-theme-docs";
import platforms from "~/platforms.json";
import { Supported } from "./platforms.mdx";
export const Platforms = () => (
<ul>
{platforms.reduce((final, platform) => {
if (platform.native) {
const element = (
<li key={platform.name}>
<Supported style={{ display: "inline", marginRight: "0.5rem" }} />
{platform.name}
</li>
);
final = [...final, element];
}
return final;
}, [])}
</ul>
);
import { SupportedPlatforms } from "~/components/platforms";
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.mdx) (commands). |
| File Name | Docs | Purpose |
| :----------- | :---------------------------------------------------: | :------------------------------------------------------------------------- |
| `config` | [Config File Docs](/configuration/config.mdx) | Application-wide configuration such as logging, web UI customization, etc. |
| `devices` | [Devices File Docs](/configuration/devices.mdx) | Your devices and their associated configurations. |
| `directives` | [Directives File Docs](/configuration/directives.mdx) | Custom directives (commands). |
<Callout type="info">
**File Extensions** <br />
@ -78,9 +60,9 @@ main = {
## Built-in Directives
hyperglass ships with predefined [directives](configuration/directives.mdx) for the following [platforms](platforms.mdx):
hyperglass ships with predefined [directives](/configuration/directives.mdx) for the following [platforms](platforms.mdx):
<Platforms />
<SupportedPlatforms />
All built in directives require that the following `attrs` be defined on each device using the directive:

16
docs/pages/index.mdx
View file

@ -4,19 +4,7 @@ description: Get started with hyperglass
---
import { Cards, Card } from "nextra/components";
import platforms from "~/platforms.json";
export const Platforms = () => (
<ul>
{platforms.reduce((final, platform) => {
if (platform.native) {
const element = <li key={platform.name}>{platform.name}</li>;
final = [...final, element];
}
return final;
}, [])}
</ul>
);
import { SupportedPlatforms } from "~/components/platforms";
## What is hyperglass?
@ -30,7 +18,7 @@ hyperglass was created with the lofty goal of benefiting the internet community
- Full IPv6 support
- Customizable everything: features, theme, UI/API text, error messages, commands
- Built in support for:
<Platforms />
<SupportedPlatforms />
- Configurable support for any other [supported platform](platforms.mdx)
- Optionally access devices via an SSH proxy/jump server
- VRF support

54
docs/pages/platforms.mdx
View file

@ -2,58 +2,8 @@
description: Platforms supported by hyperglass
---
import { Code, Table, Td, Th, Tr } from "nextra/components";
import { Callout } from "nextra-theme-docs";
import platforms from "~/platforms.json";
export const NotSupported = () => (
<svg
xmlns="http://www.w3.org/2000/svg"
width="16"
height="16"
fill="#edae49"
viewBox="0 0 16 16"
>
<path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z" />
<path d="M4.646 4.646a.5.5 0 0 1 .708 0L8 7.293l2.646-2.647a.5.5 0 0 1 .708.708L8.707 8l2.647 2.646a.5.5 0 0 1-.708.708L8 8.707l-2.646 2.647a.5.5 0 0 1-.708-.708L7.293 8 4.646 5.354a.5.5 0 0 1 0-.708z" />
</svg>
);
export const Supported = (props) => (
<svg
xmlns="http://www.w3.org/2000/svg"
width="16"
height="16"
fill="#35b246"
viewBox="0 0 16 16"
{...props}
>
<path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0zm-3.97-3.03a.75.75 0 0 0-1.08.022L7.477 9.417 5.384 7.323a.75.75 0 0 0-1.06 1.06L6.97 11.03a.75.75 0 0 0 1.079-.02l3.992-4.99a.75.75 0 0 0-.01-1.05z" />
</svg>
);
export const Platforms = () => (
<Table>
<tbody>
<Tr>
<Th>Platform Keys</Th>
<Th>Natively Supported</Th>
</Tr>
{platforms.map((spec) => (
<Tr key={spec.keys.join("--")}>
<Td>
{spec.keys.map((key) => (
<Code className="nx-mx-2" key={key}>
{key}
</Code>
))}
</Td>
<Td align="center">{spec.native ? <Supported /> : <NotSupported />}</Td>
</Tr>
))}
</tbody>
</Table>
);
import { PlatformTable } from "~/components/platforms";
hyperglass uses [Netmiko](https://github.com/ktbyers/netmiko) to interact with devices via SSH/telnet. [All platforms supported by Netmiko](https://github.com/ktbyers/netmiko/blob/develop/PLATFORMS.md) are supported by hyperglass.
@ -69,7 +19,7 @@ hyperglass uses [Netmiko](https://github.com/ktbyers/netmiko) to interact with d
<br />
<Platforms />
<PlatformTable />
## Other Platforms

18
hyperglass/models/config/cache.py
View file

@ -1,26 +1,12 @@
"""Validation model for Redis cache config."""
"""Validation model for cache config."""
# Standard Library
import typing as t
# Third Party
from pydantic import SecretStr, IPvAnyAddress
# Local
from ..main import HyperglassModel
class CachePublic(HyperglassModel):
class Cache(HyperglassModel):
"""Public cache parameters."""
timeout: int = 120
show_text: bool = True
class Cache(CachePublic):
"""Validation model for params.cache."""
host: t.Union[IPvAnyAddress, str] = "localhost"
port: int = 6379
database: int = 1
password: t.Optional[SecretStr] = None

10
hyperglass/models/config/devices.py
View file

@ -203,7 +203,17 @@ class Device(HyperglassModelWithId, extra="allow"):
def validate_platform(cls: "Device", value: t.Any, values: t.Dict[str, t.Any]) -> str:
"""Validate & rewrite device platform, set default `directives`."""
if value == "http":
if values.get("http") is None:
raise ConfigError(
"Device '{device}' has platform 'http' configured, but no http parameters are defined.",
device=values["name"],
)
if value is None:
if values.get("http") is not None:
value = "http"
else:
# Ensure device platform is defined.
raise ConfigError(
"Device '{device}' is missing a 'platform' (Network Operating System) property",

4
hyperglass/models/ui.py
View file

@ -6,7 +6,7 @@ import typing as t
# Local
from .main import HyperglassModel
from .config.web import WebPublic
from .config.cache import CachePublic
from .config.cache import Cache
from .config.params import ParamsPublic
from .config.messages import Messages
@ -54,7 +54,7 @@ class UIContent(HyperglassModel):
class UIParameters(ParamsPublic, HyperglassModel):
"""UI Configuration Parameters."""
cache: CachePublic
cache: Cache
web: WebPublic
messages: Messages
version: str