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

improve docs

Browse source
This commit is contained in:
thatmattlove 2024-03-20 18:49:51 -04:00
parent cea421c939
commit 5f3b669388
14 changed files with 313 additions and 422 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/pages/configuration.mdx
View file

@ -42,7 +42,7 @@ When using a Python file for a hyperglass configuration, one of the following me
#### Define a Function Named `main` #### Define a Function Named `main`
```python ```python filename="Example: Using a Python function to define configuration parameters"
def main(): def main():
return { return {
"org_name": "Your Organization Name", "org_name": "Your Organization Name",
@ -63,7 +63,7 @@ async def main():
#### Define a Dictionary Named `main` #### Define a Dictionary Named `main`
```python ```python filename="Example: Using a Python dictionary to define configuration parameters"
main = { main = {
"org_name": "Your Organization Name", "org_name": "Your Organization Name",
"web": { "web": {

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

@ -39,10 +39,10 @@ hyperglass relies on [Redis](https://redis.io/) as an in-memory key/value store
```yaml filename="config.yaml" ```yaml filename="config.yaml"
cache: cache:
host: localhost host: localhost
port: 6379 port: 6379
database: 1 database: 1
password: null password: null
``` ```
## Docs ## Docs
@ -60,10 +60,10 @@ Behind the scenes, hyperglass uses [FastAPI](https://fastapi.tiangolo.com/), whi
The documentation for API endpoints follow a common schema: The documentation for API endpoints follow a common schema:
- `devices` - `devices`
- `info` - `info`
- `queries` - `queries`
- `query` - `query`
### Schema ### Schema
@ -94,29 +94,29 @@ The documentation for API endpoints follow a common schema:
```yaml filename="config.yaml" ```yaml filename="config.yaml"
docs: docs:
base_url: https://lg.example.com base_url: https://lg.example.com
enable: true enable: true
mode: redoc mode: redoc
path: /api/docs path: /api/docs
title: Beloved Hyperglass User Looking Glass API Documentation title: Beloved Hyperglass User Looking Glass API Documentation
description: null description: null
# API Endpoints ↓ # API Endpoints ↓
devices: devices:
title: Devices title: Devices
description: List of all devices/locations with associated identifiers, display names, networks, & VRFs. description: List of all devices/locations with associated identifiers, display names, networks, & VRFs.
summary: Devices List summary: Devices List
info: info:
title: System Information title: System Information
description: General information about this looking glass. description: General information about this looking glass.
summary: System Information summary: System Information
queries: queries:
title: Supported Queries title: Supported Queries
description: List of supported query types. description: List of supported query types.
summary: Query Types summary: Query Types
query: query:
title: Supported Query title: Supported Query
description: Request a query response per-location. description: Request a query response per-location.
summary: Query the Looking Glass summary: Query the Looking Glass
``` ```
## Messages ## Messages
@ -140,15 +140,15 @@ hyperglass provides as much control over user-facing text/messages as possible.
```yaml filename="config.yaml" ```yaml filename="config.yaml"
message: message:
general: Something with wrong. general: Something with wrong.
``` ```
## Structured ## Structured
Devices that support responding to a query with structured or easily parsable data can have their response data placed into an easier to read table (or JSON, when using the REST API). Currently, the following platforms have structured data supported in hyperglass: Devices that support responding to a query with structured or easily parsable data can have their response data placed into an easier to read table (or JSON, when using the REST API). Currently, the following platforms have structured data supported in hyperglass:
- Juniper Junos - Juniper Junos
- Arista EOS - Arista EOS
When structured output is available, hyperglass checks the RPKI state of each BGP prefix returned using one of two methods: When structured output is available, hyperglass checks the RPKI state of each BGP prefix returned using one of two methods:
@ -157,38 +157,38 @@ When structured output is available, hyperglass checks the RPKI state of each BG
Additionally, hyperglass provides the ability to control which BGP communities are shown to the end user. Additionally, hyperglass provides the ability to control which BGP communities are shown to the end user.
| Parameter | Type | Default Value | Description | | Parameter | Type | Default Value | Description |
| :---------------------------- | :-------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------- | | :----------------------------- | :-------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------- |
| `structured.rpki` | String | router | Use `router` to use the router's view of the RPKI state (1 above), or `external` to use Cloudflare's view (2 above). | | `structured.rpki` | String | router | Use `router` to use the router's view of the RPKI state (1 above), or `external` to use Cloudflare's view (2 above). |
| `structured.communities.mode` | String | deny | Use `deny` to deny any communities listed in `structured.communities.items`, or `permit` to _only_ permit communities listed. | | `structured.communities.mode` | String | deny | Use `deny` to deny any communities listed in `structured.communities.items`, or `permit` to _only_ permit communities listed. |
| `structured.communities.items | List of Strings | | | | `structured.communities.items` | List of Strings | | List of communities to match. |
#### Community Filtering Examples #### Community Filtering Examples
##### Deny Listed Communities by Regex pattern ##### Deny Listed Communities by Regex pattern
```yaml filename="config.yaml" ```yaml filename="config.yaml" {5-6}
structured: structured:
communities: communities:
mode: deny mode: deny
items: items:
- '^65000:1\d+$' # don't show any communities starting with 65000:1. 65000:1234 would be denied, but 65000:4321 would be permitted. - '^65000:1\d+$' # don't show any communities starting with 65000:1. 65000:1234 would be denied, but 65000:4321 would be permitted.
- '65000:2345' # don't show the 65000:2345 community. - "65000:2345" # don't show the 65000:2345 community.
``` ```
##### Permit only Listed Communities ##### Permit only Listed Communities
```yaml filename="config.yaml" ```yaml filename="config.yaml" {5-6}
structured: structured:
communities: communities:
mode: permit mode: permit
items: items:
- '^65000:.*$' # permit any communities starting with 65000, but no others. - "^65000:.*$" # permit any communities starting with 65000, but no others.
- '1234:1' # permit only the 1234:1 community. - "1234:1" # permit only the 1234:1 community.
``` ```
### Caveats ### Caveats
#### Arista EOS #### Arista EOS
For whatever reason, Arista EOS does not supply certain details about routes in its JSON output when running commands `show ip bgp regex <pattern>` or `show ip bgp community <community>`. Specifically, the the route's timestamp and any attached communities are not supplied. When these commands are used with Arista EOS, hyperglass sets the timestamp to the current time, and the community to an empty list. For whatever reason, the tested version of Arista EOS does not supply certain details about routes in its JSON output when running commands `show ip bgp regex <pattern>` or `show ip bgp community <community>`. Specifically, the the route's timestamp and any attached communities are not supplied. When these commands are used with Arista EOS, hyperglass sets the timestamp to the current time, and the community to an empty list.

52
docs/pages/configuration/config/logging.mdx
View file

@ -17,11 +17,11 @@ Console, file, HTTP, and/or syslog logging configuration.
##### Syslog Example ##### Syslog Example
```yaml filename="config.yaml" ```yaml filename="config.yaml" copy
logging: logging:
syslog: syslog:
host: log.example.com host: log.example.com
port: 514 port: 514
``` ```
### HTTP Logging ### HTTP Logging
@ -52,39 +52,39 @@ Authentication is supported using HTTP basic authentication or an API key.
##### Generic ##### Generic
```yaml filename="config.yaml" ```yaml filename="config.yaml" copy
logging: logging:
http: http:
provider: generic provider: generic
host: https://httpbin.org host: https://httpbin.org
headers: headers:
x-special-header: super special header value x-special-header: super special header value
params: params:
source: hyperglass source: hyperglass
verify_ssl: true verify_ssl: true
timeout: 5 timeout: 5
authentication: authentication:
mode: basic mode: basic
username: your username username: your username
password: super secret password password: super secret password
``` ```
In the above example, hyperglass will send a `POST` request to `https://httpbin.org?source=hyperglass` with Basic Authentication headers set. In the above example, hyperglass will send a `POST` request to `https://httpbin.org?source=hyperglass` with Basic Authentication headers set.
##### Microsoft Teams Webhook ##### Microsoft Teams Webhook
```yaml filename="config.yaml" ```yaml filename="config.yaml" copy
logging: logging:
http: http:
provider: msteams provider: msteams
host: <MS Teams webhook URL> host: <MS Teams webhook URL>
``` ```
##### Slack ##### Slack
```yaml filename="config.yaml" ```yaml filename="config.yaml" copy
logging: logging:
http: http:
provider: slack provider: slack
host: <Slack webhook URL> host: <Slack webhook URL>
``` ```

122
docs/pages/configuration/config/web-ui.mdx
View file

@ -1,5 +1,5 @@
import { Callout } from 'nextra-theme-docs'; import { Callout } from "nextra-theme-docs";
import { Color } from '~/components/color'; import { Color } from "~/components/color";
## Web UI ## Web UI
@ -31,23 +31,23 @@ hyperglass provides extensive customization options for the look and feel of the
##### Example ##### Example
```yaml filename="config.yaml" ```yaml filename="config.yaml" copy
web: web:
logo: logo:
light: /path/to/light-logo.svg light: /path/to/light-logo.svg
dark: /path/to/dark-logo.svg dark: /path/to/dark-logo.svg
favicon: /path/to/favicon.svg favicon: /path/to/favicon.svg
width: 100% width: 100%
height: null height: null
``` ```
### Greeting ### Greeting
The greeting is an optional modal/popup window that will present itself to users in the Web UI. It can be used for anything you want; for example: The greeting is an optional modal/popup window that will present itself to users in the Web UI. It can be used for anything you want; for example:
- A data privacy acknowledgement that must be acknowledged prior to proceeding - A data privacy acknowledgement that must be acknowledged prior to proceeding
- Information about your company - Information about your company
- Instructions on how to use hyperglass - Instructions on how to use hyperglass
| Parameter | Type | Default Value | Description | | Parameter | Type | Default Value | Description |
| :---------------------- | :------ | :------------ | :--------------------------------------------------------------------------------------------------- | | :---------------------- | :------ | :------------ | :--------------------------------------------------------------------------------------------------- |
@ -59,14 +59,14 @@ The greeting is an optional modal/popup window that will present itself to users
##### Example ##### Example
```yaml filename="config.yaml" ```yaml filename="config.yaml" copy
web: web:
greeting: greeting:
enable: true enable: true
file: /path/to/your/file.md file: /path/to/your/file.md
title: Welcome title: Welcome
button: Continue button: Continue
required: false required: false
``` ```
### OpenGraph ### OpenGraph
@ -91,15 +91,15 @@ Each value you wish to be highlighted is defined with the following schema:
##### Example ##### Example
```yaml filename="config.yaml" ```yaml filename="config.yaml" copy
web: web:
highlight: highlight:
- pattern: '65000:1234' - pattern: "65000:1234"
label: Special snowflake community that does a thing label: Special snowflake community that does a thing
color: primary color: primary
- pattern: '^192\.0\.2\.[0-9]+$' - pattern: '^192\.0\.2\.[0-9]+$'
label: Magical IP Address label: Magical IP Address
color: blue color: blue
``` ```
### Menus ### Menus
@ -115,7 +115,7 @@ hyperglass can show completely-customizable menus in the footer. Each menu can b
##### Example ##### Example
```yaml filename="config.yaml" ```yaml filename="config.yaml" copy
web: web:
menus: menus:
- title: Terms & Conditions - title: Terms & Conditions
@ -144,19 +144,19 @@ hyperglass can show customizable links to anything you think your users might fi
##### Example ##### Example
```yaml filename="config.yaml" ```yaml filename="config.yaml" copy
web: web:
links: links:
- title: PeeringDB - title: PeeringDB
url: https://www.peeringdb.com/65000 url: https://www.peeringdb.com/65000
show_icon: true show_icon: true
side: right side: right
order: 1 order: 1
- title: Our Website - title: Our Website
url: https://example.com url: https://example.com
show_icon: false show_icon: false
side: left side: left
order: 0 order: 0
``` ```
### Credit ### Credit
@ -165,12 +165,12 @@ web:
| :-------- | :-----: | :-----: | :--------------------------------------------------------------------------------------- | | :-------- | :-----: | :-----: | :--------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the display of developer credit & link to hyperglass GitHub repository | | `enable` | Boolean | `true` | Enable or disable the display of developer credit & link to hyperglass GitHub repository |
<Callout> <Callout emoji="❤️" type="info">
**Note from the Developer** **Note from the Developer**
<br /> If your organization's policy allows, and you don't mind, I request that you keep `credit` enabled. <br /> If your organization's policy allows, and you don't mind, I request that you keep `credit`
Remember: my goal for this project is get more networks to use looking glasses to make all of our lives enabled. Remember: my goal for this project is get more networks to use looking glasses to make all
easier. Because it's primarily other network operators who will use this tool to begin with, I'd love of our lives easier. Because it's primarily other network operators who will use this tool to begin
for any operators that use your looking glass to know where they can get their own. with, I'd love for any operators that use your looking glass to know where they can get their own.
</Callout> </Callout>
### Text ### Text
@ -206,19 +206,21 @@ Most of the text in the hyperglass UI can be overridden to suit your needs.
Available title modes are: Available title modes are:
- `logo_only` only the logo is displayed, no title or subtitle will be visible. | `title_mode` Value | Action |
- `text_only` only the title and subtitle are displayed, no logo will be visible. | :----------------- | :------------------------------------------------------------------ |
- `logo_subtitle` only the logo and subtitle are displayed, no title will be visible. | `logo_only` | Only the logo is displayed, no title or subtitle will be visible. |
- `all` logo, title, and subtitle will all be visible. | `text_only` | Only the title and subtitle are displayed, no logo will be visible. |
| `logo_subtitle` | Only the logo and subtitle are displayed, no title will be visible. |
| `all` | Logo, title, and subtitle will all be visible. |
##### Example ##### Example
```yaml filename="config.yaml" ```yaml filename="config.yaml"
web: web:
text: text:
title: Our Looking Glass title: Our Looking Glass
subtitle: Company Name, Inc. subtitle: Company Name, Inc.
title_mode: text_only title_mode: text_only
``` ```
### Theme ### Theme
@ -267,9 +269,9 @@ To override hyperglass's primary color, it's recommended to override its mapped
```yaml filename="config.yaml" ```yaml filename="config.yaml"
web: web:
theme: theme:
colors: colors:
cyan: '#00ffff' cyan: "#00ffff"
``` ```
#### Fonts #### Fonts
@ -285,7 +287,7 @@ hyperglass's fonts are loaded from [Google Fonts](https://fonts.google.com/). An
```yaml filename="config.yaml" ```yaml filename="config.yaml"
web: web:
theme: theme:
fonts: fonts:
body: Inter body: Inter
``` ```

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

@ -59,49 +59,49 @@ Each configured device may have the following parameters:
## Simple ## Simple
```yaml filename="devices.yaml" ```yaml filename="devices.yaml" copy
devices: devices:
- name: New York, NY - name: New York, NY
address: 192.0.2.1 address: 192.0.2.1
platform: cisco_ios platform: cisco_ios
credential: credential:
username: you username: you
password: your password password: your password
- name: San Francisco, CA - name: San Francisco, CA
address: 192.0.2.2 address: 192.0.2.2
platform: juniper platform: juniper
credential: credential:
username: you username: you
password: your password password: your password
``` ```
## With Directives ## With Directives
```yaml filename="devices.yaml" ```yaml filename="devices.yaml" copy {8-9}
devices: devices:
- name: New York, NY - name: New York, NY
address: 192.0.2.1 address: 192.0.2.1
platform: cisco_ios platform: cisco_ios
credential: credential:
username: you username: you
password: your password password: your password
directives: directives:
- cisco-show-lldp-neighbors - cisco-show-lldp-neighbors
``` ```
## With an SSH Proxy ## With an SSH Proxy
```yaml filename="devices.yaml" ```yaml filename="devices.yaml" copy {8-12}
devices: devices:
- name: New York, NY - name: New York, NY
address: 192.0.2.1 address: 192.0.2.1
platform: cisco_ios platform: cisco_ios
credential:
username: you
password: your password
proxy:
address: 192.0.0.123
credential: credential:
username: your proxy's username username: you
password: your proxy's password password: your password
proxy:
address: 192.0.0.123
credential:
username: your proxy's username
password: your proxy's password
``` ```

120
docs/pages/configuration/directives.mdx
View file

@ -2,11 +2,11 @@
A **directive** is a defined configuration for a **command** to run on a device. For example, a BGP Route query is a built-in directive. A directive defines: A **directive** is a defined configuration for a **command** to run on a device. For example, a BGP Route query is a built-in directive. A directive defines:
- What command to run on the device - What command to run on the device
- Type of UI field, text input or select - Type of UI field, text input or select
- If the field can accept multiple values - If the field can accept multiple values
- Help information to show about the directive - Help information to show about the directive
- Validation rules - Validation rules
Each directive has the following options: Each directive has the following options:
@ -45,47 +45,51 @@ A rule is a way of saying "if a query target matches the rule's conditions, run
##### Require IPv4 Queries between /8 and /24 ##### Require IPv4 Queries between /8 and /24
```yaml filename="directives.yaml" ```yaml filename="directives.yaml" {5-6} /{target} {mask}/ copy
your-directive: your-directive:
name: IP Route name: IP Route
rules: rules:
- condition: 0.0.0.0/0 - condition: 0.0.0.0/0
ge: 8 ge: 8
le: 24 le: 24
command: 'show ip route {target} {mask}' command: "show ip route {target} {mask}"
``` ```
Given a query target of 198.18.0.0/15, the command run on the device would be `show ip route 198.18.0.0 255.254.0.0` Given a query target of 198.18.0.0/15, the command run on the device would be:
```none /198.18.0.0 255.254.0.0/
show ip route 198.18.0.0 255.254.0.0
```
##### Deny a Specific Prefix ##### Deny a Specific Prefix
```yaml ```yaml filename="directives.yaml" {5} copy
your directive: your directive:
name: BGP Route name: BGP Route
rules: rules:
- condition: '192.0.2.0/24' - condition: "192.0.2.0/24"
action: deny action: deny
- condition: '0.0.0.0/0' - condition: "0.0.0.0/0"
command: 'show ip bgp {target}' command: "show ip bgp {target}"
``` ```
In this example, a query of any IP address or prefix contained within 192.0.2.0/24 will result in an error. In this example, a query of any IP address or prefix contained within 192.0.2.0/24 will result in an error.
##### Run Multiple Commands ##### Run Multiple Commands
```yaml filename="directives.yaml" ```yaml filename="directives.yaml" /{target}/ {6-7} copy
your-directive: your-directive:
name: BGP Communities name: BGP Communities
rules: rules:
- condition: '65000:[0-9]+' - condition: "65000:[0-9]+"
commands: commands:
- 'show route table inet.0 community {target} detail' - "show route table inet.0 community {target} detail"
- 'show route table inet6.0 community {target} detail' - "show route table inet6.0 community {target} detail"
``` ```
In this example, a query of `65000:1` would result in the following commands being sent to the device: In this example, a query of `65000:1` would result in the following commands being sent to the device:
``` ```none /65000:1/
show route table inet.0 community 65000:1 detail show route table inet.0 community 65000:1 detail
show route table inet6.0 community 65000:1 detail show route table inet6.0 community 65000:1 detail
``` ```
@ -96,24 +100,28 @@ The output for both commands will be shown as the query result.
To validate input by regex pattern, just specify a regex pattern as the `condition` To validate input by regex pattern, just specify a regex pattern as the `condition`
```yaml filename="directives.yaml" ```yaml filename="directives.yaml" copy
your-directive: your-directive:
name: DNS Query name: DNS Query
rules: rules:
- condition: '^.+\.yourdomain\.com$' - condition: '^.+\.yourdomain\.com$'
``` ```
### No Validation ### No Validation
```yaml filename="directives.yaml" ```yaml filename="directives.yaml" /{target}/ copy {4}
your-directive: your-directive:
name: IP Route name: IP Route
rules: rules:
- condition: null - condition: null
command: show ip route {target} command: show ip route {target}
``` ```
In this example, any query would pass, regardless of query input. For instance, if a user selected this directive/query type and queried 'your mom', the real command sent to the device will be `show ip route your mom`. In this example, any query would pass, regardless of query input. For instance, if a user selected this directive/query type and queried `your mom`, the real command sent to the device will be:
```none /your mom/
show ip route your mom
```
## Fields ## Fields
@ -145,28 +153,28 @@ Each select option uses the following schema:
Example of a text directive expecting a string value matching a regex pattern: Example of a text directive expecting a string value matching a regex pattern:
```yaml filename="directives.yaml" ```yaml filename="directives.yaml" copy {6-7}
your-directive: your-directive:
name: IP Route name: IP Route
rules: rules:
- condition: null - condition: null
command: show ip route {target} command: show ip route {target}
field: field:
validation: '[0-9a-f\.\:]+' validation: '[0-9a-f\.\:]+'
``` ```
Example of a select directive: Example of a select directive:
```yaml filename="directives.yaml" ```yaml filename="directives.yaml" copy {6-12}
your-directive: your-directive:
name: BGP Community name: BGP Community
rules: rules:
- condition: null - condition: null
command: show ip bgp community {target} command: show ip bgp community {target}
field: field:
options: options:
- value: '65001:1' - value: "65001:1"
description: Provider A Routes description: Provider A Routes
- value: '65001:2' - value: "65001:2"
description: Provider B Routes description: Provider B Routes
``` ```

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

@ -7,7 +7,7 @@ import { Callout } from "nextra-theme-docs";
To get started, hyperglass only needs to know about your devices. To get started, hyperglass only needs to know about your devices.
<Callout> <Callout type="info">
**Devices** are your routers, switches, or whatever else you want to call the endpoints **Devices** are your routers, switches, or whatever else you want to call the endpoints
hyperglass will query for information. hyperglass will query for information.
</Callout> </Callout>

9
docs/pages/index.mdx
View file

@ -3,8 +3,7 @@ title: Introduction
description: Get started with hyperglass description: Get started with hyperglass
--- ---
import Link from "next/link"; import { Cards, Card } from "nextra/components";
import { Button } from "nextra/components";
import platforms from "~/platforms.json"; import platforms from "~/platforms.json";
export const Platforms = () => ( export const Platforms = () => (
@ -41,6 +40,6 @@ hyperglass was created with the lofty goal of benefiting the internet community
- Query multiple devices simultaneously - Query multiple devices simultaneously
- Browser-based DNS-over-HTTPS resolution of FQDN queries - Browser-based DNS-over-HTTPS resolution of FQDN queries
<Link href="/installation"> <Cards>
<Button className="nx-my-2 nx-py-2 nx-px-4">Get Started</Button> <Card title="Get Started" href="installation/docker" arrow />
</Link> </Cards>

152
docs/pages/installation.mdx
View file

@ -1,145 +1,11 @@
--- import { Cards, Card } from "nextra/components";
title: Installation
description: Installing hyperglass
---
import { Callout, Tab, Tabs } from 'nextra-theme-docs'; <Cards>
<Card href="installation/docker" title="Using Docker" />
<Card href="installation/manual" title="Manual Installation" />
</Cards>
## Docker <Cards>
<Callout type="info"> <Card href="installation/environment-variables" title="Environment Variables" />
**Docker is the recommended method for running hyperglass.** <Card href="installation/reverse-proxy" title="Reverse Proxy" />
</Callout> </Cards>
### 1. [Install Docker](https://docs.docker.com/engine/install/)
### 2. Download hyperglass
```shell copy
mkdir /etc/hyperglass
cd /opt
git clone https://github.com/thatmattlove/hyperglass/tree/v2.0.0 --depth=1
```
### Quickstart (optional)
Do this if you just want to see the hyperglass page working with a fake device.
```shell copy
cp /opt/hyperglass/.samples/sample_devices.yaml /etc/hyperglass/devices.yaml
cd /opt/hyperglass
docker compose up
```
Navigate to http://localhost:8001
### 3. Setup Reverse Proxy
[Caddy](https://caddyserver.com) is recommended, but any reverse proxy ([NGINX](https://www.nginx.com), [Apache2](https://httpd.apache.org)) will work.
#### Caddy
[**Install Caddy**](https://caddyserver.com/docs/install)
```shell copy
cp /opt/hyperglass/.samples/Caddyfile /etc/caddy/Caddyfile
```
Change the `lg.example.com` and `person@example.com` values to match your hyperglass FQDN and email address (the email address is for automatic SSL certificate generation via Let's Encrypt).
<Callout type="info">
If you prefer to use other Let's Encrypt validation methods or your own SSL certificate, modify your `/etc/hyperglass/Caddyfile` in accordance with the [Caddy docs](https://caddyserver.com/docs/caddyfile-tutorial).
</Callout>
Restart the Caddy service: `systemctl restart caddy{:shell}`
#### NGINX
```shell copy
cp /opt/hyperglass/.samples/hyperglass.nginx /etc/nginx/sites-available/hyperglass
ln -s /etc/nginx/sites-available/hyperglass /etc/nginx/sites-enabled/hyperglass
```
Change the `lg.example.com` value to match your hyperglass FQDN.
Change the `<path to cert chain>` and `<path to key>` values to match the path to your certificate and private key files.
## Automatic installation
If your system runs on:
- Ubuntu/Debian Linux
- ~~CentOS/Red Had Linux~~
You should be able to proceed with the automatic installation:
```bash
curl https://install.hyperglass.dev | sudo bash
```
<Callout type="warning">
**Piping to bash**
<br /> You should be _very_ worried when someone asks you to do what I just did. Downloading a bash
script from the internet and piping it to `bash` with root privileges is a terrible idea, unless you
fully trust the source. Please don't trust me - go [look at the code](https://github.com/thatmattlove/hyperglass/blob/v1.0.0/install.sh)
and determine for your self if it's safe to execute. If you feel it's not, please proceed with the
manual installation (and [tell me why](https://github.com/thatmattlove/hyperglass/issues), so I can
fix it).
</Callout>
## Manual Installation
### System Dependencies
#### Python
hyperglass is written in Python 3 and requires Python version **3.9** as a minimum dependency.
If you're confident upgrading your system's version of Python won't break your system (many Linux operating systems rely heavily on Python for package management and other system functions), you can install Python 3.9:
<Tabs items={["Debian/Ubuntu", "RHEL/CentOS"]}>
<Tab>
```bash
sudo apt install -y python3-dev python3-pip
```
</Tab>
<Tab>
Documentation for CentOS is still in-progress. However, it's been determined that these dependencies _may_ also be required, depending on the version of CentOS:
```bash
sudo yum install libtiff-devel libjpeg-devel openjpeg2-devel zlib-devel \
freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel \
harfbuzz-devel fribidi-devel libraqm-devel libimagequant-devel \
libxcb-devel ncurses-devel
```
Until further testing with CentOS can be done, you should install the above dependencies _before_ installing Python 3. You may have to uninstall and re-install Python 3 if these dependencies weren't already installed.
You can install python from the CentOS 7 repository:
```bash
sudo yum install python3-devel python3-pip
```
But you can also use the [SCL repository](https://www.softwarecollections.org/en/scls/rhscl/rh-python36/)
```bash
sudo yum install centos-release-scl
sudo yum install rh-python36
```
</Tab>
</Tabs>
### Install hyperglass
Now that system dependencies are installed, you can install hyperglass.
```bash
pip3 install hyperglass
```

27
docs/pages/installation/docker.mdx
View file

@ -3,22 +3,25 @@ title: Using Docker
description: Installing hyperglass with Docker description: Installing hyperglass with Docker
--- ---
import { Button } from "nextra/components"; import { Card, Cards, Steps } from "nextra/components";
import { Callout } from "nextra-theme-docs"; import { Callout } from "nextra-theme-docs";
## Docker
<Callout type="info">**Docker is the recommended method for running hyperglass.**</Callout> <Callout type="info">**Docker is the recommended method for running hyperglass.**</Callout>
### 1. Install Docker <Steps>
<Button className="nx-my-4 nx-py-2 nx-px-4 nx-font-bold"> ### Install Docker
<a target="_blank" href="https://docs.docker.com/engine/install/">
Docker Engine Installation Guide
</a>
</Button>
### 2. Download hyperglass <Cards>
<Card
title="Docker Engine Installation Guide"
href="https://docs.docker.com/engine/install/"
target="_blank"
arrow
/>
</Cards>
### Download hyperglass
```shell copy ```shell copy
mkdir /etc/hyperglass mkdir /etc/hyperglass
@ -38,7 +41,7 @@ docker compose up
Navigate to http://localhost:8001 Navigate to http://localhost:8001
### 3. Create a `systemd` service ### Create a `systemd` service
<Callout type="info"> <Callout type="info">
Before you create and start the hyperglass service, you may want to verify whether or not you Before you create and start the hyperglass service, you may want to verify whether or not you
@ -52,3 +55,5 @@ systemctl daemon-reload
systemctl enable hyperglass systemctl enable hyperglass
systemctl start hyperglass systemctl start hyperglass
``` ```
</Steps>

27
docs/pages/installation/manual.mdx
View file

@ -3,9 +3,13 @@ title: Manual Installation
description: Installing hyperglass manually description: Installing hyperglass manually
--- ---
import { Callout } from 'nextra-theme-docs'; import { Steps } from "nextra/components";
import { Callout } from "nextra-theme-docs";
<Steps>
### Install Dependencies
## Install Dependencies
To install hyperglass manually, you'll need to install the following dependencies: To install hyperglass manually, you'll need to install the following dependencies:
1. [Python 3.9, 3.10, 3.11, or 3.12](https://www.python.org/downloads/) 1. [Python 3.9, 3.10, 3.11, or 3.12](https://www.python.org/downloads/)
@ -13,11 +17,9 @@ To install hyperglass manually, you'll need to install the following dependencie
3. [PNPM 8 or later](https://pnpm.io/installation) 3. [PNPM 8 or later](https://pnpm.io/installation)
4. [Redis 7.2 or later](https://redis.io/download/) 4. [Redis 7.2 or later](https://redis.io/download/)
<Callout type="default"> <Callout type="warning">Make sure the Redis server is started.</Callout>
Make sure the Redis server is started.
</Callout>
## Install hyperglass ### Install hyperglass
Once these dependencies are installed, install hyperglass via PyPI: Once these dependencies are installed, install hyperglass via PyPI:
@ -25,17 +27,18 @@ Once these dependencies are installed, install hyperglass via PyPI:
pip3 install hyperglass pip3 install hyperglass
``` ```
## Create app directory ### Create app directory
<Callout type="info"> <Callout type="info">
If you plan on using a different directory, be sure to set the directory you wish to use in your [environment variables](environment-variables.mdx). If you plan on using a different directory, be sure to set the directory you wish to use in your
[environment variables](environment-variables.mdx).
</Callout> </Callout>
```shell copy ```shell copy
mkdir /etc/hyperglass mkdir /etc/hyperglass
``` ```
## Optional: Quickstart ### Optional: Quickstart
Do this if you just want to see the hyperglass page working with default settings and a fake device. Do this if you just want to see the hyperglass page working with default settings and a fake device.
@ -44,7 +47,7 @@ curl -o /etc/hyperglass/devices.yaml https://github.com/thatmattlove/hyperglass/
hyperglass start hyperglass start
``` ```
## Create a `systemd` service ### Create a `systemd` service
```shell copy ```shell copy
curl -o /etc/hyperglass/hyperglass.service https://github.com/thatmattlove/hyperglass/blob/v2.0.0/.samples/hyperglass-manual.service curl -o /etc/hyperglass/hyperglass.service https://github.com/thatmattlove/hyperglass/blob/v2.0.0/.samples/hyperglass-manual.service
@ -55,6 +58,8 @@ systemctl start hyperglass
``` ```
<Callout type="info"> <Callout type="info">
If you used a different app directory from the default `/etc/hyperglass`, change the `EnvironmentFile` value in the `hyperglass.service` file. If you used a different app directory from the default `/etc/hyperglass`, change the
`EnvironmentFile` value in the `hyperglass.service` file.
</Callout> </Callout>
</Steps>

10
docs/pages/installation/reverse-proxy.mdx
View file

@ -3,18 +3,16 @@ title: Reverse Proxy
description: Setting up a reverse proxy for hyperglass description: Setting up a reverse proxy for hyperglass
--- ---
import { Button } from "nextra/components"; import { Cards, Card } from "nextra/components";
import { Callout } from "nextra-theme-docs"; import { Callout } from "nextra-theme-docs";
[Caddy](https://caddyserver.com) is recommended, but any reverse proxy ([NGINX](https://www.nginx.com), [Apache2](https://httpd.apache.org)) will work. [Caddy](https://caddyserver.com) is recommended, but any reverse proxy ([NGINX](https://www.nginx.com), [Apache2](https://httpd.apache.org)) will work.
## Caddy ## Caddy
<Button className="nx-my-4 nx-py-2 nx-px-4 nx-font-bold"> <Cards>
<a target="_blank" href="https://caddyserver.com/docs/install"> <Card title="Install Caddy" target="_blank" href="https://caddyserver.com/docs/install" arrow />
Install Caddy </Cards>
</a>
</Button>
```shell copy ```shell copy
cp /opt/hyperglass/.samples/Caddyfile /etc/caddy/Caddyfile cp /opt/hyperglass/.samples/Caddyfile /etc/caddy/Caddyfile

39
docs/pages/plugins.mdx
View file

@ -1,7 +1,14 @@
---
title: Plugins
description: hyperglass Plugins
---
import { Cards, Card } from "nextra/components";
Starting in version 2.0, hyperglass supports custom plugins. There are two main types of plugins: Starting in version 2.0, hyperglass supports custom plugins. There are two main types of plugins:
- **Input Plugins**: Apply custom validation logic to or transform user input before the query is sent to a device. - [**Input Plugins**](#input-plugins): Apply custom validation logic to or transform user input before the query is sent to a device.
- **Output Plugins**: Interact with the output from a device before it's displayed to the user. - [**Output Plugins**](#output-plugins): Interact with the output from a device before it's displayed to the user.
Plugins are associated with a directive. Plugins are associated with a directive.
@ -13,11 +20,11 @@ Plugins are associated with a directive.
In this example, the following query is sent to hyperglass: In this example, the following query is sent to hyperglass:
```json ```json filename="Example Query"
{ {
"query_target": "192.0.2.0/24", "query_target": "192.0.2.0/24",
"query_location": "your_location", "query_location": "your_location",
"query_type": "ip_route_directive" "query_type": "ip_route_directive"
} }
``` ```
@ -39,16 +46,16 @@ class TransformCIDR(InputPlugin):
```yaml filename="directives.yaml" ```yaml filename="directives.yaml"
ip_route_directive: ip_route_directive:
name: IP Route name: IP Route
plugins: plugins:
- '/path/to/your/transform_plugin.py' - "/path/to/your/transform_plugin.py"
rules: rules:
- condition: '0.0.0.0/0' - condition: "0.0.0.0/0"
action: permit action: permit
command: 'show ip route {target}' command: "show ip route {target}"
- condition: '::/0' - condition: "::/0"
action: permit action: permit
command: 'show ipv6 route {target}' command: "show ipv6 route {target}"
``` ```
When the query is received, the query target is transformed, resulting in this being sent to the device: When the query is received, the query target is transformed, resulting in this being sent to the device:

1
docs/theme.config.tsx
View file

@ -114,6 +114,7 @@ const config: DocsThemeConfig = {
}, },
feedback: { content: null }, feedback: { content: null },
footer: { text: `© ${new Date().getFullYear()} hyperglass` }, footer: { text: `© ${new Date().getFullYear()} hyperglass` },
editLink: { component: null },
chat: { chat: {
link: "https://netdev.chat/", link: "https://netdev.chat/",
icon: ( icon: (