1
0
Fork 1
mirror of https://github.com/thatmattlove/hyperglass.git synced 2026-01-17 08:48:05 +00:00

docs updates

This commit is contained in:
checktheroads 2020-02-11 00:36:43 -07:00
parent 268c1a0cea
commit 666bc8c091
9 changed files with 430 additions and 29 deletions

89
docs/docs/api.mdx Normal file
View file

@ -0,0 +1,89 @@
---
id: api
title: API
sidebar_label: API
keywords: [configuration, api, rest]
description: hyperglass API configuration
---
import Link from "@docusaurus/Link";
import Admonition from "react-admonitions";
import MiniNote from "../src/components/MiniNote";
import Code from "../src/components/JSXCode";
import PageLink from "../src/components/PageLink";
The hyperglass API is based on the powerful [FastAPI](https://fastapi.tiangolo.com/) framework, which includes automatic API documentation using the [OpenAPI](https://www.openapis.org/) specification. If you plan to provide your users with API access to your hyperglass instance, it is highly recommended to leave this enabled.
FastAPI provides built in support for both [Swagger UI](https://swagger.io/tools/swagger-ui/) and [Redoc](https://redocly.github.io/redoc/), which are open source projects that create a pretty web UI from an OpenAPI specification.
## Settings
| Parameter | Type | Default | Description |
| :------------ | :-----: | :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the API documentation. |
| `title` | String | `'{site_title} API Documentation'` | API documentation title. `{site_title}` will be replaced with the <Link to="/docs/configuration#global-settings"><Code>site_title</Code></Link> parameter. |
| `description` | String | | API documentation description appearing below the title. |
| `base_url` | String | `'https://lg.example.net'` | The base URL for your hyperglass site. Used by OpenAPI for dynamically creating hyperlinks. |
| `mode` | String | `'redoc'` | OpenAPI UI library to use for the hyperglass API docs. <MiniNote>Must be <Code>redoc</Code> or <Code>swagger</Code></MiniNote> |
| `uri` | String | `'/api/docs'` | HTTP URI/path where API documentation can be accessed. |
| `openapi_uri` | String | `'/openapi.json'` | Path to the automatically generated `openapi.json` file. |
| `queries` | | | `/queries` endpoint settings <PageLink to="#queries">➡️</PageLink> |
| `query` | | | `/query` endpoint settings <PageLink to="#query">➡️</PageLink> |
| `devices` | | | `/devices` endpoint settings <PageLink to="#devices">➡️</PageLink> |
### `queries`
| Parameter | Type | Default | Description |
| :------------ | :----: | :--------------------------------- | :----------------------------------------------------------- |
| `title` | String | `'Supported Queries'` | Displayed as the header text above the API endpoint section. |
| `description` | String | `'List of supported query types.'` | Displayed inside each API endpoint section. |
| `summary` | String | `'Query Types'` | Displayed beside the API endpoint URI. |
### `query`
| Parameter | Type | Default | Description |
| :------------ | :----: | :----------------------------------------- | :----------------------------------------------------------- |
| `title` | String | `'Submit Query'` | Displayed as the header text above the API endpoint section. |
| `description` | String | `'Request a query response per-location.'` | Displayed inside each API endpoint section. |
| `summary` | String | `'Query the Looking Glass'` | Displayed beside the API endpoint URI. |
### `devices`
| Parameter | Type | Default | Description |
| :------------ | :----: | :---------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |
| `title` | String | `'Devices'` | Displayed as the header text above the API endpoint section. |
| `description` | String | `'List of all devices/locations with associated identifiers, display names, networks, & VRFs.'` | Displayed inside each API endpoint section. |
| `summary` | String | `'Devices List'` | Displayed beside the API endpoint URI. |
## Example
```yaml
docs:
base_url: https://lg.example.net
description: ""
devices:
description: List of all devices/locations with associated identifiers, display
names, networks, & VRFs.
summary: Devices List
title: Devices
enable: true
mode: redoc
openapi_uri: /openapi.json
queries:
description: List of supported query types.
summary: Query Types
title: Supported Queries
query:
description: Request a query response per-location.
summary: Query the Looking Glass
title: Submit Query
title: "{site_title} API Documentation"
uri: /api/docs
```
<Admonition type="tip" title="From the developer">
I'm partial to Redoc, partially because I find it to be more aesthetically pleasing, and
partially because it's written in <a href="https://reactjs.org/">ReactJS</a>, just like the
hyperglass UI. At some point, I plan to migrate away from the built-in Redoc page and integrate
Redoc directly with hyperglass.
</Admonition>

40
docs/docs/cache.mdx Normal file
View file

@ -0,0 +1,40 @@
---
id: cache
title: Caching
sidebar_label: Caching
keywords: [configuration, cache, timeout]
description: hyperglass caching configuration
---
import Link from "@docusaurus/Link";
import Admonition from "react-admonitions";
hyperglass uses [Redis](https://redis.io/) for cache storage. Every query is cached and automatically expired from the cache after a configurable timeout period.
Common Redis parameters are configurable, in case you already have a dedicated Redis server you'd prefer to use, instead of running it on the same server as hyperglass:
| Parameter | Type | Default | Description |
| :---------- | :-----: | :------------ | :--------------------------------------------------------------------------- |
| `host` | String | `'localhost'` | Redis server IP address or hostname. |
| `port` | Integer | `6379` | Redis server TCP port. |
| `database` | Integer | `0` | 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 <Link to="/docs/ui#text">cache message</Link> in the hyperglass UI. |
<Admonition type="important" title="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.
</Admonition>
## Example
```yaml
cache:
database: 0
host: localhost
port: 6379
show_text: true
timeout: 120
```

View file

@ -9,6 +9,7 @@ description: Configuring hyperglass
import Link from "@docusaurus/Link";
import Admonition from "react-admonitions";
import MiniNote from "../src/components/MiniNote";
import PageLink from "../src/components/PageLink";
hyperglass is meant to be _extremely_ customizable, but with reasonable defaults that most operators won't need to override. Even though there are a _lot_ of configuration options, all of them can be left untouched and hyperglass will work (although, it's recommended to at least set the organization name).
@ -39,6 +40,53 @@ Configuration files may be located in one of the following directories:
- `/etc/hyperglass`
- `~/hyperglass`
# Global Settings
The following global settings can be set in `hyperglass.yaml`:
| Parameter | Type | Default | Description |
| :----------------- | :-----: | :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `debug` | Boolean | `false` | Enable application-wide debug mode. **This will generate a log of logs!** |
| `developer_mode` | Boolean | `false` | If enabled, the hyperglass backend (Python) and frontend (React/Javascript) applications are "unlinked", so that React tools can be used for front end development. A `<Debugger />` convenience component is also displayed in the UI for easier UI development.' |
| `primary_asn` | String | `'65000'` | Your network's primary ASN. This field is used to set some useful defaults such as the subtitle and PeeringDB URL. |
| `org_name` | String | `'Beloved Hyperglass User'` | Your organization's name. This field is used in the UI & API documentation to set fields such as `<meta/>` HTML tags for SEO and the terms & conditions footer component. |
| `site_title` | String | `'hyperglass'` | The name of your hyperglass site. This field is used in the UI & API documentation to set fields such as the `<title/>` HTML tag, and the terms & conditions footer component. |
| `site_description` | String | `'{org_name} Network Looking Glass'` | A short description of your hyperglass site. This field is used in th UI & API documentation to set the `<meta name="description"/>` tag. `{org_name}` may be used to insert the value of the `org_name` field. |
| `site_keywords` | List | | Keywords pertaining to your hyperglass site. This field is used to generate `<meta name="keywords"/>` HTML tags, which helps tremendously with [SEO](https://support.google.com/webmasters/answer/7451184). |
| `request_timeout` | Integer | `30` | Global timeout in seconds for all requests. The UI uses this field's exact value when submitting queries. The backend uses this field's value, minus one second, for its own timeout handling. This is to ensure a contextual timeout error is presented to the end user in the event of a backend application timeout. |
| `listen_address` | String | `'localhost'` | Local IP Address or hostname the hyperglass application listens on to serve web traffic. |
| `listen_port` | Integer | `8001` | Local TCP port the hyperglass application listens on to serve web traffic. |
| `log_file` | String | | Path to a log file to which hyperglass can write logs. If none is set, hyperglass will write logs to a file located at `/tmp/`, with a uniquely generated name for each time hyperglass is started. |
| `cors_origins` | List | `[]` | Allowed [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) hosts. By default, no CORS hosts are allowed. |
#### Example
```yaml
debug: false
developer_mode: false
org_name: Beloved Hyperglass User
site_title: hyperglass
site_description: "{org_name} Network Looking Glass"
site_keywords: [hyperglass, looking glass, routing, bgp]
request_timeout: 30
listen_address: localhost
listen_port: 8001
log_file: /tmp/hyperglass.log
cors_origins: [localhost:3000, 192.0.2.1]
```
## Subsections
From the top level, the following subsections may be defined and configured:
| Section | Description | All Options |
| :--------- | :-------------------------------------------------- | :-----------------------------------------: |
| `cache` | Redis server & cache timeout settings. | <PageLink to="/docs/cache">➡️</PageLink> |
| `docs` | API documentation settings. | <PageLink to="/docs/api">➡️</PageLink> |
| `messages` | Customize almost all user-facing UI & API messages. | <PageLink to="/docs/messages">➡️</PageLink> |
| `queries` | Enable, disable, or configure query types. | <PageLink to="/docs/queries">➡️</PageLink> |
| `web` | Web UI & branding settings. | <PageLink to="/docs/ui">➡️</PageLink> |
# Adding Devices
To add, as an example, a Cisco router, add the following to your `devices.yaml`, with the relevant details changed for your device:

View file

@ -1,17 +0,0 @@
---
id: mdx
title: Powered by MDX
---
You can write JSX and use React components within your Markdown thanks to [MDX](https://mdxjs.com/).
export const Highlight = ({children, color}) => ( <span style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}> {children} </span> );
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!

49
docs/docs/messages.mdx Normal file
View file

@ -0,0 +1,49 @@
---
id: messages
title: Messages
sidebar_label: Messages
keywords: [configuration, messages, text, ui, customization]
description: hyperglass messages configuration
---
import Link from "@docusaurus/Link";
import Code from "../src/components/JSXCode";
All user-facing status messages can be customized if needed.
| Parameter | Type | Default | Description |
| :--------------------- | :----: | :-------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `acl_denied` | String | `'"{target} is a member of {denied_network}, which is not allowed."'` | Displayed when a query target is explicitly denied by a matched VRF's ACL entry. `{target}` and `{denied_network}` will be replaced with the denied query target and the ACL entry that caused it to be denied. |
| `acl_not_allowed` | String | `'{target} is not allowed.'` | Displayed when a query target is implicitly denied by a matched VRF's ACL. `{target}` will be replaced with the denied query target. |
| `authentication_error` | String | `'Authentication error occurred.'` | Displayed when hyperglass is unable to authenticate to a configured device. Usually, this indicates a configuration error. `{device_name}` and `{error}` will be replaced with the device in question and the specific connection error. |
| `connection_error` | String | `'Error connecting to {device_name}: {error}'` | Displayed when hyperglass is unable to connect to a configured device. Usually, this indicates a configuration error. `{device_name}` and `{error}` will be replaced with the device in question and the specific connection error. |
| `feature_not_enabled` | String | `'{feature} is not enabled for {device_name}.'` | Displayed when a query type is submitted that is not supported or disabled. The UI performs validation of supported query types prior to submitting any requests, so this is primarily relevant to the hyperglass API. `{feature}` and `{device_name}` will be replaced with the disabled feature and the selected device/location. |
| `general` | String | `'Something went wrong.'` | Displayed when generalized errors occur. Seeing this error message may indicate a bug in hyperglass, as most other errors produced are highly contextual. If you see this in the wild, try enabling <Link to="/docs/configuration#global-settings"><Code>debug</Code></Link> mode and review the logs to pinpoint the source of the error. |
| `invalid_field` | String | `'{input} is an invalid {field}.'` | Displayed when a query field contains an invalid or unsupported value. `{input}` and `{field}` will be replaced with the invalid input value and corresponding field name. |
| `invalid_input` | 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}` will be replaced with the invalid target and corresponding query type. |
| `no_input` | String | `'{field} must be specified.'` | Displayed when no a required field is not specified. `{field}` will be replaced with the `display_name` of the field that was omitted. |
| `no_output` | String | `'No output.'` | Displayed when hyperglass can connect to a device and execute a query, but the response is empty. |
| `no_response` | String | `'No response.'` | Displayed when hyperglass can connect to a device, but no output is able to be read. Seeing this error may indicate a bug in hyperglass or one of its dependencies. If you see this in the wild, try enabling <Link to="/docs/configuration#global-settings"><Code>debug</Code></Link> mode and review the logs to pinpoint the source of the error. |
| `request_timeout` | String | `'Request timed out.'` | Displayed when the <Link to="/docs/configuration#global-settings"><Code>request_timeout</Code></Link> time expires. |
| `vrf_not_associated` | String | `'VRF {vrf_name} is not associated with {device_name}.'` | Displayed when a query request's VRF field value contains a VRF that is not configured or associated with the corresponding location/device. The UI automatically filters out VRFs that are not configured on a selected device, so this error is most likely to appear when using the hyperglass API. `{vrf_name}` and `{device_name}` will be replaced with the VRF in question and corresponding device. |
| `vrf_not_found` | String | `'RF {vrf_name} is not defined.'` | Displayed when a query VRF is not configured on any devices. The UI only shows configured VRFs, so this error is most likely to appear when using the hyperglass API. `{vrf_name}` will be replaced with the VRF in question. |
## Example
```yaml
messages:
acl_denied: "{target} is a member of {denied_network}, which is not allowed."
acl_not_allowed: "{target} is not allowed."
authentication_error: Authentication error occurred.
connection_error: "Error connecting to {device_name}: {error}"
feature_not_enabled: "{feature} is not enabled for {device_name}."
general: Something went wrong.
invalid_field: "{input} is an invalid {field}."
invalid_input: "{target} is not a valid {query_type} target."
no_input: "{field} must be specified."
no_output: No output.
no_response: No response.
request_timeout: Request timed out.
vrf_not_associated: VRF {vrf_name} is not associated with {device_name}.
vrf_not_found: VRF {vrf_name} is not defined.
```

49
docs/docs/queries.mdx Normal file
View file

@ -0,0 +1,49 @@
---
id: queries
title: Queries
sidebar_label: Queries
keywords: [hyperglass, queries]
description: hyperglass query types
---
import Link from "@docusaurus/Link";
import Code from "../src/components/JSXCode";
Each query type may be disabled, enabled, or customized.
## `bgp_route`
| Parameter | Type | Default | Description |
| :------------- | :-----: | :------------ | :----------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the BGP Route query type. |
| `display_name` | String | `'BGP Route'` | Text displayed for the BGP Route query type in the UI. |
## `bgp_community`
| Parameter | Type | Default | Description |
| :------------- | :-----: | :---------------- | :--------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the BGP Community query type. |
| `display_name` | String | `'BGP Community'` | Text displayed for the BGP Community query type in the UI. |
| `pattern` | | | |
## `bgp_aspath`
| Parameter | Type | Default | Description |
| :------------- | :-----: | :-------------- | :------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the BGP AS Path query type. |
| `display_name` | String | `'BGP AS Path'` | Text displayed for the BGP AS Path query type in the UI. |
| `pattern` | | | |
## `ping`
| Parameter | Type | Default | Description |
| :------------- | :-----: | :------- | :------------------------------------------------ |
| `enable` | Boolean | `true` | Enable or disable the Ping query type. |
| `display_name` | String | `'Ping'` | Text displayed for the Ping query type in the UI. |
## `traceroute`
| Parameter | Type | Default | Description |
| :------------- | :-----: | :------------- | :------------------------------------------------------ |
| `enable` | Boolean | `true` | Enable or disable the Traceroute query type. |
| `display_name` | String | `'Traceroute'` | Text displayed for the Traceroute query type in the UI. |

View file

@ -13,12 +13,9 @@ import MiniNote from "../src/components/MiniNote";
import Code from "../src/components/JSXCode";
import Color from "../src/components/Color";
import Font from "../src/components/Font";
import PageLink from "../src/components/PageLink";
export const PageLink = ({ children, to }) => (
<Link to={to} style={{ textDecoration: "unset" }}>
{children}
</Link>
);
The `web` subsection contains multiple subsections of its own, should you wish to customize various aspects of the UI:
| Section | Description | All Options |
| :-------------- | :----------------------------- | :-----------------------------------------: |
@ -30,6 +27,72 @@ export const PageLink = ({ children, to }) => (
| `terms` | Terms & Conditions | <PageLink to="#terms">➡️</PageLink> |
| `theme` | Colors & Fonts | <PageLink to="#theme">➡️</PageLink> |
## Example
```yaml
web:
credit:
enable: true
dns_provider:
name: google
url: https://dns.google/resolve
external_link:
enable: true
title: PeeringDB
url: https://www.peeringdb.com/AS{primary_asn}
help_menu:
enable: true
file: null
title: Help
logo:
dark: /images/hyperglass-light.png
favicons: ui/images/favicons/
height: null
light: /images/hyperglass-dark.png
width: 384
opengraph:
height: 1132
image: /images/hyperglass-opengraph.png
width: 7355
terms:
enable: true
file: null
title: Terms
text:
cache: Results will be cached for 2 minutes.
fqdn_tooltip: 'Use {protocol}'
query_location: Location
query_target: Target
query_type: Query Type
query_vrf: Routing Table
subtitle: AS65001
title: hyperglass
title_mode: text_only
theme:
colors:
black: "#262626"
blue: "#314cb6"
cyan: "#118ab2"
danger: "#d84b4b"
error: "#ff6b35"
gray: "#c1c7cc"
green: "#35b246"
orange: "#ff6b35"
pink: "#f2607d"
primary: "#118ab2"
purple: "#8d30b5"
red: "#d84b4b"
secondary: "#314cb6"
success: "#35b246"
teal: "#35b299"
warning: "#edae49"
white: "#f7f7f7"
yellow: "#edae49"
fonts:
body: Nunito
mono: Fira Code
```
## `credit`
| Parameter | Type | Default | Description |
@ -52,11 +115,11 @@ export const PageLink = ({ children, to }) => (
## `external_link`
| Parameter | Type | Default | Description |
| :-------- | :-----: | :-------------------------------------------- | :------------------------------------------------ |
| `enable` | Boolean | `true` | Enable or disable the display of an external link |
| `title` | String | `'PeeringDB'` | Link title/label |
| `url` | String | `'https://www.peeringdb.com/AS{primary_asn}'` | Target URL |
| Parameter | Type | Default | Description |
| :-------- | :-----: | :-------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the display of an external link |
| `title` | String | `'PeeringDB'` | Link title/label |
| `url` | String | `'https://www.peeringdb.com/AS{primary_asn}'` | Target URL. `{primary_asn}` will be replaced with the `primary_asn` value from <Link to="/docs/configuration#global-settings">Global Settings</Link> |
## `logo`
@ -87,6 +150,67 @@ By default, no Opengraph image is set. If you define one with `image`, hyperglas
| `file` | String | | Path to a plain text or markdown file with content to override the default terms & conditions |
| `title` | String | `'Terms'` | Terms & conditions title |
## `text`
| Parameter | Type | Default | Description |
| :--------------- | :----: | :------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cache` | String | `'Results will be cached for {timeout} {period}.'` | User-facing text regarding the cache timeout. `{timeout}` and `{period}` are replaced with the a generated value derived from the length of the <Link to="/docs/configuration#global-settings"><Code>request_timeout</Code></Link> setting. |
| `fqdn_tooltip` | String | `'Use {protocol}'` | Text displayed when a user hovers over the IPv4 or IPv6 button on an FQDN target resolved by DNS. `{protocol}` is replaced with the relevant IP protocol. |
| `query_location` | String | `'Location'` | Query Location (router) form label. |
| `query_target` | String | `'Target'` | Query Target (IP/hostname/community/AS Path) form label. |
| `query_type` | String | `'Query Type'` | Query Type (BGP Route, Ping, Traceroute, etc.) form label. |
| `query_vrf` | String | `'Routing Table'` | Query VRF form label. |
| `subtitle` | String | `'AS{primary_asn}'` | Subtitle text. `{primary_asn}` will be replaced with the <PageLink to="/docs/configuration#global-settings"><Code>primary_asn</Code></PageLink> value. |
| `title` | String | `'hyperglass'` | Title text. |
| `title_mode` | String | `'text_only'` | Set the title mode. <MiniNote>Must be <Code>text_only</Code>, <Code>logo_only</Code>, <Code>logo_title</Code>, or <Code>all</Code></MiniNote> |
<Admonition type="important" title="Title Mode">
The <Code>title_mode</Code> parameter behaves in the following manner:
<br/>
<table>
<thead>
<tr>
<th align="left">Mode</th>
<th>Behavior</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<Code>text_only</Code>
</td>
<td>
Shows the <Code>title</Code> and <Code>subtitle</Code> only.
</td>
</tr>
<tr>
<td>
<Code>logo_only</Code>
</td>
<td>
Shows the <Link to="#logo"><Code>logo</Code></Link> only.
</td>
</tr>
<tr>
<td>
<Code>logo_title</Code>
</td>
<td>
Shows the <Link to="#logo"><Code>logo</Code></Link> and <Code>title</Code> only.
</td>
</tr>
<tr>
<td>
<Code>all</Code>
</td>
<td>
Shows the <Link to="#logo"><Code>logo</Code></Link>, <Code>title</Code>, and <Code>subtitle</Code>.
</td>
</tr>
</tbody>
</table>
</Admonition>
## `theme`
| Section | Description | All Options |
@ -125,3 +249,5 @@ Currently, only [Google Fonts](https://fonts.google.com/) are supported.
| :-------- | :----: | :----------------------- | :-------------------------------------- |
| `body` | String | <Font name='Nunito'/> | Main body font |
| `mono` | String | <Font name='Fira Code'/> | Monospace font, used for command output |

View file

@ -3,9 +3,18 @@ module.exports = {
{
type: "category",
label: "Installation",
items: ["introduction", "getting-started", "configuration", "devices", "ui"]
items: [
"introduction",
"getting-started",
"configuration",
"devices",
"ui",
"cache",
"api",
"messages",
"queries"
]
},
{ type: "category", label: "Features", items: ["mdx"] },
{ type: "doc", id: "platforms" }
]
};

View file

@ -0,0 +1,8 @@
import React from "react";
import Link from "@docusaurus/Link";
export default ({ children, to }) => (
<Link to={to} style={{ textDecoration: "unset" }}>
{children}
</Link>
);