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

docs updates

Browse source
This commit is contained in:
checktheroads 2020-02-10 09:06:20 -07:00
parent 2606d01801
commit 96fced9e33
13 changed files with 438 additions and 242 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

227
docs/docs/configuration.mdx
View file

@ -8,9 +8,7 @@ description: Configuring hyperglass
import Link from "@docusaurus/Link";
import Admonition from "react-admonitions";
import R from "../src/components/Required";
import MiniNote from "../src/components/MiniNote";
import Code from "../src/components/JSXCode";
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).
@ -26,13 +24,15 @@ hyperglass configuration consists of three separate [YAML](https://yaml.org/) co
- `hyperglass.yaml`
- Defines configuration parameters for the application and UI
- _This file is not required for hyperglass to run_
<MiniNote>This file is not required for hyperglass to run</MiniNote>
- `devices.yaml`
- Defines devices (routers), SSH proxy servers, and credentials
- **This file is required for hyperglass to run**
<MiniNote>
This file <strong>is required</strong> for hyperglass to run
</MiniNote>
- `commands.yaml`
- Defines commands for custom network operating systems, or overrides default hyperglass command sets.
- _This file is not required for hyperglass to run_
<MiniNote>This file is not required for hyperglass to run</MiniNote>
Configuration files may be located in one of the following directories:
@ -63,7 +63,7 @@ routers:
source_address: 2001:db8::1
```
There are a lot more options, but this is enough to get started.
There are a lot more options, but this is enough to get started. For all device configuration options, <Link to="/docs/devices">see here</Link>.
<Admonition type="tip" iconType="emoji" title="YAML">
If you have a lot of devices with shared configuration parameters, you may want to look into{" "}
@ -74,218 +74,3 @@ There are a lot more options, but this is enough to get started.
</a>
.
</Admonition>
## All Device Parameters
| Parameter | Type | Description |
| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| <R/> `name` | String | Device hostname. This is not user-facing. |
| <R/> `address` | String | Device management hostname or IP address. |
| <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/>`credential` | | <Link to="#credential">Device Credential Configuration</Link> |
| <R/>`vrfs` | | <Link to="#vrf">Device VRF Configuration</Link> |
| `proxy` | | <Link to="#proxy">SSH Proxy Configuration</Link> |
| `ssl` | | <Link to="#ssl">SSL Configuration</Link> for devices using [hyperglass-agent](https://github.com/checktheroads/hyperglass-agent). |
### `proxy`
Any device that uses SSH (see <Link to="/docs/platforms">platforms</Link> 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. |
<Admonition type="note">
Currently only <Code>linux_ssh</Code> has been tested and validated for use as an SSH proxy.
</Admonition>;
### `credential`
While all devices require a credential mapping, the credential values themselves may be used in different ways depending on the device NOS. For SSH devices, the credential is used as a typical SSH username and password.
For HTTP devices (i.e. devices using [hyperglass-agent](https://github.com/checktheroads/hyperglass-agent)), the username is ignored and the password is used as a secret for [JSON Web Token](https://tools.ietf.org/html/rfc7519) encoding/decoding.
| Parameter | Type | Description |
| --------------- | ------ | ------------------------------------------------------------ |
| <R/> `username` | String | Username |
| <R/> `password` | String | Password <MiniNote>Passwords will never be logged</MiniNote> |
### `ssl`
HTTP devices may optionally use SSL for the connection between hyperglass and the device. This is **disabled** by default, which means devices will use unencrypted HTTP by default.
If SSL is enabled, the public key of the device must be provided in the form of an accessible absolute file path. With SSL enabled and a valid certificate specified, every connection to the device will use HTTPS in addition to payload encoding with [JSON Web Tokens](https://tools.ietf.org/html/rfc7519).
| Parameter | Type | Description |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enable` | Boolean | Enable or disable the use of SSL. <MiniNote>If enabled, a certificate file must be specified (hyperglass does not support connecting to a device over an unverified SSL session).</MiniNote> |
| <R/> `cert` | String | Absolute path to agent's public RSA key. |
### `vrfs`
The VRFs section is a list of available VRFs for a given device. Each VRF may be configured with the following fields:
| Parameter | Type | Description |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <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> |
#### `ipv4`
May be set to `null` to disable IPv4 for this VRF, on the parent device.
| Parameter | Type | Description |
| --------------------- | ------ | --------------------------------------------------------------------- |
| <R/> `source_address` | String | Device's source IPv4 address for directed queries (ping, traceroute). |
| `access_list` | | <Link to="#access_list">IPv4 Access List Configuration</Link> |
#### `ipv6`
May be set to `null` to disable IPv6 for this VRF, on the parent device.
| Parameter | Type | Description |
| --------------------- | ------ | --------------------------------------------------------------------- |
| <R/> `source_address` | String | Device's source IPv6 address for directed queries (ping, traceroute). |
| `access_list` | | <Link to="#access_list">IPv6 Access List Configuration</Link> |
#### `access_list`
The `access_list` block can be thought of like a prefix-list from Cisco IOS. It is a list of rules, where the first matching rule is the action executed.
| Parameter | Type | Default | Description |
| -------------- | ------- | ------------- | --------------------------------------------------------------------------- |
| <R/> `network` | String | | This rule's IPv4 or IPv6 base prefix |
| `action` | String | `'permit'` | This rule's action. Must be `permit` or `deny` |
| `ge` | Integer | `0` | To match this rule, the target prefix must be greater than or equal to `ge` |
| `le` | Integer | `32` \| `128` | To match this rule, the target prefix must be less than or equal to `le` |
#### `info`
Each VRF may enable, disable, or customize the contextual help menu for each enabled query type. The following parameters may be defined under any query type:
| Parameter | Type | Default | Description |
| --------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the help menu for this command. |
| `file` | String | | Path to a plain text or markdown file containing customized help information for this command. |
| `params` | Object | | Any arbitrary key/value pairs where the value will replace any occurrences of the key when wrapped in braces (e.g. `{key}`) |
For example:
```yaml
info:
bgp_route:
enable: true
file: /etc/hyperglass/customer_bgp_route.md
params:
vrf_name: Customer A
ping:
enable: false
bgp_community:
enable: true
file: /etc/hyperglass/customer_bgp_community.md
params:
vrf_name: Customer A
community: "65000"
```
### Full Example
Below is a full example with nearly every available knob turned:
```yaml
routers:
# HTTP/hyperglass-agent device
- name: router01
display_name: HTTP Router
address: 192.0.2.1
network:
- name: primary
display_name: AS65000
credential:
username: madeup
password: txeTTIqwhKSJi4V3tefXQASf5AyGZ6cPsycS9nYLpKk
ssl:
enable: true
cert: /etc/hyperglass/certs/router01.pem
port: 8080
nos: frr
vrfs:
- name: default
ipv4:
source_address: 192.0.2.1
access_list:
- network: 10.0.0.0/8
action: deny
ge: 8
le: 32
- network: 0.0.0.0/0
action: permit
le: 24 # Only allow /24 or smaller prefixes
ipv6:
source_address: 2001:db8::1
access_list:
- network: ::/0
action: permit
proxy: null
# SSH/netmiko device
- name: router02
address: 10.0.0.1
network:
name: primary
display_name: AS65000
credential:
username: user
password: pass
display_name: SSH Router
port: 22
nos: cisco_ios
vrfs:
- name: default
ipv4:
source_address: 192.0.2.2
access_list:
- network: 10.0.0.0/8
action: deny
ge: 8
le: 32
- network: 0.0.0.0/0
action: permit
ipv6:
source_address: 2001:db8::2
access_list:
- network: ::/0
action: permit
le: 64 # Only allow /64 or smaller prefixes
- name: special_customer
display_name: Customer Name
ipv4:
source_address: 172.16.0.1
access_list:
- network: 172.16.0.0/16
action: allow
ipv6: null # disable IPv6 for this VRF
info:
bgp_route:
file: /etc/hyperglass/help/customer_bgp_route.md
params:
customer_name: Customer Name
proxy:
name: jump_server
address: 10.0.1.100
port: 22
credential:
username: user
password: pass
nos: linux_ssh
```

228
docs/docs/devices.mdx Normal file
View file

@ -0,0 +1,228 @@
---
id: devices
title: Adding Devices
sidebar_label: Device Configuration
keywords: [hyperglass, authentication, ssl, proxy, access list, prefix list, acl, help]
description: Adding devices to hyperglass
---
import Link from "@docusaurus/Link";
import Admonition from "react-admonitions";
import R from "../src/components/Required";
import MiniNote from "../src/components/MiniNote";
import Code from "../src/components/JSXCode";
## All Device Parameters
| Parameter | Type | Description |
| :------------------ | :-----: | :-------------------------------------------------------------------------------------------------------------------------------- |
| <R/> `name` | String | Device hostname. This is not user-facing. |
| <R/> `address` | String | Device management hostname or IP address. |
| <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/>`credential` | | <Link to="#credential">Device Credential Configuration</Link> |
| <R/>`vrfs` | | <Link to="#vrf">Device VRF Configuration</Link> |
| `proxy` | | <Link to="#proxy">SSH Proxy Configuration</Link> |
| `ssl` | | <Link to="#ssl">SSL Configuration</Link> for devices using [hyperglass-agent](https://github.com/checktheroads/hyperglass-agent). |
### `proxy`
Any device that uses SSH (see <Link to="/docs/platforms">platforms</Link> 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. |
<Admonition type="note">
Currently only <Code>linux_ssh</Code> has been tested and validated for use as an SSH proxy.
</Admonition>
### `credential`
While all devices require a credential mapping, the credential values themselves may be used in different ways depending on the device NOS. For SSH devices, the credential is used as a typical SSH username and password.
For HTTP devices (i.e. devices using [hyperglass-agent](https://github.com/checktheroads/hyperglass-agent)), the username is ignored and the password is used as a secret for [JSON Web Token](https://tools.ietf.org/html/rfc7519) encoding/decoding.
| Parameter | Type | Description |
| --------------- | ------ | ------------------------------------------------------------ |
| <R/> `username` | String | Username |
| <R/> `password` | String | Password <MiniNote>Passwords will never be logged</MiniNote> |
### `ssl`
HTTP devices may optionally use SSL for the connection between hyperglass and the device. This is **disabled** by default, which means devices will use unencrypted HTTP by default.
If SSL is enabled, the public key of the device must be provided in the form of an accessible absolute file path. With SSL enabled and a valid certificate specified, every connection to the device will use HTTPS in addition to payload encoding with [JSON Web Tokens](https://tools.ietf.org/html/rfc7519).
| Parameter | Type | Description |
| :---------- | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enable` | Boolean | Enable or disable the use of SSL. <MiniNote>If enabled, a certificate file must be specified (hyperglass does not support connecting to a device over an unverified SSL session).</MiniNote> |
| <R/> `cert` | String | Absolute path to agent's public RSA key. |
### `vrfs`
The VRFs section is a list of available VRFs for a given device. Each VRF may be configured with the following fields:
| Parameter | Type | Description |
| :------------- | :----: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <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> |
#### `ipv4`
May be set to `null` to disable IPv4 for this VRF, on the parent device.
| Parameter | Type | Description |
| :-------------------- | :----: | :-------------------------------------------------------------------- |
| <R/> `source_address` | String | Device's source IPv4 address for directed queries (ping, traceroute). |
| `access_list` | | <Link to="#access_list">IPv4 Access List Configuration</Link> |
#### `ipv6`
May be set to `null` to disable IPv6 for this VRF, on the parent device.
| Parameter | Type | Description |
| :-------------------- | :----: | :-------------------------------------------------------------------- |
| <R/> `source_address` | String | Device's source IPv6 address for directed queries (ping, traceroute). |
| `access_list` | | <Link to="#access_list">IPv6 Access List Configuration</Link> |
#### `access_list`
The `access_list` block can be thought of like a prefix-list from Cisco IOS. It is a list of rules, where the first matching rule is the action executed.
| Parameter | Type | Default | Description |
| :------------- | :-----: | :-----------: | :-------------------------------------------------------------------------- |
| <R/> `network` | String | | This rule's IPv4 or IPv6 base prefix |
| `action` | String | `'permit'` | This rule's action. Must be `permit` or `deny` |
| `ge` | Integer | `0` | To match this rule, the target prefix must be greater than or equal to `ge` |
| `le` | Integer | `32` \| `128` | To match this rule, the target prefix must be less than or equal to `le` |
#### `info`
Each VRF may enable, disable, or customize the contextual help menu for each enabled query type. The following parameters may be defined under any query type:
| Parameter | Type | Default | Description |
| :-------- | :-----: | :-----: | :-------------------------------------------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the help menu for this command. |
| `file` | String | | Path to a plain text or markdown file containing customized help information for this command. |
| `params` | Object | | Any arbitrary key/value pairs where the value will replace any occurrences of the key when wrapped in braces (e.g. `{key}`) |
For example:
```yaml
info:
bgp_route:
enable: true
file: /etc/hyperglass/customer_bgp_route.md
params:
vrf_name: Customer A
ping:
enable: false
bgp_community:
enable: true
file: /etc/hyperglass/customer_bgp_community.md
params:
vrf_name: Customer A
community: "65000"
```
### Full Example
Below is a full example with nearly every available knob turned:
```yaml
routers:
# HTTP/hyperglass-agent device
- name: router01
display_name: HTTP Router
address: 192.0.2.1
network:
- name: primary
display_name: AS65000
credential:
username: madeup
password: txeTTIqwhKSJi4V3tefXQASf5AyGZ6cPsycS9nYLpKk
ssl:
enable: true
cert: /etc/hyperglass/certs/router01.pem
port: 8080
nos: frr
vrfs:
- name: default
ipv4:
source_address: 192.0.2.1
access_list:
- network: 10.0.0.0/8
action: deny
ge: 8
le: 32
- network: 0.0.0.0/0
action: permit
le: 24 # Only allow /24 or smaller prefixes
ipv6:
source_address: 2001:db8::1
access_list:
- network: ::/0
action: permit
proxy: null
# SSH/netmiko device
- name: router02
address: 10.0.0.1
network:
name: primary
display_name: AS65000
credential:
username: user
password: pass
display_name: SSH Router
port: 22
nos: cisco_ios
vrfs:
- name: default
ipv4:
source_address: 192.0.2.2
access_list:
- network: 10.0.0.0/8
action: deny
ge: 8
le: 32
- network: 0.0.0.0/0
action: permit
ipv6:
source_address: 2001:db8::2
access_list:
- network: ::/0
action: permit
le: 64 # Only allow /64 or smaller prefixes
- name: special_customer
display_name: Customer Name
ipv4:
source_address: 172.16.0.1
access_list:
- network: 172.16.0.0/16
action: allow
ipv6: null # disable IPv6 for this VRF
info:
bgp_route:
file: /etc/hyperglass/help/customer_bgp_route.md
params:
customer_name: Customer Name
proxy:
name: jump_server
address: 10.0.1.100
port: 22
credential:
username: user
password: pass
nos: linux_ssh
```

4
docs/docs/getting-started.mdx
View file

@ -72,7 +72,7 @@ echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/source
# Install
sudo apt update
sudo apt install -y nodejs yarn
sudo apt install -y nodejs yarn redis-server
```
</TabItem>
@ -85,7 +85,7 @@ curl -sL https://rpm.nodesource.com/setup_13.x | sudo bash -
# Add Yarn Package Manager
curl -sL https://dl.yarnpkg.com/rpm/yarn.repo -o /etc/yum.repos.d/yarn.repo
sudo yum -y install gcc-c++ make nodejs yarn
sudo yum -y install gcc-c++ make nodejs yarn redis
```
</TabItem>

1
docs/docs/introduction.mdx
View file

@ -35,6 +35,7 @@ hyperglass was created with the lofty goal of benefiting the internet community
- REST API with automatic, configurable OpenAPI documentation
- Modern, responsive UI built on [ReactJS](https://reactjs.org/), with [NextJS](https://nextjs.org/) & [Chakra UI](https://chakra-ui.com/)
- Query multiple devices simultaneously
- Browser-based DNS-over-HTTPS resolution of FQDN queries
<Link

127
docs/docs/ui.mdx Normal file
View file

@ -0,0 +1,127 @@
---
id: ui
title: Web UI
sidebar_label: Web UI
keywords: [web ui, gui, theme, colors, branding]
description: hyperglass Web UI Configuration
---
import Link from "@docusaurus/Link";
import Admonition from "react-admonitions";
import R from "../src/components/Required";
import MiniNote from "../src/components/MiniNote";
import Code from "../src/components/JSXCode";
import Color from "../src/components/Color";
import Font from "../src/components/Font";
export const PageLink = ({ children, to }) => (
<Link to={to} style={{ textDecoration: "unset" }}>
{children}
</Link>
);
| Section | Description | All Options |
| :-------------- | :----------------------------- | :-----------------------------------------: |
| `credit` | Developer credit & GitHub Link | <PageLink to="#credit">➡️</PageLink> |
| `dns_provider` | DNS over HTTPS Provider | <PageLink to="#dns_provider">➡️</PageLink> |
| `external_link` | Link to external site | <PageLink to="#external_link">➡️</PageLink> |
| `logo` | Logo & Favicons | <PageLink to="#logo">➡️</PageLink> |
| `opengraph` | [OpenGraph](https://ogp.me/) | <PageLink to="#opengraph">➡️</PageLink> |
| `terms` | Terms & Conditions | <PageLink to="#terms">➡️</PageLink> |
| `theme` | Colors & Fonts | <PageLink to="#theme">➡️</PageLink> |
## `credit`
| Parameter | Type | Default | Description |
| :-------- | :-----: | :-----: | :--------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the display of developer credit & link to hyperglass GitHub repository |
<Admonition title="From the developer" type="tip">
If your organization's policy allows, and you don't mind, I request that you keep{" "}
<Code>credit</Code> enabled. Remember: my goal for this project is get more networks to use
looking glasses to make all of our lives easier. <br />
<br /> Because it's primarily other network operators that will use this tool to begin with, I'd
love for any operators that use your looking glass to know where they can get their own.
</Admonition>
## `dns_provider`
| Parameter | Type | Default | Description |
| :-------- | :----: | :------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | `'cloudflare'` | DNS over HTTPS provider for in-browser DNS resolution. Cloudflare & Google supported. <MiniNote>Must be <Code>cloudflare</Code> or <Code>google</Code></MiniNote> |
## `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 |
## `logo`
| Parameter | Type | Default | Description |
| :-------- | :-----: | :----------------------------------------------------------- | :------------------------------------------- |
| `light` | String | `'hyperglass/hyperglass/static/images/hyperglass-dark.png'` | Path to logo that will be used in light mode |
| `dark` | String | `'hyperglass/hyperglass/static/images/hyperglass-light.png'` | Path to logo that will be used in dark mode |
| `width` | Integer | `384` | Maximum logo width in pixels |
| `height` | Integer | | Maximum logo height in pixels |
## `opengraph`
If you're not familiar with [OpenGraph](https://ogp.me/), it's the thing that generates the pretty pictures, titles, and descriptions for links when you post them to sites/tools such as Facebook, Twitter, Slack, etc.
By default, no Opengraph image is set. If you define one with `image`, hyperglass will try to determine the image's dimensions automatically. Or, you can override those dimensions with the `width` and `height` parameters.
| Parameter | Type | Description |
| :-------- | :-----: | :---------------------- |
| `image` | String | Path to opengraph image |
| `width` | Integer | Opengraph image width |
| `height` | Integer | Opengraph image height |
## `terms`
| Parameter | Type | Default | Description |
| :-------- | :-----: | :-------- | :-------------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or display the display of terms & conditions |
| `file` | String | | Path to a plain text or markdown file with content to override the default terms & conditions |
| `title` | String | `'Terms'` | Terms & conditions title |
## `theme`
| Section | Description | All Options |
| :------- | :----------- | :----------------------------------: |
| `colors` | Theme colors | <PageLink to="#colors">➡️</PageLink> |
| `fonts` | Theme fonts | <PageLink to="#fonts">➡️</PageLink> |
### `colors`
| Parameter | Type | Default | Description |
| :---------- | :----: | :--------------------- | :------------------------------------- |
| `primary` | String | | Primary accent color |
| `secondary` | String | | Secondary accent color |
| `success` | String | | Success message/status color |
| `warning` | String | | Warning message/status color |
| `error` | String | | Error message/status color |
| `danger` | String | | Danger message/status color |
| `black` | String | <Color hex="#262626"/> | Used as background color in dark mode |
| `white` | String | <Color hex="#f7f7f7"/> | Used as background color in light mode |
| `red` | String | <Color hex="#d84b4b"/> | Used as `danger` color if undefined |
| `orange` | String | <Color hex="#ff6b35"/> | Used as `error` color if undefined |
| `yellow` | String | <Color hex="#edae49"/> | Used as `warning` color if undefined |
| `green` | String | <Color hex="#35b246"/> | Used as `success` color if undefined |
| `cyan` | String | <Color hex="#118ab2"/> | Used as `primary` color if undefined |
| `blue` | String | <Color hex="#314cb6"/> | Used as `secondary` color if undefined |
| `teal` | String | <Color hex="#35b299"/> | |
| `pink` | String | <Color hex="#f2607d"/> | |
| `purple` | String | <Color hex="#8d30b5"/> | |
| `gray` | String | <Color hex="#c1c7cc"/> | |
### `fonts`
Currently, only [Google Fonts](https://fonts.google.com/) are supported.
| Parameter | Type | Default | Description |
| :-------- | :----: | :----------------------- | :-------------------------------------- |
| `body` | String | <Font name='Nunito'/> | Main body font |
| `mono` | String | <Font name='Fira Code'/> | Monospace font, used for command output |

2
docs/sidebars.js
View file

@ -3,7 +3,7 @@ module.exports = {
{
type: "category",
label: "Installation",
items: ["introduction", "getting-started", "configuration"]
items: ["introduction", "getting-started", "configuration", "devices", "ui"]
},
{ type: "category", label: "Features", items: ["mdx"] },
{ type: "doc", id: "platforms" }

9
docs/src/components/Color.js Normal file
View file

@ -0,0 +1,9 @@
import React from "react";
import styles from "./styles.module.css";
export default ({ hex }) => (
<div className={styles.colorCode}>
<span style={{ backgroundColor: hex }} className={styles.color} />
<span className={styles.code}>{hex}</span>
</div>
);

12
docs/src/components/Font.js Normal file
View file

@ -0,0 +1,12 @@
import React from "React";
import classnames from "classnames";
import styles from "./fonts.module.css";
export default ({ name }) => {
const fontClass = { Nunito: "fontBody", "Fira Code": "fontMono" };
return (
<a href={`https://fonts.google.com/specimen/${name.split(" ").join("+")}`}>
<span className={classnames(styles.font, styles[fontClass[name]])}>{name}</span>
</a>
);
};

17
docs/src/components/JSXCode.js
View file

@ -1,17 +1,4 @@
import React from "react";
import styles from "./styles.module.css";
export default ({ children }) => (
<span
style={{
backgroundColor: "var(--ifm-code-background)",
color: "var(--ifm-code-color)",
fontFamily: "var(--ifm-font-family-monospace)",
fontSize: "var(--ifm-code-font-size)",
borderRadius: "var(--ifm-code-border-radius)",
margin: 0,
padding: "var(--ifm-code-padding-vertical) var(--ifm-code-padding-horizontal)"
}}
>
{children}
</span>
);
export default ({ children }) => <span className={styles.code}>{children}</span>;

4
docs/src/components/MiniNote.js
View file

@ -1,8 +1,8 @@
import React from "react";
export default ({ children }) => (
export default ({ children, newLine = true }) => (
<>
<br />
{newLine && <br />}
<span
style={{
fontSize: "var(--ifm-font-size-sm)",

21
docs/src/components/fonts.module.css Normal file
View file

@ -0,0 +1,21 @@
@import url("https://fonts.googleapis.com/css?family=Nunito&display=swap");
@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;
}
.fontBody {
font-family: Nunito, sans-serif;
}
.fontMono {
font-family: "Fira Code", monospace;
}

25
docs/src/components/styles.module.css Normal file
View file

@ -0,0 +1,25 @@
.code {
background-color: var(--ifm-code-background);
color: var(--ifm-code-color);
font-family: var(--ifm-font-family-monospace);
font-size: var(--ifm-code-font-size);
border-radius: var(--ifm-code-border-radius);
margin: 0;
padding: var(--ifm-code-padding-vertical) var(--ifm-code-padding-horizontal);
font-style: normal;
}
.color {
border-radius: var(--ifm-global-radius);
display: inline-flex;
height: 1.5rem;
width: 1.5rem;
margin-right: 0.5rem;
padding: var(--ifm-code-padding-vertical) var(--ifm-code-padding-horizontal);
}
.colorCode {
display: flex;
align-items: center;
justify-content: space-between;
}

3
hyperglass/configuration/models/web.py
View file

@ -186,7 +186,7 @@ class ThemeColors(HyperglassLevel4):
white: Color = "#f7f7f7"
gray: Color = "#c1c7cc"
red: Color = "#d84b4b"
orange: Color = "ff6b35"
orange: Color = "#ff6b35"
yellow: Color = "#edae49"
green: Color = "#35b246"
blue: Color = "#314cb6"
@ -204,6 +204,7 @@ class ThemeColors(HyperglassLevel4):
@validator(*FUNC_COLOR_MAP.keys(), pre=True, always=True)
def validate_colors(cls, value, values, field):
"""Set default functional color mapping.
Arguments:
value {str|None} -- Functional color
values {str} -- Already-validated colors