From 5f3b6693885fa858af553d2e4da0525112553b7b Mon Sep 17 00:00:00 2001 From: thatmattlove Date: Wed, 20 Mar 2024 18:49:51 -0400 Subject: [PATCH] improve docs --- docs/pages/configuration.mdx | 4 +- docs/pages/configuration/config.mdx | 104 ++++++------ docs/pages/configuration/config/logging.mdx | 52 +++--- docs/pages/configuration/config/web-ui.mdx | 122 +++++++------- docs/pages/configuration/devices.mdx | 66 ++++---- docs/pages/configuration/directives.mdx | 120 +++++++------- .../examples/basic-configuration.mdx | 2 +- docs/pages/index.mdx | 9 +- docs/pages/installation.mdx | 152 ++---------------- docs/pages/installation/docker.mdx | 27 ++-- docs/pages/installation/manual.mdx | 27 ++-- docs/pages/installation/reverse-proxy.mdx | 10 +- docs/pages/plugins.mdx | 39 +++-- docs/theme.config.tsx | 1 + 14 files changed, 313 insertions(+), 422 deletions(-) diff --git a/docs/pages/configuration.mdx b/docs/pages/configuration.mdx index 58b95fc..184d02e 100644 --- a/docs/pages/configuration.mdx +++ b/docs/pages/configuration.mdx @@ -42,7 +42,7 @@ When using a Python file for a hyperglass configuration, one of the following me #### Define a Function Named `main` -```python +```python filename="Example: Using a Python function to define configuration parameters" def main(): return { "org_name": "Your Organization Name", @@ -63,7 +63,7 @@ async def main(): #### Define a Dictionary Named `main` -```python +```python filename="Example: Using a Python dictionary to define configuration parameters" main = { "org_name": "Your Organization Name", "web": { diff --git a/docs/pages/configuration/config.mdx b/docs/pages/configuration/config.mdx index 970f6f5..15209c2 100644 --- a/docs/pages/configuration/config.mdx +++ b/docs/pages/configuration/config.mdx @@ -39,10 +39,10 @@ hyperglass relies on [Redis](https://redis.io/) as an in-memory key/value store ```yaml filename="config.yaml" cache: - host: localhost - port: 6379 - database: 1 - password: null + host: localhost + port: 6379 + database: 1 + password: null ``` ## 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: -- `devices` -- `info` -- `queries` -- `query` +- `devices` +- `info` +- `queries` +- `query` ### Schema @@ -94,29 +94,29 @@ The documentation for API endpoints follow a common schema: ```yaml filename="config.yaml" docs: - base_url: https://lg.example.com - enable: true - mode: redoc - path: /api/docs - title: Beloved Hyperglass User Looking Glass API Documentation - description: null - # API Endpoints ↓ - devices: - title: Devices - description: List of all devices/locations with associated identifiers, display names, networks, & VRFs. - summary: Devices List - info: - title: System Information - description: General information about this looking glass. - summary: System Information - queries: - title: Supported Queries - description: List of supported query types. - summary: Query Types - query: - title: Supported Query - description: Request a query response per-location. - summary: Query the Looking Glass + base_url: https://lg.example.com + enable: true + mode: redoc + path: /api/docs + title: Beloved Hyperglass User Looking Glass API Documentation + description: null + # API Endpoints ↓ + devices: + title: Devices + description: List of all devices/locations with associated identifiers, display names, networks, & VRFs. + summary: Devices List + info: + title: System Information + description: General information about this looking glass. + summary: System Information + queries: + title: Supported Queries + description: List of supported query types. + summary: Query Types + query: + title: Supported Query + description: Request a query response per-location. + summary: Query the Looking Glass ``` ## Messages @@ -140,15 +140,15 @@ hyperglass provides as much control over user-facing text/messages as possible. ```yaml filename="config.yaml" message: - general: Something with wrong. + general: Something with wrong. ``` ## 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: -- Juniper Junos -- Arista EOS +- Juniper Junos +- Arista EOS 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. -| 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.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 | | | +| 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.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 | | List of communities to match. | #### Community Filtering Examples ##### Deny Listed Communities by Regex pattern -```yaml filename="config.yaml" +```yaml filename="config.yaml" {5-6} structured: - communities: - mode: deny - 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:2345' # don't show the 65000:2345 community. + communities: + mode: deny + 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:2345" # don't show the 65000:2345 community. ``` ##### Permit only Listed Communities -```yaml filename="config.yaml" +```yaml filename="config.yaml" {5-6} structured: - communities: - mode: permit - items: - - '^65000:.*$' # permit any communities starting with 65000, but no others. - - '1234:1' # permit only the 1234:1 community. + communities: + mode: permit + items: + - "^65000:.*$" # permit any communities starting with 65000, but no others. + - "1234:1" # permit only the 1234:1 community. ``` ### Caveats #### 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 ` or `show ip bgp 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 ` or `show ip bgp 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. diff --git a/docs/pages/configuration/config/logging.mdx b/docs/pages/configuration/config/logging.mdx index e961a7c..5f1e834 100644 --- a/docs/pages/configuration/config/logging.mdx +++ b/docs/pages/configuration/config/logging.mdx @@ -17,11 +17,11 @@ Console, file, HTTP, and/or syslog logging configuration. ##### Syslog Example -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy logging: - syslog: - host: log.example.com - port: 514 + syslog: + host: log.example.com + port: 514 ``` ### HTTP Logging @@ -52,39 +52,39 @@ Authentication is supported using HTTP basic authentication or an API key. ##### Generic -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy logging: - http: - provider: generic - host: https://httpbin.org - headers: - x-special-header: super special header value - params: - source: hyperglass - verify_ssl: true - timeout: 5 - authentication: - mode: basic - username: your username - password: super secret password + http: + provider: generic + host: https://httpbin.org + headers: + x-special-header: super special header value + params: + source: hyperglass + verify_ssl: true + timeout: 5 + authentication: + mode: basic + username: your username + 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. ##### Microsoft Teams Webhook -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy logging: - http: - provider: msteams - host: + http: + provider: msteams + host: ``` ##### Slack -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy logging: - http: - provider: slack - host: + http: + provider: slack + host: ``` diff --git a/docs/pages/configuration/config/web-ui.mdx b/docs/pages/configuration/config/web-ui.mdx index 7fa28ce..2fa4c31 100644 --- a/docs/pages/configuration/config/web-ui.mdx +++ b/docs/pages/configuration/config/web-ui.mdx @@ -1,5 +1,5 @@ -import { Callout } from 'nextra-theme-docs'; -import { Color } from '~/components/color'; +import { Callout } from "nextra-theme-docs"; +import { Color } from "~/components/color"; ## Web UI @@ -31,23 +31,23 @@ hyperglass provides extensive customization options for the look and feel of the ##### Example -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy web: - logo: - light: /path/to/light-logo.svg - dark: /path/to/dark-logo.svg - favicon: /path/to/favicon.svg - width: 100% - height: null + logo: + light: /path/to/light-logo.svg + dark: /path/to/dark-logo.svg + favicon: /path/to/favicon.svg + width: 100% + height: null ``` ### 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: -- A data privacy acknowledgement that must be acknowledged prior to proceeding -- Information about your company -- Instructions on how to use hyperglass +- A data privacy acknowledgement that must be acknowledged prior to proceeding +- Information about your company +- Instructions on how to use hyperglass | Parameter | Type | Default Value | Description | | :---------------------- | :------ | :------------ | :--------------------------------------------------------------------------------------------------- | @@ -59,14 +59,14 @@ The greeting is an optional modal/popup window that will present itself to users ##### Example -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy web: - greeting: - enable: true - file: /path/to/your/file.md - title: Welcome - button: Continue - required: false + greeting: + enable: true + file: /path/to/your/file.md + title: Welcome + button: Continue + required: false ``` ### OpenGraph @@ -91,15 +91,15 @@ Each value you wish to be highlighted is defined with the following schema: ##### Example -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy web: - highlight: - - pattern: '65000:1234' - label: Special snowflake community that does a thing - color: primary - - pattern: '^192\.0\.2\.[0-9]+$' - label: Magical IP Address - color: blue + highlight: + - pattern: "65000:1234" + label: Special snowflake community that does a thing + color: primary + - pattern: '^192\.0\.2\.[0-9]+$' + label: Magical IP Address + color: blue ``` ### Menus @@ -115,7 +115,7 @@ hyperglass can show completely-customizable menus in the footer. Each menu can b ##### Example -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy web: menus: - title: Terms & Conditions @@ -144,19 +144,19 @@ hyperglass can show customizable links to anything you think your users might fi ##### Example -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy web: - links: - - title: PeeringDB - url: https://www.peeringdb.com/65000 - show_icon: true - side: right - order: 1 - - title: Our Website - url: https://example.com - show_icon: false - side: left - order: 0 + links: + - title: PeeringDB + url: https://www.peeringdb.com/65000 + show_icon: true + side: right + order: 1 + - title: Our Website + url: https://example.com + show_icon: false + side: left + order: 0 ``` ### Credit @@ -165,12 +165,12 @@ web: | :-------- | :-----: | :-----: | :--------------------------------------------------------------------------------------- | | `enable` | Boolean | `true` | Enable or disable the display of developer credit & link to hyperglass GitHub repository | - - **Note from the Developer** -
If your organization's policy allows, and you don't mind, I request that you keep `credit` enabled. - Remember: my goal for this project is get more networks to use looking glasses to make all of our lives - easier. Because it's primarily other network operators who 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. + + **Note from the Developer** +
If your organization's policy allows, and you don't mind, I request that you keep `credit` + enabled. Remember: my goal for this project is get more networks to use looking glasses to make all + of our lives easier. Because it's primarily other network operators who 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. ### Text @@ -206,19 +206,21 @@ Most of the text in the hyperglass UI can be overridden to suit your needs. Available title modes are: -- `logo_only` only the logo is displayed, no title or subtitle will 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. +| `title_mode` Value | Action | +| :----------------- | :------------------------------------------------------------------ | +| `logo_only` | Only the logo is displayed, no title or subtitle will 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 ```yaml filename="config.yaml" web: - text: - title: Our Looking Glass - subtitle: Company Name, Inc. - title_mode: text_only + text: + title: Our Looking Glass + subtitle: Company Name, Inc. + title_mode: text_only ``` ### Theme @@ -267,9 +269,9 @@ To override hyperglass's primary color, it's recommended to override its mapped ```yaml filename="config.yaml" web: - theme: - colors: - cyan: '#00ffff' + theme: + colors: + cyan: "#00ffff" ``` #### Fonts @@ -285,7 +287,7 @@ hyperglass's fonts are loaded from [Google Fonts](https://fonts.google.com/). An ```yaml filename="config.yaml" web: - theme: - fonts: - body: Inter + theme: + fonts: + body: Inter ``` diff --git a/docs/pages/configuration/devices.mdx b/docs/pages/configuration/devices.mdx index cefe281..58ba708 100644 --- a/docs/pages/configuration/devices.mdx +++ b/docs/pages/configuration/devices.mdx @@ -59,49 +59,49 @@ Each configured device may have the following parameters: ## Simple -```yaml filename="devices.yaml" +```yaml filename="devices.yaml" copy devices: - - name: New York, NY - address: 192.0.2.1 - platform: cisco_ios - credential: - username: you - password: your password - - name: San Francisco, CA - address: 192.0.2.2 - platform: juniper - credential: - username: you - password: your password + - name: New York, NY + address: 192.0.2.1 + platform: cisco_ios + credential: + username: you + password: your password + - name: San Francisco, CA + address: 192.0.2.2 + platform: juniper + credential: + username: you + password: your password ``` ## With Directives -```yaml filename="devices.yaml" +```yaml filename="devices.yaml" copy {8-9} devices: - - name: New York, NY - address: 192.0.2.1 - platform: cisco_ios - credential: - username: you - password: your password - directives: - - cisco-show-lldp-neighbors + - name: New York, NY + address: 192.0.2.1 + platform: cisco_ios + credential: + username: you + password: your password + directives: + - cisco-show-lldp-neighbors ``` ## With an SSH Proxy -```yaml filename="devices.yaml" +```yaml filename="devices.yaml" copy {8-12} devices: - - name: New York, NY - address: 192.0.2.1 - platform: cisco_ios - credential: - username: you - password: your password - proxy: - address: 192.0.0.123 + - name: New York, NY + address: 192.0.2.1 + platform: cisco_ios credential: - username: your proxy's username - password: your proxy's password + username: you + password: your password + proxy: + address: 192.0.0.123 + credential: + username: your proxy's username + password: your proxy's password ``` diff --git a/docs/pages/configuration/directives.mdx b/docs/pages/configuration/directives.mdx index bb8bc0a..c99135e 100644 --- a/docs/pages/configuration/directives.mdx +++ b/docs/pages/configuration/directives.mdx @@ -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: -- What command to run on the device -- Type of UI field, text input or select -- If the field can accept multiple values -- Help information to show about the directive -- Validation rules +- What command to run on the device +- Type of UI field, text input or select +- If the field can accept multiple values +- Help information to show about the directive +- Validation rules 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 -```yaml filename="directives.yaml" +```yaml filename="directives.yaml" {5-6} /{target} {mask}/ copy your-directive: - name: IP Route - rules: - - condition: 0.0.0.0/0 - ge: 8 - le: 24 - command: 'show ip route {target} {mask}' + name: IP Route + rules: + - condition: 0.0.0.0/0 + ge: 8 + le: 24 + 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 -```yaml +```yaml filename="directives.yaml" {5} copy your directive: - name: BGP Route - rules: - - condition: '192.0.2.0/24' - action: deny - - condition: '0.0.0.0/0' - command: 'show ip bgp {target}' + name: BGP Route + rules: + - condition: "192.0.2.0/24" + action: deny + - condition: "0.0.0.0/0" + 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. ##### Run Multiple Commands -```yaml filename="directives.yaml" +```yaml filename="directives.yaml" /{target}/ {6-7} copy your-directive: - name: BGP Communities - rules: - - condition: '65000:[0-9]+' - commands: - - 'show route table inet.0 community {target} detail' - - 'show route table inet6.0 community {target} detail' + name: BGP Communities + rules: + - condition: "65000:[0-9]+" + commands: + - "show route table inet.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: -``` +```none /65000:1/ show route table inet.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` -```yaml filename="directives.yaml" +```yaml filename="directives.yaml" copy your-directive: - name: DNS Query - rules: - - condition: '^.+\.yourdomain\.com$' + name: DNS Query + rules: + - condition: '^.+\.yourdomain\.com$' ``` ### No Validation -```yaml filename="directives.yaml" +```yaml filename="directives.yaml" /{target}/ copy {4} your-directive: - name: IP Route - rules: - - condition: null - command: show ip route {target} + name: IP Route + rules: + - condition: null + 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 @@ -145,28 +153,28 @@ Each select option uses the following schema: 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: - name: IP Route - rules: - - condition: null - command: show ip route {target} - field: - validation: '[0-9a-f\.\:]+' + name: IP Route + rules: + - condition: null + command: show ip route {target} + field: + validation: '[0-9a-f\.\:]+' ``` Example of a select directive: -```yaml filename="directives.yaml" +```yaml filename="directives.yaml" copy {6-12} your-directive: - name: BGP Community - rules: - - condition: null - command: show ip bgp community {target} - field: - options: - - value: '65001:1' - description: Provider A Routes - - value: '65001:2' - description: Provider B Routes + name: BGP Community + rules: + - condition: null + command: show ip bgp community {target} + field: + options: + - value: "65001:1" + description: Provider A Routes + - value: "65001:2" + description: Provider B Routes ``` diff --git a/docs/pages/configuration/examples/basic-configuration.mdx b/docs/pages/configuration/examples/basic-configuration.mdx index a191376..831735e 100644 --- a/docs/pages/configuration/examples/basic-configuration.mdx +++ b/docs/pages/configuration/examples/basic-configuration.mdx @@ -7,7 +7,7 @@ import { Callout } from "nextra-theme-docs"; To get started, hyperglass only needs to know about your devices. - + **Devices** are your routers, switches, or whatever else you want to call the endpoints hyperglass will query for information. diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index dd9df4c..add56fb 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -3,8 +3,7 @@ title: Introduction description: Get started with hyperglass --- -import Link from "next/link"; -import { Button } from "nextra/components"; +import { Cards, Card } from "nextra/components"; import platforms from "~/platforms.json"; export const Platforms = () => ( @@ -41,6 +40,6 @@ hyperglass was created with the lofty goal of benefiting the internet community - Query multiple devices simultaneously - Browser-based DNS-over-HTTPS resolution of FQDN queries - - - + + + diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index 38814e3..32e0fc5 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -1,145 +1,11 @@ ---- -title: Installation -description: Installing hyperglass ---- +import { Cards, Card } from "nextra/components"; -import { Callout, Tab, Tabs } from 'nextra-theme-docs'; + + + + -## Docker - -**Docker is the recommended method for running hyperglass.** - - -### 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). - - -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). - - -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 `` and `` 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 -``` - - - **Piping to bash** -
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). - - -## 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: - - - - - -```bash -sudo apt install -y python3-dev python3-pip -``` - - - - - -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 -``` - - - - - -### Install hyperglass - -Now that system dependencies are installed, you can install hyperglass. - -```bash -pip3 install hyperglass -``` + + + + diff --git a/docs/pages/installation/docker.mdx b/docs/pages/installation/docker.mdx index b005533..146d2d6 100644 --- a/docs/pages/installation/docker.mdx +++ b/docs/pages/installation/docker.mdx @@ -3,22 +3,25 @@ title: Using Docker description: Installing hyperglass with Docker --- -import { Button } from "nextra/components"; +import { Card, Cards, Steps } from "nextra/components"; import { Callout } from "nextra-theme-docs"; -## Docker - **Docker is the recommended method for running hyperglass.** -### 1. Install Docker + - +### Install Docker -### 2. Download hyperglass + + + + +### Download hyperglass ```shell copy mkdir /etc/hyperglass @@ -38,7 +41,7 @@ docker compose up Navigate to http://localhost:8001 -### 3. Create a `systemd` service +### Create a `systemd` service 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 start hyperglass ``` + + diff --git a/docs/pages/installation/manual.mdx b/docs/pages/installation/manual.mdx index 99358cf..c1c817b 100644 --- a/docs/pages/installation/manual.mdx +++ b/docs/pages/installation/manual.mdx @@ -3,9 +3,13 @@ title: Manual Installation description: Installing hyperglass manually --- -import { Callout } from 'nextra-theme-docs'; +import { Steps } from "nextra/components"; +import { Callout } from "nextra-theme-docs"; + + + +### Install Dependencies -## Install 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/) @@ -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) 4. [Redis 7.2 or later](https://redis.io/download/) - -Make sure the Redis server is started. - +Make sure the Redis server is started. -## Install hyperglass +### Install hyperglass 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 ``` -## Create app directory +### Create app directory -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). ```shell copy 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. @@ -44,7 +47,7 @@ curl -o /etc/hyperglass/devices.yaml https://github.com/thatmattlove/hyperglass/ hyperglass start ``` -## Create a `systemd` service +### Create a `systemd` service ```shell copy 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 ``` -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. + diff --git a/docs/pages/installation/reverse-proxy.mdx b/docs/pages/installation/reverse-proxy.mdx index 48fe173..08cda66 100644 --- a/docs/pages/installation/reverse-proxy.mdx +++ b/docs/pages/installation/reverse-proxy.mdx @@ -3,18 +3,16 @@ title: Reverse Proxy 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"; [Caddy](https://caddyserver.com) is recommended, but any reverse proxy ([NGINX](https://www.nginx.com), [Apache2](https://httpd.apache.org)) will work. ## Caddy - + + + ```shell copy cp /opt/hyperglass/.samples/Caddyfile /etc/caddy/Caddyfile diff --git a/docs/pages/plugins.mdx b/docs/pages/plugins.mdx index bfbe6b1..cdf7ea2 100644 --- a/docs/pages/plugins.mdx +++ b/docs/pages/plugins.mdx @@ -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: -- **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. +- [**Input Plugins**](#input-plugins): Apply custom validation logic to or transform user input before the query is sent to a device. +- [**Output Plugins**](#output-plugins): Interact with the output from a device before it's displayed to the user. 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: -```json +```json filename="Example Query" { - "query_target": "192.0.2.0/24", - "query_location": "your_location", - "query_type": "ip_route_directive" + "query_target": "192.0.2.0/24", + "query_location": "your_location", + "query_type": "ip_route_directive" } ``` @@ -39,16 +46,16 @@ class TransformCIDR(InputPlugin): ```yaml filename="directives.yaml" ip_route_directive: - name: IP Route - plugins: - - '/path/to/your/transform_plugin.py' - rules: - - condition: '0.0.0.0/0' - action: permit - command: 'show ip route {target}' - - condition: '::/0' - action: permit - command: 'show ipv6 route {target}' + name: IP Route + plugins: + - "/path/to/your/transform_plugin.py" + rules: + - condition: "0.0.0.0/0" + action: permit + command: "show ip route {target}" + - condition: "::/0" + action: permit + command: "show ipv6 route {target}" ``` When the query is received, the query target is transformed, resulting in this being sent to the device: diff --git a/docs/theme.config.tsx b/docs/theme.config.tsx index 20c9890..ff4210c 100644 --- a/docs/theme.config.tsx +++ b/docs/theme.config.tsx @@ -114,6 +114,7 @@ const config: DocsThemeConfig = { }, feedback: { content: null }, footer: { text: `© ${new Date().getFullYear()} hyperglass` }, + editLink: { component: null }, chat: { link: "https://netdev.chat/", icon: (