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

docs restructure

Browse Source
This commit is contained in:
checktheroads
2020-06-21 14:12:08 -07:00
parent 85e764c661
commit e50cd05fa3
15 changed files with 139 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/docs/cache.mdx
View File

@@ -1,7 +1,7 @@
---
id: cache
title: Caching
sidebar_label: Caching
id: response-caching
title: Response Caching
sidebar_label: Response Caching
keywords: [configuration, cache, timeout]
description: hyperglass caching configuration
---
@@ -16,7 +16,7 @@ Common Redis parameters are configurable, in case you already have a dedicated R
| `port` | Integer | `6379` | Redis server TCP port. |
| `database` | Integer | `1` | Database ID for hyperglass. |
| `timeout` | Integer | `120` | Time in seconds query output will be kept in the Redis cache. |
| `show_text` | Boolean | `true` | Show the [cache message](ui.mdx#text) in the hyperglass UI. |
| `show_text` | Boolean | `true` | Show the [cache message](ui/text) in the hyperglass UI. |
:::important Caching
hyperglass caches every query response to a Redis database, and always responds to a request with the cached value. If hyperglass receives a query for which it has no matching cached entry, the query parameters are used to created a new cache entry, hyperglass executes the request normally, writes the response to the cache, and then returns the response to the end user.

16
docs/docs/commands.mdx
View File

@@ -1,7 +1,7 @@
---
id: commands
title: Commands
sidebar_label: Commands
title: Command Customization
sidebar_label: Command Customization
keywords:
[
hyperglass,
@@ -29,7 +29,7 @@ hyperglass comes with built in support for the following platforms:
- Arista EOS
- Huawei VRP
Default commands for each of these network operating systems are built into hyperglass. However, you may override any of them or even add commands for another Network Operating System (NOS), as long as it's [supported](platforms.mdx). To define custom commands, add a `commands.yaml` file to your installation directory (`/etc/hyperglass`,
Default commands for each of these network operating systems are built into hyperglass. However, you may override any of them or even add commands for another Network Operating System (NOS), as long as it's [supported](platforms). To define custom commands, add a `commands.yaml` file to your installation directory (`/etc/hyperglass`,
`~/hyperglass`). As an example, you could override the default Juniper `bgp_route` command for the default routing table like this:
```yaml
@@ -74,10 +74,10 @@ command_name:
`ipv4_default` and `ipv6_default` reference the commands used in the default routing table/VRF, while `ipv4_vpn` and `ipv6_vpn` reference the commands used in **any** configured VRF. Every command will have the following keywords replaced:
| Keyword | Description |
| :--------- | :------------------------------------------------------------ |
| `{target}` | Query Target (IP address, community, AS Path). |
| `{vrf}` | If it's a VRF query, the [name of the VRF](devices.mdx#vrfs). |
| Keyword | Description |
| :--------- | :--------------------------------------------------------------- |
| `{target}` | Query Target (IP address, community, AS Path). |
| `{vrf}` | If it's a VRF query, the [name of the VRF](adding-devices#vrfs). |
## Defining Custom Commands
@@ -96,7 +96,7 @@ special_commands:
The above example defines the command set.
:::important
You must define _all_ commands, even if they're disabled in your [configuration](queries.mdx).
You must define _all_ commands, even if they're disabled in your [configuration](query-settings).
:::
Then, in the device's definition in `devices.yaml`, reference the command set:

12
docs/docs/configuration.mdx
View File

@@ -1,9 +1,9 @@
---
id: configuration
title: Configuration
sidebar_label: Configuration
keywords: [configuration]
description: Configuring hyperglass
id: parameters
title: Configuration Parameters
sidebar_label: Parameters
keywords: [hyperglass, configuration, parameters]
description: hyperglass configuration parameters.
---
import MiniNote from "../src/components/MiniNote";
@@ -113,7 +113,7 @@ routers:
source_address: 2001:db8::1
```
There are a lot more options, but this is enough to get started. For all device configuration options, [see here](devices.mdx).
There are a lot more options, but this is enough to get started. For all device configuration options, [see here](adding-devices).
:::tip YAML
If you have a lot of devices with shared configuration parameters, you may want to look into **YAML Anchors and Aliases**. If you've never used them before, they can be pretty weird looking at first read. Atlassian [has a pretty decent guide](https://confluence.atlassian.com/bitbucket/yaml-anchors-960154027.html).

30
docs/docs/devices.mdx
View File

@@ -1,7 +1,7 @@
---
id: devices
title: Devices
sidebar_label: Devices
id: adding-devices
title: Adding Devices
sidebar_label: Adding Devices
keywords:
[hyperglass, authentication, ssl, proxy, access list, prefix list, acl, help]
description: Adding devices to hyperglass
@@ -23,7 +23,7 @@ import Code from "../src/components/JSXCode";
| <R/> `network` | String | Primary network this device is a member of. Used for device grouping. Usually something like 'AS65000'. |
| <R/> `display_name` | String | Device's user-facing name. |
| <R/> `port` | Integer | TCP port used to connect to the device. |
| <R/> `nos` | String | Network Operating System. <MiniNote>Must be a <Link to="/docs/platforms">supported platform</Link>.</MiniNote> |
| <R/> `nos` | String | Network Operating System. <MiniNote>Must be a <Link to="platforms">supported platform</Link>.</MiniNote> |
| `structured_output` | Boolean | Disabled output parsing to structured data. |
| <R/>`credential` | | [Device Credential Configuration](#credential) |
| <R/>`vrfs` | | [Device VRF Configuration](#vrf) |
@@ -32,15 +32,15 @@ import Code from "../src/components/JSXCode";
### `proxy`
Any device that uses SSH (see [platforms](platforms.mdx) for breakdown) can be accessed through an intermediary SSH "proxy". The process is nearly identical to using local SSH tunneling, e.g. `ssh -L local_port:remote_device:remote_port username@proxy_server -p proxy_port`.
Any device that uses SSH (see [platforms](platforms) for breakdown) can be accessed through an intermediary SSH "proxy". The process is nearly identical to using local SSH tunneling, e.g. `ssh -L local_port:remote_device:remote_port username@proxy_server -p proxy_port`.
| Parameter | Type | Default | Description |
| :---------------- | :-----: | :------------ | :--------------------------------------------------------------------------------------------------------------------- |
| <R/> `name` | String | | Proxy hostname. |
| <R/> `address` | String | | Proxy management hostname or IP address. |
| <R/> `credential` | | | <Link to="#credential">Proxy Credential Configuration</Link> |
| `nos` | String | `'linux_ssh'` | Proxy's network operating system. <MiniNote>Must be a <Link to="/docs/platforms">supported platform</Link>.</MiniNote> |
| `port` | Integer | `22` | TCP port user to connect to the proxy. |
| Parameter | Type | Default | Description |
| :---------------- | :-----: | :------------ | :--------------------------------------------------------------------------------------------------------------- |
| <R/> `name` | String | | Proxy hostname. |
| <R/> `address` | String | | Proxy management hostname or IP address. |
| <R/> `credential` | | | [Proxy Credential Configuration](#credential) |
| `nos` | String | `'linux_ssh'` | Proxy's network operating system. <MiniNote>Must be a <Link to="platforms">supported platform</Link>.</MiniNote> |
| `port` | Integer | `22` | TCP port user to connect to the proxy. |
:::important
Currently, only `linux_ssh` has been tested and validated for use as an SSH proxy.
@@ -76,9 +76,9 @@ The VRFs section is a list of available VRFs for a given device. Each VRF may be
| :------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <R/> `name` | String | The VRF's name, as known **by the device**. <MiniNote>hyperglass sends this field to the device for queries, so it needs to match the device's configuration.</MiniNote> |
| `display_name` | String | The VRF's user-facing name. This field's value is visible in the UI. <MiniNote>If this is not specified, hyperglass will try to create a "pretty" display name based on the `name` field.</MiniNote> |
| `info` | | <Link to="#info">Per-VRF Contextual Help Configuration</Link> |
| `ipv4` | | <Link to="#ipv4">VRF's IPv4 Configuration</Link> |
| `ipv6` | | <Link to="#ipv6">VRF's IPv6 Configuration</Link> |
| `info` | | [Per-VRF Contextual Help Configuration](#info) |
| `ipv4` | | [VRF's IPv4 Configuration](#ipv4) |
| `ipv6` | | [VRF's IPv6 Configuration](#ipv6) |
#### `ipv4`

4
docs/docs/logging.mdx
View File

@@ -1,7 +1,7 @@
---
id: logging
title: Logging
sidebar_label: Logging
title: Logging & Webhooks
sidebar_label: Logging & Webhooks
keywords: [hyperglass, logging, webhook, hooks, syslog]
description: hyperglass Logging
---

6
docs/docs/queries.mdx
View File

@@ -1,7 +1,7 @@
---
id: queries
title: Queries
sidebar_label: Queries
id: query-settings
title: Query Settings
sidebar_label: Query Settings
keywords: [hyperglass, queries]
description: hyperglass query types
---

8
docs/docs/api.mdx → docs/docs/rest-api.mdx
View File

@@ -1,9 +1,9 @@
---
id: api
title: API
sidebar_label: API
id: rest-api
title: REST API
sidebar_label: REST API
keywords: [configuration, api, rest]
description: hyperglass API configuration
description: Configure the REST API
---
import Link from "@docusaurus/Link";

4
docs/docs/setup.mdx
View File

@@ -63,7 +63,7 @@ $ sudo systemctl enable hyperglass
## UI Build
hyperglass is build with [NextJS](https://nextjs.org/), a [React](https://reactjs.org/)-based UI framework that supports server-side rendering and static exporting, which contribute to hyperglass's speed and SEO-friendliness. At startup, hyperglass creates a new "UI build", which is a static export of the site and includes some elements of the [configuration](configuration.mdx).
hyperglass is build with [NextJS](https://nextjs.org/), a [React](https://reactjs.org/)-based UI framework that supports server-side rendering and static exporting, which contribute to hyperglass's speed and SEO-friendliness. At startup, hyperglass creates a new "UI build", which is a static export of the site and includes some elements of the [configuration](parameters).
It is recommended to run an initial UI build after running the setup wizard, so that you can verify that the installation is working prior to diving into configuration.
@@ -71,3 +71,5 @@ It is recommended to run an initial UI build after running the setup wizard, so
$ hyperglass build-ui
✅ Completed UI build in production mode
```
The UI build will run automatically any time the hyperglass configuration or version changes.

14
docs/docs/structured-data.mdx
View File

@@ -1,10 +1,18 @@
---
id: structured-data
title: Structured Data
sidebar_label: Structured Data
id: table-output
title: Table Output
sidebar_label: Table Output
description: Configure structured data parameters
---
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](rest-api)). Currently, the following platforms have structured data supported in hyperglass:
- Juniper Junos
:::note
Unlike with standard text output, devices with structured data enabled do not support customization of their commands. This is because the response must be something hyperglass is preconfigured to understand and parse, so hyperglass must maintain control over the specific command to run for a given platform.
:::
<div class="table--full-width" />
The `structured` subsection contains multiple subsections of its own:

26
docs/sidebars.js
View File

@@ -9,16 +9,26 @@ module.exports = {
type: "category",
label: "Configuration",
items: [
"configuration",
"queries",
"logging",
"cache",
"devices",
"parameters",
"adding-devices",
"commands",
"ui",
"api",
"logging",
"messages",
"structured-data",
"query-settings",
"response-caching",
"rest-api",
"table-output",
{
type: "category",
label: "Web UI",
items: [
"ui/configuration",
"ui/logo",
"ui/text",
"ui/theme",
"ui/example",
],
},
],
},
{

25
docs/src/components/fonts.module.css
View File

@@ -2,20 +2,23 @@
@import url("https://fonts.googleapis.com/css?family=Fira+Code|Nunito&display=swap");
.font {
background-color: var(--ifm-blockquote-color);
padding: 0.2rem;
color: var(--ifm-code-color);
border-radius: var(--ifm-code-border-radius);
width: 100%;
height: 100%;
text-decoration: none;
display: inline-block;
text-align: center;
background-color: var(--ifm-color-emphasis-200);
padding-top: 0.2rem;
padding-bottom: 0.2rem;
padding-right: 0.5rem;
padding-left: 0.5rem;
color: var(--ifm-color-emphasis-900);
border-radius: var(--ifm-code-border-radius);
width: 100%;
height: 100%;
text-decoration: none;
display: inline-block;
text-align: center;
}
.fontBody {
font-family: Nunito, sans-serif;
font-family: Nunito, sans-serif;
}
.fontMono {
font-family: "Fira Code", monospace;
font-family: "Fira Code", monospace;
}

25
docs/src/css/custom.css
View File

@@ -44,16 +44,19 @@
:root {
--ifm-menu-color-active: black;
--ra-color-link: var(--ifm-color-black);
--ra-color-caution: var(--ifm-color-warning-lightest);
--ra-color-tip: var(--ifm-color-success-lightest);
--ra-color-important: var(--ifm-color-info-lightest);
--ra-color-note: var(--ifm-color-gray-200);
--ra-color-warning: var(--ifm-color-danger-lighter);
--ra-admonition-color: var(--ifm-font-base-color);
--ifm-alert-background-color: var(--ifm-color-gray-400);
}
html[data-theme="dark"]:root {
--ifm-menu-color-active: var(--ifm-color-primary);
--ra-color-link: var(--ifm-color-black);
--ra-color-caution: var(--ifm-color-warning-darkest);
--ra-color-tip: var(--ifm-color-success-darkest);
--ra-color-important: var(--ifm-color-info-darkest);
@@ -62,6 +65,19 @@ html[data-theme="dark"]:root {
--ifm-blockquote-color: var(--ifm-color-emphasis-400);
}
.admonition.alert {
--ra-admonition-icon-color: currentColor;
}
html[data-theme="dark"]:root .admonition.alert.admonition-note {
--ifm-alert-background-color: var(--ifm-color-gray-600);
}
.admonition.alert.admonition-note {
--ifm-alert-background-color: var(--ifm-color-gray-300);
--ifm-alert-color: var(--ifm-color-black);
}
html[data-theme="dark"] .footer.footer--dark {
--ifm-footer-color: var(--ifm-color-emphasis-400);
--ifm-navbar-background-color: var(--ifm-background-color);
@@ -96,16 +112,17 @@ html[data-theme="dark"] {
.admonition.alert--success .admonition-content a,
.admonition.alert--warning .admonition-content a,
.admonition.alert--critical .admonition-content a {
color: var(--ifm-color-black);
.admonition.alert--critical .admonition-content a,
.admonition.alert--info .admonition-content a {
color: var(--ra-color-link);
}
.admonition.admonition-note .admonition-content code {
--ifm-code-color: var(--ifm-color-gray-900);
}
.admonition a:hover {
color: rgba(0, 0, 0, 0.5);
.admonition .admonition-content a:hover {
color: rgba(0, 0, 0, 0.7);
}
.docusaurus-highlight-code-line {

36
docs/static/sitemap.xml vendored
View File

@@ -1,9 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://hyperglass.io/docs/api</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/cache</loc>
</url>
@@ -40,6 +36,10 @@
<loc>https://hyperglass.io/docs/messages</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/oldui</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/platforms</loc>
</url>
@@ -52,6 +52,10 @@
<loc>https://hyperglass.io/docs/queries</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/rest-api</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/setup</loc>
</url>
@@ -60,10 +64,6 @@
<loc>https://hyperglass.io/docs/structured-data</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/ui</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/upgrading</loc>
</url>
@@ -75,4 +75,24 @@
<url>
<loc>https://hyperglass.io/docs/agent/setup</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/ui/configuration</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/ui/example</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/ui/logo</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/ui/text</loc>
</url>
<url>
<loc>https://hyperglass.io/docs/ui/theme</loc>
</url>
</urlset>

3
hyperglass/configuration/models/structured.py
View File

@@ -4,7 +4,7 @@
from typing import List
# Third Party
from pydantic import StrictInt, StrictStr, constr
from pydantic import StrictStr, constr
# Project
from hyperglass.models import HyperglassModel
@@ -21,7 +21,6 @@ class StructuredRpki(HyperglassModel):
"""Control structured data response for RPKI state."""
mode: constr(regex=r"(router|external)") = "router"
max_age: StrictInt = 24
class Structured(HyperglassModel):

1
hyperglass/external/rpki.py vendored
View File

@@ -1,5 +1,6 @@
"""Validate RPKI state via Cloudflare GraphQL API."""
# Project
from hyperglass.log import log
from hyperglass.external._base import BaseExternal