From e50cd05fa3bbb98577cd081ecd545dc5dd949ea0 Mon Sep 17 00:00:00 2001 From: checktheroads Date: Sun, 21 Jun 2020 14:12:08 -0700 Subject: [PATCH] docs restructure --- docs/docs/cache.mdx | 8 ++--- docs/docs/commands.mdx | 16 ++++----- docs/docs/configuration.mdx | 12 +++---- docs/docs/devices.mdx | 30 ++++++++-------- docs/docs/logging.mdx | 4 +-- docs/docs/queries.mdx | 6 ++-- docs/docs/{api.mdx => rest-api.mdx} | 8 ++--- docs/docs/setup.mdx | 4 ++- docs/docs/structured-data.mdx | 14 ++++++-- docs/sidebars.js | 26 +++++++++----- docs/src/components/fonts.module.css | 25 +++++++------ docs/src/css/custom.css | 25 ++++++++++--- docs/static/sitemap.xml | 36 ++++++++++++++----- hyperglass/configuration/models/structured.py | 3 +- hyperglass/external/rpki.py | 1 + 15 files changed, 139 insertions(+), 79 deletions(-) rename docs/docs/{api.mdx => rest-api.mdx} (98%) diff --git a/docs/docs/cache.mdx b/docs/docs/cache.mdx index 25a33e5..f8903f6 100644 --- a/docs/docs/cache.mdx +++ b/docs/docs/cache.mdx @@ -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. diff --git a/docs/docs/commands.mdx b/docs/docs/commands.mdx index 6b3b032..615106b 100644 --- a/docs/docs/commands.mdx +++ b/docs/docs/commands.mdx @@ -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: diff --git a/docs/docs/configuration.mdx b/docs/docs/configuration.mdx index 746ace0..55f555a 100644 --- a/docs/docs/configuration.mdx +++ b/docs/docs/configuration.mdx @@ -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). diff --git a/docs/docs/devices.mdx b/docs/docs/devices.mdx index b9b17eb..126d8a1 100644 --- a/docs/docs/devices.mdx +++ b/docs/docs/devices.mdx @@ -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"; | `network` | String | Primary network this device is a member of. Used for device grouping. Usually something like 'AS65000'. | | `display_name` | String | Device's user-facing name. | | `port` | Integer | TCP port used to connect to the device. | -| `nos` | String | Network Operating System. Must be a supported platform. | +| `nos` | String | Network Operating System. Must be a supported platform. | | `structured_output` | Boolean | Disabled output parsing to structured data. | | `credential` | | [Device Credential Configuration](#credential) | | `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 | -| :---------------- | :-----: | :------------ | :--------------------------------------------------------------------------------------------------------------------- | -| `name` | String | | Proxy hostname. | -| `address` | String | | Proxy management hostname or IP address. | -| `credential` | | | Proxy Credential Configuration | -| `nos` | String | `'linux_ssh'` | Proxy's network operating system. Must be a supported platform. | -| `port` | Integer | `22` | TCP port user to connect to the proxy. | +| Parameter | Type | Default | Description | +| :---------------- | :-----: | :------------ | :--------------------------------------------------------------------------------------------------------------- | +| `name` | String | | Proxy hostname. | +| `address` | String | | Proxy management hostname or IP address. | +| `credential` | | | [Proxy Credential Configuration](#credential) | +| `nos` | String | `'linux_ssh'` | Proxy's network operating system. Must be a supported platform. | +| `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 | :------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | String | The VRF's name, as known **by the device**. hyperglass sends this field to the device for queries, so it needs to match the device's configuration. | | `display_name` | String | The VRF's user-facing name. This field's value is visible in the UI. If this is not specified, hyperglass will try to create a "pretty" display name based on the `name` field. | -| `info` | | Per-VRF Contextual Help Configuration | -| `ipv4` | | VRF's IPv4 Configuration | -| `ipv6` | | VRF's IPv6 Configuration | +| `info` | | [Per-VRF Contextual Help Configuration](#info) | +| `ipv4` | | [VRF's IPv4 Configuration](#ipv4) | +| `ipv6` | | [VRF's IPv6 Configuration](#ipv6) | #### `ipv4` diff --git a/docs/docs/logging.mdx b/docs/docs/logging.mdx index 5d5bb36..e550db7 100644 --- a/docs/docs/logging.mdx +++ b/docs/docs/logging.mdx @@ -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 --- diff --git a/docs/docs/queries.mdx b/docs/docs/queries.mdx index 789443b..df9c889 100644 --- a/docs/docs/queries.mdx +++ b/docs/docs/queries.mdx @@ -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 --- diff --git a/docs/docs/api.mdx b/docs/docs/rest-api.mdx similarity index 98% rename from docs/docs/api.mdx rename to docs/docs/rest-api.mdx index dff1da2..d74c4dc 100644 --- a/docs/docs/api.mdx +++ b/docs/docs/rest-api.mdx @@ -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"; diff --git a/docs/docs/setup.mdx b/docs/docs/setup.mdx index dbd4962..c619a20 100644 --- a/docs/docs/setup.mdx +++ b/docs/docs/setup.mdx @@ -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. diff --git a/docs/docs/structured-data.mdx b/docs/docs/structured-data.mdx index 5d96b97..bff1f1b 100644 --- a/docs/docs/structured-data.mdx +++ b/docs/docs/structured-data.mdx @@ -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. +::: +
The `structured` subsection contains multiple subsections of its own: diff --git a/docs/sidebars.js b/docs/sidebars.js index aac90e2..3d0753e 100755 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -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", + ], + }, ], }, { diff --git a/docs/src/components/fonts.module.css b/docs/src/components/fonts.module.css index b333fa9..f5b090f 100644 --- a/docs/src/components/fonts.module.css +++ b/docs/src/components/fonts.module.css @@ -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; } diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index a14e924..f5e437f 100755 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -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 { diff --git a/docs/static/sitemap.xml b/docs/static/sitemap.xml index 90fb081..7145cbd 100644 --- a/docs/static/sitemap.xml +++ b/docs/static/sitemap.xml @@ -1,9 +1,5 @@ - - https://hyperglass.io/docs/api - - https://hyperglass.io/docs/cache @@ -40,6 +36,10 @@ https://hyperglass.io/docs/messages + + https://hyperglass.io/docs/oldui + + https://hyperglass.io/docs/platforms @@ -52,6 +52,10 @@ https://hyperglass.io/docs/queries + + https://hyperglass.io/docs/rest-api + + https://hyperglass.io/docs/setup @@ -60,10 +64,6 @@ https://hyperglass.io/docs/structured-data - - https://hyperglass.io/docs/ui - - https://hyperglass.io/docs/upgrading @@ -75,4 +75,24 @@ https://hyperglass.io/docs/agent/setup + + + https://hyperglass.io/docs/ui/configuration + + + + https://hyperglass.io/docs/ui/example + + + + https://hyperglass.io/docs/ui/logo + + + + https://hyperglass.io/docs/ui/text + + + + https://hyperglass.io/docs/ui/theme + diff --git a/hyperglass/configuration/models/structured.py b/hyperglass/configuration/models/structured.py index a2fa1a6..ed0bef3 100644 --- a/hyperglass/configuration/models/structured.py +++ b/hyperglass/configuration/models/structured.py @@ -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): diff --git a/hyperglass/external/rpki.py b/hyperglass/external/rpki.py index 5e035b4..691ce90 100644 --- a/hyperglass/external/rpki.py +++ b/hyperglass/external/rpki.py @@ -1,5 +1,6 @@ """Validate RPKI state via Cloudflare GraphQL API.""" +# Project from hyperglass.log import log from hyperglass.external._base import BaseExternal