mirror/checktheroads-hyperglass
1
0
Fork 0
mirror of https://github.com/checktheroads/hyperglass synced 2024-05-11 05:55:08 +00:00
Code Releases Activity

moving docs to separate repo

Browse Source
This commit is contained in:
checktheroads
2019-06-15 14:25:54 -07:00
parent a413a26f34
commit 421cc2a85e
35 changed files with 963 additions and 1478 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/blacklist_error.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 18 KiB

7
docs/caching.md
View File

@@ -1,7 +0,0 @@
Hyperglass supports caching the application's responses for a configurable period of time to reduce the number of lookups passed back to routers for repetitive/common lookups. By default, all application responses (including error messages), are cached for 2 minutes in the local file system.
Hyperglass uses [Flask-Caching](https://github.com/sh4nks/flask-caching), which is able to use a wide variety of cache storage backends (Filesystem, Redis, Memcached, etc.). By default, Hyperglass uses the Filesystem method, and stores the cached data in `hyperglass/hyperglass/.flask_cache`.
The cache list little more than a key value store. Hyperglass uses a stringified combination of router/location name, command used, and query type as a key, and the output as a value. If a lookup matching the exact key is found, the cached value will be returned. If not, a standard lookup is performed (and that data is subsequently cached).
# Insert Video Here

355
docs/configuration/branding.md
View File

@@ -1,355 +0,0 @@
<style>
.bd-color {
border-radius: 1px;
box-shadow: 0 1px 2px 0 rgba(0,0,0,.1), inset 0 0 0 1px rgba(0,0,0,.1);
display: inline-block;
float: left;
height: 16px;
margin-right: 2px;
width: 16px;
}
</style>
From `hyperglass/hyperglass/configuration/configuration.toml` `[branding]` table.
# `[branding]` - Site Parameters
#### site_name
| Type | Default Value |
| ------ | -------------- |
| String | `"hyperglass"` |
HTML `<title>` element that is shown in a browser's title bar.
## `[branding.footer]` - Footer Configuration
#### enable
| Type | Default Value |
| ------- | ------------- |
| Boolean | `true` |
Enables or disables entire footer element.
The footer text itself can be customized by adding a [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) document to `hyperglass/hyperglass/render/templates/info/details/footer.md`. The example file, `footer.md.example`, can be copied to `footer.md` and modified. All Markdown files in this directory are excluded from change control and will not be overwritten when hyperglass is updated.
!!! note "Syntax"
The custom content Markdown files *must* have TOML Front Matter, even if there are no attributes used.
## `[branding.credit]` - Credit Configuration
#### enable
| Type | Default Value |
| ------- | ------------- |
| Boolean | `true` |
Enables or disables text below the footer element, which links to the hyperglass repo:
> Powered by Hyperglass. Source code licensed BSD 3-Clause Clear.
## `[branding.peering_db]` - PeeringDB Configuration
#### enable
| Type | Default Value |
| ------- | ------------- |
| Boolean | `true` |
Enables or disables the PeeringDB link in the upper right corner. If `true`, the [primary_asn](#primary_asn) will be automatically used to create the URL to your ASN's PeeringDB entry.
## `[branding.text]` - Site-Wide Text Customizations
#### title_mode
| Type | Default Value |
| ------ | ------------- |
| String | `"none"` |
Controls the title section on the main page.
- `"none"` Hides Title and Subtitle text, displays logo defined in [logo_path](#logo_path).
- `"both"` Displays both Title and Subtitle text defined in [title](#title) and [subtitle](#subtitle) parameters.
- `"hide_subtitle"` Displays only the Title text defined in the [title](#title) parameter.
#### title
| Type | Default Value |
| ------ | -------------- |
| String | `"hyperglass"` |
#### subtitle
| Type | Default Value |
| ------ | -------------------- |
| String | `"AS" + primary_asn` |
See [primary_asn](#primary_asn) parameter.
#### query_type
| Type | Default Value |
| ------ | -------------------- |
| String | `"Query Type"` |
Placeholder text that appears in the Query Type dropdown.
#### results
| Type | Default Value |
| ------ | -------------------- |
| String | `"Results"` |
Title text used for the results message box which contains the results of the query.
#### location
| Type | Default Value |
| ------ | ---------------------- |
| String | `"Select Location..."` |
Placeholder text that appears in the Location dropdown.
#### query_placeholder
| Type | Default Value |
| ------ | ------------------------------------- |
| String | `"IP, Prefix, Community, or AS Path"` |
Placeholder text that appears in the main search box.
#### bgp_route
| Type | Default Value |
| ------ | ------------- |
| String | `"BGP Route"` |
Dropdown text used for the BGP Route query type.
#### bgp_community
| Type | Default Value |
| ------ | ----------------- |
| String | `"BGP Community"` |
Dropdown text used for the BGP Community query type.
#### bgp_aspath
| Type | Default Value |
| ------ | --------------- |
| String | `"BGP AS Path"` |
Dropdown text used for the BGP AS Path query type.
#### ping
| Type | Default Value |
| ------ | ------------- |
| String | `"Ping"` |
Dropdown text used for the Ping query type.
#### traceroute
| Type | Default Value |
| ------ | -------------- |
| String | `"Traceroute"` |
Dropdown text used for the Traceroute query type.
### `[branding.text.404]` - 404 Error Page Text Customization
The 404 error page will be displayed if a user attempts to visit any non-existent URI, e.g. `http://lg.domain.tld/this_isnt_real`
#### title
| Type | Default Value |
| ------ | ------------- |
| String | `"Error"` |
#### subtitle
| Type | Default Value |
| ------ | ------------------ |
| String | `"Page Not Found"` |
### `[branding.text.500]` - 500 Error Page Text Customization
The 500 error page will be displayed if there is a backend problem or if an exception is raised. If you get this page, you should probably enable debug mode to find out why.
#### title
| Type | Default Value |
| ------ | ------------- |
| String | `"Error"` |
#### subtitle
| Type | Default Value |
| ------ | ------------------------ |
| String | `"Something Went Wrong"` |
## `[branding.logo]` - Logo & Favicon Configuration
#### path
| Type | Default Value |
| ------ | ------------------------------------- |
| String | `"static/images/hyperglass-dark.png"` |
Sets the path to the logo file, which will be displayed if [title_mode](#title_mode) is set to `"logo_only"`. This file can be any browser-compatible format, such as JPEG, PNG, or SVG.
!!! note "Custom Files"
The `hyperglass/hyperglass/static/custom/` directory is excluded from change control, and will not be overwritten when hyperglass is updated. Custom image files should be placed here.
#### width
| Type | Default Value |
| ------ | ------------- |
| String | `"384"` |
Sets the width of the logo defined in the [logo_path](#logo_path) parameter. This is helpful if your logo is a dimension that doesn't quite work with the default width.
#### favicons
| Type | Default Value |
| ------ | ------------------------------------- |
| String | `"static/images/favicon/"` |
Sets the path to the favicons directory (must have a trailing `/`). For full browser and platform comatability, it is recommended to use [RealFaviconGenerator](https://realfavicongenerator.net/) and place all the generated files in `static/custom/images/favicon/` (and update the `favicons` parameter).
## `[branding.color]` - Color Customization
#### background
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#fbfffe"` | <span class="bd-color" style="background-color: #fbfffe;"></span> |
Sets the background color of the main page.
#### button_submit
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#40798c"` | <span class="bd-color" style="background-color: #40798c;"></span> |
Sets color of the submit button.
#### danger
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#ff3860"` | <span class="bd-color" style="background-color: #ff3860;"></span> |
Sets color of the Bulma "danger" class, which is used for some user-facing error, and as the background color for the 404, 500 and Rate Limit error pages.
#### progress_bar
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#40798c"` | <span class="bd-color" style="background-color: #40798c;"></span> |
Sets color of the progress bar that displays while the back-end application processes the request.
### `[branding.color.tag]` - Tag Color Customization
Bulma tags are used to show attributes for the active query being run.
#### type_title
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#330036"` | <span class="bd-color" style="background-color: #330036;"></span> |
Sets color of the title portion of the query type tag which appears at the top of the results box on the right side.
#### type
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#ff5e5b"` | <span class="bd-color" style="background-color: #ff5e5b;"></span> |
Sets color of the type portion of the query type tag which appears at the top of the results box on the right side.
#### location_title
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#330036"` | <span class="bd-color" style="background-color: #330036;"></span> |
Sets color of the title portion of the location tag which appears at the top of the results box on the left side.
#### location
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#40798c"` | <span class="bd-color" style="background-color: #40798c;"></span> |
Sets color of the location name portion of the location tag which appears at the top of the results box on the left side.
## `[branding.font]` - Font Customization
Hyperglass makes use of two font families - a primary family and a monospace family. The primary family is used for all paragraph, title/subtitle, and non-code/preformatted text, and the monospace font is used for any code/preformatted blocks as well as the query results.
The values are passed as a Jinja2 variable to generate `hyperglass/hyperglass/static/sass/hyperglass.scss`, which will be compiled from Sass to CSS.
### `[branding.font.primary]` - Primary Font Customization
#### name
| Type | Default Value |
| ------ | ------------- |
| String | `"Nunito"` |
Sets the web font name for the primary font.
#### url
| Type | Default Value |
| ------ | -------------------------------------------------------------- |
| String | `"https://fonts.googleapis.com/css?family=Nunito:400,600,700"` |
Sets the web font URL for the primary font.
### `[branding.font.mono]` - Monospace Font Customization
#### name
| Type | Default Value |
| ------ | ------------- |
| String | `"Fira Mono"` |
Sets the web font name for the monospace/code/preformatted text font.
#### url
| Type | Default Value |
| ------ | ----------------------------------------------------- |
| String | `"https://fonts.googleapis.com/css?family=Fira+Mono"` |
Sets the web font URL for the monospace/code/preformatted text font.
#### text_cache
| Type | Default Value |
| ------ | ------------------------------------------------------- |
| String | `"Results will be cached for {cache_timeout} minutes."` |
Sets the text at the bottom of the results box that states the cache timeout. `{cache_timeout}` will be formatted with the value of [cache_timeout](/configuration/general/#cache_timeout).
#### text_limiter_title
| Type | Default Value |
| ------ | ----------------- |
| String | `"Limit Reached"` |
Sets the title text for the site-wide rate limit page. Users are redirected to this page when they have accessed the site more than the [specified](/configuration/general/#rate_limit_site) limit.
#### text_limiter_subtitle
| Type | Default Value |
| ------ | ------------------------------------------------------------------------------------- |
| String | `"You have accessed this site more than {rate_limit_site} times in the last minute."` |
Sets the subtitle text for the site-wide rate limit page. Users are redirected to this page when they have accessed the site more than the [specified](/configuration/general/#rate_limit_site) limit. `{rate_limit_site}` will be formatted with the value of [rate_limit_site](/configuration/general/#rate_limit_site).

58
docs/configuration/commands.md
View File

@@ -1,58 +0,0 @@
Commands are defined in `hyperglass/hyperglass/configuration/commands.toml`. A table for each NOS (Network Operating System) contains three nested tables: `dual`, `ipv4`, and `ipv6`.
| Table | Function | Commands |
| --------- | ----------------------------- | ------------------------------- |
| **dual** | Protocol agnostic commands | `bgp_community` `bgp_aspath` |
| **ipv4** | IPv4-specific commands | `bgp_route` `ping` `traceroute` |
| **ipv6** | IPv6-specific commands | `bgp_route` `ping` `traceroute` |
#### Variables
The following variables can be used in the command definitions.
- `{target}` Maps to search box input.
- `{src_addr_ipv4}` Maps to [src_addr_ipv4](configuration/devices.md/#src_addr_ipv4)
- `{src_addr_ipv6}` Maps to [src_addr_ipv6](configuration/devices.md/#src_addr_ipv6)
#### Example
```toml
[[cisco_ios]]
[cisco_ios.dual]
bgp_community = "show bgp all community {target}"
bgp_aspath = 'show bgp all quote-regexp "{target}"'
[cisco_ios.ipv4]
bgp_route = "show bgp ipv4 unicast {target} | exclude pathid:|Epoch"
ping = "ping {target} repeat 5 source {src_addr_ipv4}"
traceroute = "traceroute {target} timeout 1 probe 2 source {src_addr_ipv4}"
[cisco_ios.ipv6]
bgp_route = "show bgp ipv6 unicast {target} | exclude pathid:|Epoch"
ping = "ping ipv6 {target} repeat 5 source {src_addr_ipv6}"
traceroute = "traceroute ipv6 {target} timeout 1 probe 2 source {src_addr_ipv6}"
[[cisco_xr]]
[cisco_xr.dual]
bgp_community = 'show bgp all unicast community {target} | utility egrep -v "\(BGP |Table |Non-stop\)"'
bgp_aspath = 'show bgp all unicast regexp {target} | utility egrep -v "\(BGP |Table |Non-stop\)"'
[cisco_xr.ipv4]
bgp_route = 'show bgp ipv4 unicast {target} | util egrep "\(BGP routing table entry|Path \#|aggregated by|Origin |Community:|validity| from \)"'
ping = "ping ipv4 {target} count 5 source {src_addr_ipv4}"
traceroute = "traceroute ipv4 {target} timeout 1 probe 2 source {src_addr_ipv4}"
[cisco_xr.ipv6]
bgp_route = 'show bgp ipv6 unicast {target} | util egrep "\(BGP routing table entry|Path \#|aggregated by|Origin |Community:|validity| from \)"'
ping = "ping ipv6 {target} count 5 source {src_addr_ipv6}"
traceroute = "traceroute ipv6 {target} timeout 1 probe 2 source {src_addr_ipv6}"
[[juniper]]
[juniper.dual]
bgp_community = "show route protocol bgp community {target}"
bgp_aspath = "show route protocol bgp aspath-regex {target}"
[juniper.ipv4]
bgp_route = "show route protocol bgp table inet.0 {target} detail"
ping = "ping inet {target} count 5 source {src_addr_ipv4}"
traceroute = "traceroute inet {target} wait 1 source {src_addr_ipv4}"
[juniper.ipv6]
bgp_route = "show route protocol bgp table inet6.0 {target} detail"
ping = "ping inet6 {target} count 5 source {src_addr_ipv6}"
traceroute = "traceroute inet6 {target} wait 1 source {src_addr_ipv6}"
```

79
docs/configuration/configuration.md
View File

@@ -1,79 +0,0 @@
# Configuration
Hyperglass configuration files are stored in `hyperglass/hyperglass/configuration/`, in [TOML](https://github.com/toml-lang/toml) format.
```console
hyperglass/configuration/
├── commands.toml
├── configuration.toml
└── devices.toml
```
## Site Parameters
Global hyperglass parameters
#### debug
| Type | Default Value |
| ------- | ------------- |
| Boolean | `false` |
Enables hyperglass & Flask debugging.
!!! warning "Logging"
Enabling debug mode will produce a large amount of log output, as every configuration parameter and backend transaction is logged to stdout.
#### requires_ipv6_cidr
| Type | Default Value |
| ----- | ----------------------------- |
| Array | `["cisco_ios", "cisco_nxos"]` |
Some platforms (namely Cisco IOS) are unable to perform a BGP lookup by IPv6 host address (e.g. 2001:db8::1), but must perform the lookup by prefix (e.g. 2001:db8::/48). `requires_ipv6_cidr` is a list (TOML array) of network operating systems that require this (in Netmiko format).
If a user attempts to query a device requiring IPv6 lookups in CIDR format with an IPv6 host address, the following message will be displayed:
<img src="/requires_ipv6_cidr.png" style="width: 70%"></img>
#### blacklist
| Type | Default Value |
| ----- | ------------- |
| Array | See Example |
The blacklist is a simple TOML array (list) of host IPs or prefixes that you do not want end users to be able to query. For example, if you have one or more hosts/subnets you wish to prevent users from looking up (or any contained host or prefix), add them to the list.
##### Example
```toml
blacklist = [
"198.18.0.0/15",
"2001:db8::/32",
"10.0.0.0/8",
"192.168.0.0/16",
"172.16.0.0/12"
]
```
When users attempt to query a matching host/prefix, they will receive the following error message by default:
<img src="/blacklist_error.png" style="width: 70%"></img>
## `[general]` - Site Parameters
#### primary_asn
| Type | Default Value |
| ------ | ------------- |
| String | `"65000"` |
Your network's _primary_ ASN. Number only, e.g. `65000`, **not** `AS65000`.
#### google_analytics
| Type | Default Value |
| ------ | ------------- |
| String | `""` |
Google Analytics ID number. For more information on how to set up Google Analytics, see [here](https://support.google.com/analytics/answer/1008080?hl=en).

103
docs/configuration/devices.md
View File

@@ -1,103 +0,0 @@
`devices.toml` is structured as three separate hash table/dictionaries for devices, credentials, and proxies. All values are strings.
# Routers
| Parameter | Function |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **address** | IP address hyperglass will use to connect to the device. |
| **asn** | ASN this device is a member of. |
| **src_addr_ipv4** | Source IPv4 address used for ping and traceroute queries. |
| **src_addr_ipv6** | Source IPv6 address used for ping and traceroute queries. |
| **credential** | Name of credential (username & password) used to authenticate with the device. Credentials are defined as individual tables. See [here](/configuration/authentication.md) for more information on authentication. |
| **location** | Name of location/POP where this device resides. |
| **name** | Hostname of the individual device. |
| **display_name** | Device name that will be shown to the end user on the main hyperglass page. |
| **port** | TCP port for SSH/HTTP connection to device. |
| **type** | Device type/vendor name as recognized by [Netmiko](https://github.com/ktbyers/netmiko). See [supported device types](extras/supported-device-types) for a full list. If using FRRouting and the [hyperglass-frr](https://github.com/checktheroads/hyperglass-frr) API, specify `frr`. |
| **proxy** | Name of SSH proxy/jumpbox, if any, used for connecting to the device. See [here](/configuration/proxy.md) for more information on proxying. If not using a proxy, specify an empty string, i.e. `""`. |
#### Example
```toml
[router.'pop1']
address = "192.0.2.1"
asn = "65000"
src_addr_ipv4 = "192.0.2.251"
src_addr_ipv6 = "2001:db8::1"
credential = "default"
location = "pop1"
name = "router1.pop1"
display_name = "Washington, DC"
port = "22"
type = "cisco_ios"
proxy = "jumpbox1"
[router.'pop2']
address = "192.0.2.2"
asn = "65000"
src_addr_ipv4 = "192.0.2.252"
src_addr_ipv6 = "2001:db8::2"
credential = "frr_api_pop2"
location = "pop2"
name = "router1.pop2"
display_name = "Portland, OR"
port = "8080"
type = "frr"
proxy = ""
```
# Credentials
The credential table stores the username and password for a device. SSH Key authentication is not yet supported. If using FRRouting and the [hyperglass-frr](https://github.com/checktheroads/hyperglass-frr) API, the username can be any arbitrary value (it is not used), and the password is the PBKDF2 SHA256 *hashed* API key (**not** the API key itself).
#### Example
```toml
[credential.'default']
username = "hyperglass"
password = "secret_password"
[credential.'frr_api_pop2']
username = "doesntmatter"
password = "$pbkdf2-sha256$29000$bI0xJqQUQoixtjZGSAnhvA$FM0oUc.Y3kuvl9ilQmMuULTD1MjzD64Ax9rFNUgAl.c"
```
!!! warning "Security Warning"
These values are stored in plain text, so make sure the accounts are restricted. Instructions for creating restricted accounts on common platforms can be found [here](extras/securing-router-access).
# Proxies
The proxy table stores the connection parameters for an SSH proxy.
When a proxy server is defined in the `[router]` table, the defined proxy name is matched to a configured proxy as shown above. When the connection to the device is initiated, the hyperglass server will first initiate an SSH connection to the proxy, and then initiate a second connection to the target device (router) *from* the proxy server. This can be helpful if you want to secure access to your routers.
!!! warning "Security Warning"
These values are stored in plain text, so make sure the accounts are restricted.
| Parameter | Function |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **address** | IP address hyperglass will use to connect to the device. |
| **username** | Username for SSH authentication to the proxy server/jumpbox. SSH Key authentication is not yet supported. |
| **password** | Plain text password for SSH authentication to the proxy server/jumpbox. |
| **type** | Device type/vendor name as recognized by [Netmiko](https://github.com/ktbyers/netmiko). See [supported device types](extras/supported-device-types) for a full list. |
| **ssh_command** | Command used to initiate an SSH connection _from_ the proxy server to the target device. `{username}` will map to the target device (router) username as defined in its associated credential mapping. `{host}` will map to the target device IP address as defined in `devices.toml`. |
#### Example
```toml
[proxy.'jumpbox1']
address = "10.1.1.1"
username = "hyperglass"
password = "secret_password"
type = "linux_ssh"
ssh_command = "ssh -l {username} {host}"
[proxy.'jumpbox2']
address = "10.1.1.2"
username = "hyperglass"
password = "secret_password"
type = "linux_ssh"
ssh_command = "ssh -l {username} {host}"
```
!!! note "Compatibility"
Hyperglass has only been tested with `linux_ssh` as of this writing.

256
docs/configuration/features.md
View File

@@ -1,256 +0,0 @@
From `hyperglass/hyperglass/configuration/configuration.toml` `[features]`table.
`[features]`
## Rate Limiting
##### `[features.rate_limit.query]`
#### Query
Configuration paramters for rate limiting the number of queries per visitor. For information on how this works, please see the [rate limiting documentation](/ratelimiting/#query).
##### `rate`
| Type | Default Value |
| ------- | ------------- |
| Integer | `5` |
Sets the number of queries **per minute** allowed from the remote IP address of the request.
##### `period`
| Type | Default Value |
| -------| ------------- |
| String | `"minute"` |
Sets the time period to which `rate` applies.
##### `message`
| Type | Default Value |
| ------ | ------------------------------------------------------------------------------------- |
| String | `"Query limit of {rate} per minute reached. Please wait one {period} and try again."` |
Message presented to the user when the [query limit](#rate_limit_query) is reached. `{rate_limit_query}` will be formatted as the [`rate_limit_query`](#rate_limit_query) parameter.
#### Site
`[features.rate_limit.site]`
Configuration parameters for rate limiting the number of site visits per visitor. For information on how this works, please see the [rate limiting documentation](/ratelimiting/#site).
##### `rate`
| Type | Default Value |
| ------- | ------------- |
| Integer | `60` |
Sets the number of site visits allowed from the remote IP address of the request during the configured [period](#period) below.
##### `period`
| Type | Default Value |
| -------| ------------- |
| String | `"minute"` |
Sets the time period to which `rate` applies.
##### `title`
| Type | Default Value |
| ------ | ----------------- |
| String | `"Limit Reached"` |
Title text on Rate Limit error page.
##### `subtitle`
| Type | Default Value |
| ------ | ---------------------------------------------------------------------------- |
| String | `"You have accessed this site more than {rate} times in the last {period}."` |
Subtitle text on Rate Limit error page.
## Caching
`[features.cache]`
For information on how this works, please see the [caching documentation](/caching).
##### `timeout`
| Type | Default Value |
| ------- | ------------- |
| Integer | `120` |
Sets the number of **seconds** to cache the back-end response.
##### `directory`
| Type | Default Value |
| ------ | -------------------------------------- |
| String | `"hyperglass/hyperglass/.flask_cache"` |
Sets the directory where the back-end responses are cached. `hyperglass/hyperglass/.flask_cache` is excluded from change control.
!!! note "Permissions"
The user hyperglass runs as must have permissions to this directory.
##### `show_text`
| Type | Default Value |
| ------- | ------------- |
| Boolean | `true` |
If `true`, a message will be displayed at the bottom of the results box:
> Results will be cached for {seconds / 60} minutes.
##### `text`
| Type | Default Value |
| ------ | ----------------------------------------------------- |
| String | `"Results will be cached for {seconds / 60} minutes"` |
Sets the caching message text if `show_text` is `true`.
## Maximum Prefix Length
##### `[features.max_prefix]`
##### `enable`
| Type | Default Value |
| ------- | ------------- |
| Boolean | `false` |
Enables or disables a maximum allowed prefix size for BGP Route queries. If enabled, the prefix length of BGP Route queries must be shorter than the `max_prefix_length_ipv4` and `max_prefix_length_ipv6` parameters. For example, a BGP Route query for `192.0.2.0/25` would result in the following error message:
<img src="/max_prefix_error.png" style="width: 70%"></img>
##### `ipv4`
| Type | Default Value |
| ------- | ------------- |
| Integer | `24` |
If `enable` is `true`, sets the maxiumum prefix length allowed for IPv4 BGP Route queries.
##### `ipv6`
| Type | Default Value |
| ------- | ------------- |
| Integer | `64` |
If `enable` is `true`, sets the maxiumum prefix length allowed for IPv6 BGP Route queries.
## BGP Route
##### `[features.bgp_route]`
##### `enable`
| Type | Default Value |
| ------- | ------------- |
| Boolean | `true` |
Enables or disables the BGP Route query type.
## BGP Community
##### `[features.bgp_community]`
##### `enable`
| Type | Default Value |
| ------- | ------------- |
| Boolean | `true` |
Enables or disables the BGP Community query type.
#### Regex
##### `[features.bgp_community.regex]`
Override the default regex patterns for validating BGP Community input.
##### `decimal`
| Type | Default Value |
| ------ | ----------------- |
| String | `"^[0-9]{1,10}$"` |
Decimal/32 bit community format.
##### `extended_as`
| Type | Default Value |
| ------ | -------------------------------- |
| String | `"^([0-9]{0,5})\:([0-9]{1,5})$"` |
Extended community format
##### `large`
| Type | Default Value |
| ------ | ----------------------------------------------- |
| String | `"^([0-9]{1,10})\:([0-9]{1,10})\:[0-9]{1,10}$"` |
Large community format
## BGP AS Path
##### `[features.bgp_aspath]`
##### `enable`
| Type | Default Value |
| ------- | ------------- |
| Boolean | `true` |
Enables or disables the BGP AS Path query type.
#### Regex
##### `[features.bgp_aspath.regex]`
##### `mode`
| Type | Default Value |
| ------ | ------------- |
| String | `"asplain"` |
Sets the AS Path type used **network-wide**. Options are `asplain`, `asdot`. For more information on what these options mean, [click here](https://tools.ietf.org/html/rfc5396).
!!! warning "AS_PATH Format"
This pattern will be used to validate AS_PATH queries to your routers, so it should match how your routers are actually configured.
##### `asplain`
| Type | Default Value |
| ------ | -------------------------------------------- |
| String | `"^(\^|^\_)(\d+\_|\d+\$|\d+\(\_\.\+\_\))+$"` |
Regex pattern used to validate `asplain` formatted AS numbers in an AS_PATH. Only used if `mode` is set to `asplain.`
##### `asdot`
| Type | Default Value |
| ------ | ----------------------------------------------------------------- |
| String | `"^(\^|^\_)((\d+\.\d+)\_|(\d+\.\d+)\$|(\d+\.\d+)\(\_\.\+\_\))+$"` |
Regex pattern used to validate `asdot` formatted AS numbers in an AS_PATH. Only used if `mode` is set to `asdot.`
## Ping
##### `[features.ping]`
##### `enable`
| Type | Default Value |
| ------- | ------------- |
| Boolean | `true` |
Enables or disables the Ping query type.
## Traceroute
##### `[features.traceroute]`
##### `enable`
| Type | Default Value |
| ------- | ------------- |
| Boolean | `true` |
Enables or disables the Traceroute query type.

17
docs/configuration/frr-api.md
View File

@@ -1,17 +0,0 @@
# Add User
```console
# useradd -M hyperglass-frr-api
# usermod -L hyerglass-frr-api
```
```console
# chown -R hyerglass-frr-api:hyerglass-frr-api /opt/hyperglass-frr
```
iptables -A INPUT -i loopback1 -s 199.34.92.72 -p tcp --dport 8080 -J ACCEPT
Add user to fttvty group:
```console
# usermod -a -G <group> <user>
```

134
docs/development/index.md
View File

@@ -1,134 +0,0 @@
# Hyperglass Development
Hyperglass is maintained as a [Github project](https://github.com/checktheroads/hyperglass) under the BSD 3-Clause Clear License. Hyperglass users are encouraged to submit Github issues for feature requests and bug reports.
## License
The intent behind the the [BSD 3-Clause Clear License](https://choosealicense.com/licenses/bsd-3-clause-clear/) is to ensure that anyone can use or modify Hyperglass in any way they wish, as long as credit and copyright notice is provied. If you have any questions about this, or wish to request any special permissions, please contact [matt@allroads.io](mailto:matt@allroads.io).
## Structure
Under the main `hyperglass/hyperglass/` directory, the following basic structure is in place:
```
hyperglass/
├── __init__.py
├── command/
├── configuration/
├── gunicorn_config.py
├── hyperglass.py
├── manage.py
├── render/
├── static/
└── wsgi.py
```
### Scripts
#### `hyperglass.py`
Main Flask application. Passes input to the `command.execute` module.
#### `manage.py`
Management script for perfoming one-off actions. For now, the only action implemented is a manual clearing of the Flask-cache cache. To clear the cache, run `python3 manage.py --clearcache`.
### Directories
#### command/
```
hyperglass/command/
├── __init__.py
├── construct.py
├── execute.py
└── parse.py
```
##### `execute.py`
Matches router name to router IP, OS, and credentials. Passes data to `cmd_construct.py`, uses the results to execute the Netmiko action. Also performs error handling in the event of a [blacklist](/configuration/blacklist) match.
##### `construct.py`
Constructs full commands to run on routers from `hyperglass/hyperglass/config/commands.toml`. Also performs error handling in the event of input errors.
##### `parser.py`
Parses output before presentation to the user. For the time being, only BGP output from Cisco IOS is parsed. This is because for BGP Community and AS_PATH lookups, Cisco IOS returns results for *all* address families, including VPNv4. This script ensures that only IPv4 and IPv6 address family output is returned.
#### configuration/
The `configuration/` directory contains all TOML config files used by Hyperglass:
```
hyperglass/configuration/
├── __init__.py
├── blacklist.toml
├── commands.toml
├── config.toml
├── devices.toml
└── requires_ipv6_cidr.toml
```
As a module, `configuration` imports configuration from TOML configuration files, defines default values, and exports each as a variable that can be called in other scripts.
#### static/
The `static/` directory contains all static HTML/CSS/JS files used for serving the site:
```
hyperglass/static/
├── css/
│   ├── hyperglass.css
│   └── icofont
├── images/
│   ├── brand.svg
│   ├── favicon
│   ├── hyperglass-dark.png
│   └── hyperglass-light.png
├── js/
│   ├── hyperglass.js
│   ├── jquery-3.4.0.min.js
│   └── jquery-3.4.0.min.map
└── sass/
├── base
├── components
├── custom
├── elements
├── grid
├── hyperglass.scss
├── layout
└── utilities
```
- `css/hyperglass.css` Final CSS file compiled from Sass file `hyperglass.scss`. Sass compiles all the `.sass` files located under `sass/` and combines them into a single CSS file.
- `css/icofont/` Completely free alternative to FontAwesome - [Icofont](https://icofont.com/).
- `js/hyerpglass.js` Basic Javascript helper to perform AJAX queries necessary to pull in dynamic information and render content.
#### render/
The `render/` directory contains the `render` module, which renders HTML and Sass templates, compiles Sass to CSS.
```
hyperglass/render/
├── __init__.py
└── templates/
├── 415.html
├── 429.html
├── base.html
├── footer.html
├── footer.md
├── hyperglass.scss
└── index.html
```
`render/templates/` contains the Jinja2 templates themselves:
- `415.html` General error page template.
- `429.html` Site load rate limit page.
- `base.html` Base template inherited by all other templates. Contains HTML `head`, JavaScript, etc.
- `footer.html` Footer template containing footer text and hyperglass credit link.
- `footer.md` Text that appears in the footer, if enabled. Markdown will be rendered as HTML.
- `hyperglass.scss` Generates SCSS file for Bulma and local customizations.
- `index.html` Main page template.

17
docs/extras/common_as_path_regex.md
View File

@@ -1,17 +0,0 @@
| Expression | Match |
| :----------------------- | ----------------------------------------------------: |
| `.\*` | Anything |
| `.+` | One Character |
| `^$` | Local Routes |
| `\_65000$` | Originated by `AS65000` |
| `^65000\_` | Received from `AS65000` |
| `_65000_` | Via `AS65000` |
| `_65000_65001_` | Via `AS65000` and `AS65001` |
| `_(65000_)+` | Multiple `AS65000` in path |
| `^[0-9]+$` | AS_PATH length of 1 |
| `^[0-9]+_[0-9]+$` | AS_PATH length of 2 |
| `^[0-9]*_[0-9]+$` | AS_PATH length of 1 or 2 |
| `^[0-9]*_[0-9]*$` | AS_PATH length of 0, 1, or 2 |
| `^[0-9]+_[0-9]+_[0-9]+$` | AS_PATH length of 3 |
| `_(65000\|65001)_` | Anything that has gone through `AS65000` or `AS65001` |
| `_65000(_.+_)65001$` | Anything from `AS65001` that passed through `AS65001` |

56
docs/extras/securing-router-access.md
View File

@@ -1,56 +0,0 @@
More than likely, you'll want to "lock down" what commands can be executed with the credentials you've provided in `hyperglass/hyperglass/configuration/devices.toml`. It is **strongly** recommended to use a low privilege read only account and not your full administrator account. Even though Hyperglass is coded to only run certain commands to begin with, you're more than likely still exposing the server Hyperglass runs on to the internet, and on that server is a plain text file with your router's credentials in it. Take precautions.
# Cisco IOS
On Cisco IOS, **parser views** are the recommended tool to restrict access. Basic instructions for configuring Cisco IOS parser views for the default enabled query types are below:
```
parser view hyperglass
secret <secret>
commands exec include all terminal width
commands exec include all terminal length
commands exec include all traceroute
commands exec include all ping
commands exec include all show bgp
!
username hyperglass privilege 15 view hyperglass secret <secret>
```
!!! note "Terminal"
The `terminal length` and `terminal width` commands are required by Netmiko for session handling. If you remove these, Hyperglass will not work.
# Cisco IOS-XR
On Cisco IOS-XR, **taskgroups** are the recommended tool to restrict access. Basic instructoins for configuring Cisco IOS-XR taskgroups for the default enabled query types are below:
```
taskgroup hyperglass
task read bgp
!
usergroup hyperglass
taskgroup hyperglass
!
username hyperglass
group hyperglass
group operator
secret <secret>
```
!!! warning "IOS-XR"
I have not yet figured out a way to enable all the extended options for `ping` and `traceroute` (source IP, count, etc.) without adding the `group operator` statement to the taskgroup. If anyone knows of a way to do this, I welcome a docs PR.
# Juniper
On JunOS, **system login classes** are the recommended tool to restrict access. Basic instructoins for configuring Juniper JunOS login classes for the default enabled query types are below:
```
edit system login class hyperglass
set permissions floppy
set allow-commands-regexp [ "show route protocol bgp" ping traceroute "show route protocol bgp table inet.0" "show route protocol bgp table inet6.0" "ping inet" "ping inet6" "traceroute inet" "traceroute inet6" ]
top
set system login user hyperglass class hyperglass authentication plain-text-password
```

82
docs/extras/supported-device-types.md
View File

@@ -1,82 +0,0 @@
# HTTP API
- FRRouting via [hyperglass-frr](https://github.com/checktheroads/hyperglass-frr) API.
# Netmiko
Updated **2019-04-28** from [Netmiko](https://github.com/ktbyers/netmiko/blob/master/netmiko/ssh_dispatcher.py#L76).
```console
a10
accedian
alcatel_aos
alcatel_sros
apresia_aeos
arista_eos
aruba_os
avaya_ers
avaya_vsp
brocade_fastiron
brocade_netiron
brocade_nos
brocade_vdx
brocade_vyos
checkpoint_gaia
calix_b6
ciena_saos
cisco_asa
cisco_ios
cisco_nxos
cisco_s300
cisco_tp
cisco_wlc
cisco_xe
cisco_xr
coriant
dell_dnos9
dell_force10
dell_os6
dell_os9
dell_os10
dell_powerconnect
dell_isilon
eltex
enterasys
extreme
extreme_ers
extreme_exos
extreme_netiron
extreme_nos
extreme_slx
extreme_vdx
extreme_vsp
extreme_wing
f5_ltm
f5_tmsh
f5_linux
fortinet
generic_termserver
hp_comware
hp_procurve
huawei
huawei_vrpv8
ipinfusion_ocnos
juniper
juniper_junos
linux
mellanox
mrv_optiswitch
netapp_cdot
netscaler
oneaccess_oneos
ovs_linux
paloalto_panos
pluribus
quanta_mesh
rad_etx
ruckus_fastiron
ubiquiti_edge
ubiquiti_edgeswitch
vyatta_vyos
vyos
```

BIN
docs/hyperglass-dark.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 54 KiB

25
docs/index.md
View File

@@ -1,25 +0,0 @@
<img src="/hyperglass-dark.png" width=300></img>
# What is Hyperglass?
**Hyperglass** is an open source looking glass application to provide customers, peers, and partners of network operators with unattended visibility into the operator's network.
# Yet Another Looking Glass?
Many of the more popular open source looking glass applications are written in PHP or Perl, languages infrequently used by many network engineers today. With the widespread adoption of network operations tooling such as [Netmiko](https://github.com/ktbyers/netmiko), [Netbox](https://github.com/digitalocean/netbox), and [Napalm](https://github.com/napalm-automation/napalm), Python is most often the language of choice for network operators. Hyperglass is built completely on Python 3 and utilizes user-friendly configuration files to provide a highly customizable, easy to deploy looking glass app.
Hyperglass was created with the lofty goal of benefiting the internet community at-large, by providing an easier and more familiar way for operators to provide looking glass services to their customers, peers, and partners.
# Application Stack
| Function | Component |
| -------------------------- | --------- |
| Front End Framework | Bulma |
| Front End Application | Flask |
| Back End Application | Python 3 |
| Device Connection Handling | Netmiko |
| Configuration Format | TOML |
# Get Started
See the [installation guide](<>) to get started.

50
docs/installation/installing-hyperglass.md
View File

@@ -1,50 +0,0 @@
# Download
#### System Requirements
!!! warning "Compatibility"
To date, Hyperglass has only been installed tested on Ubuntu Linux 18.04, and was developed on macOS 10.14. Installation instructions are specific to Ubuntu 18.04. Installation instructions for additional operating systems are forthcoming (contribution welcome!).
#### OS Dependencies
Hyperglass is written and tested on Python 3.7, but should be backwards compatible with any Python 3 version (albeit untested). If needed, install Python 3 and PyPi 3 on your system:
```console
# apt install -y python3 python3-pip
```
#### Clone the repository
```console
$ cd /opt/
$ git clone https://github.com/checktheroads/hyperglass
```
# Install
#### Python Dependencies
```console
$ cd /opt/hyperglass/
$ pip3 install -r requirements.txt
```
#### Migrate Configuration Files
```console
$ cd /opt/hyperglass/
$ python3 manage.py migrateconfig
```
All `*.example` files in `hyperglass/hyperglass/configuration/` will be copied to `.toml` extension for use by hyperglass. This is a non-destructive copy, so if you already have `*.toml` files in this directory, they will *not* be overwritten.
# Test
At this stage, Hyperglass should be able to start up with the built-in Flask development server. This will be enough to verify that the application itself can run, and provie a means to test branding customizations, router connectivity, etc., prior to placing a production-grade WSGI & web server in front of Hyperglass.
```console
$ cd /opt/hyperglass/
$ python3 manage.py testserver
```
You should now be able to access hyperglass by loading the name or IP on port 5000 in a web browser, for example: `http://10.0.0.1:5000`. Note that the Flask development server is **not** suited for production use. This will simply verify that the application and dependencies have been correctly installed. Production deployment will be covered in the next sections.

104
docs/installation/reverseproxy.md
View File

@@ -1,104 +0,0 @@
More than likely, you'll be exposing Hyperglass to the internet. It is recommended practice to run most web applications behind a reverse proxy, such as Nginx, Apache, Caddy, etc. This example uses Nginx, but can easily be adapted to other reverse proxy applications if you prefer.
#### Example
The below Nginx example assumes the default [Gunicorn](installation/wsgi) settings are used.
```nginx
geo $not_prometheus_hosts {
default 1;
192.0.2.1/32 0;
}
server {
listen 80;
listen [::]:80 ipv6only=on;
client_max_body_size 1024;
server_name lg.domain.tld;
location /metrics {
if ($not_prometheus_hosts) {
rewrite /metrics /getyourownmetrics;
}
try_files $uri @proxy_to_app;
}
location /static/ {
alias /opt/hyperglass/hyperglass/static/;
}
location / {
try_files $uri @proxy_to_app;
}
location @proxy_to_app {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_redirect off;
proxy_pass http://[::1]:8001;
}
}
```
This configuration, in combination with the default Gunicorn configuration, makes the hyperglass front-end dual stack IPv4/IPv6 capable. To add SSL support, Nginx can be easily adjusted to terminate front-end SSL connections:
```nginx
geo $not_prometheus_hosts {
default 1;
192.0.2.1/32 0;
}
server {
listen 80;
listen [::]:80;
server_name lg.domain.tld;
return 301 https://$host$request_uri;
}
server {
listen [::]:443 ssl ipv6only=on;
listen 443 ssl;
ssl_certificate <path to certificate>;
ssl_certificate_key <path to private key>;
client_max_body_size 1024;
server_name lg.domain.tld;
location /metrics {
if ($not_prometheus_hosts) {
rewrite /metrics /getyourownmetrics;
}
try_files $uri @proxy_to_app;
}
location /static/ {
alias /opt/hyperglass/hyperglass/static/;
}
location / {
try_files $uri @proxy_to_app;
}
location @proxy_to_app {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_redirect off;
proxy_pass http://[::1]:8001;
}
}
```
[Let's Encrypt](https://letsencrypt.org/) provides automatic (and free) SSL certificate generation and renewal. There are a number of guides available on how to integrate Let's Encrypt with Nginx (or your reverse proxy of choice). Some examples:
- Digital Ocean: [How To Secure Nginx with Let's Encrypt on Ubuntu 18.04](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-18-04)
- NGINX: [Using Free Let’s Encrypt SSL/TLS Certificates with NGINX](https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/)
The `/metrics` block will ensure that hosts defined in the `geo $not_prometheus_hosts` directive are allowed to reach the `/metrics` URI, but that any other hosts will have the a request for `/metrics` rewritten to `/getyourownmetrics`, which will render the 404 error page.

26
docs/installation/systemd.md
View File

@@ -1,26 +0,0 @@
More than likely, you'll want to run Hyperglass as a service so that it automatically starts on server boot. Any service manager can be used, however Ubuntu `systemd` instructions are included as a reference.
For easy installation, migrate the example `systemd` service:
```console
$ cd /opt/hyperglass/
$ python3 manage.py migratesystemd
```
This copies the example systemd service to `/etc/systemd/system/hyperglass.service`
#### Example
```ini
[Unit]
Description=Hyperglass
After=network.target
[Service]
User=www-data
Group=www-data
WorkingDirectory=/opt/hyperglass
ExecStart=/usr/local/bin/gunicorn -c /opt/hyperglass/hyperglass/gunicorn_config.py hyperglass.wsgi
[Install]
WantedBy=multi-user.target
```

32
docs/installation/wsgi.md
View File

@@ -1,32 +0,0 @@
For production builds, we'll want to have a real WSGI front end instead of the built in Flask developer web server. For time's sake, Ubuntu 18.04 instructions are provided. That said, this is a pretty generic setup and should be easily replicable to other platforms.
# Gunicorn Installation
Gunicorn is a WSGI server written in Python.
## Install
```console
$ pip3 install gunicorn
```
## Configure
Migrate the example Gunicorn configuration file:
```console
$ cd /opt/hyperglass/
$ python3 manage.py migrate-gunicorn
```
Open `hyperglass/hyperglass/gunicorn_config.py`, and adjust the parameters to match your local system. For example, make sure the `command` parameter matches the location of your `gunicorn` executable (`which gunicorn`), the `pythonpath` parameter matches the location where hyperglass is installed, and that the `user` parameter matches the user you're running hyperglass as:
### Permissions
Gunicorn requires read/write/executable access to the entire `hyperglass/hyperglass` directory in order to read its configuration and execute the python code. If running gunicorn as `www-data`, fix permissions with:
```console
# cd /opt/hyperglass/
# python3 manage.py update-permissions --user <user> --group <group>
```
!!! note "File Ownership"
If the `--user` and `--group` options are not specified, `www-data` will be used.

BIN
docs/max_prefix_error.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 25 KiB

1
docs/monitoring.md
View File

@@ -1 +0,0 @@
Hyperglass has built in support for [Prometheus](https://prometheus.io/) metrics.

BIN
docs/ping_traceroute_cidr.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 21 KiB

3
docs/ratelimiting.md
View File

@@ -1,3 +0,0 @@
Hyperglass supports configurable rate limiting of both site loads and queries. By default, users are able to reach the site up to 120 times per minute, and submit up to 5 queries per minute. When the site limit is reached, users are directed to a separate error page until the timer expires. When the query limit is reached, an error message is displayed, and no further queries are allowed until the timer expires.
Hyperglass uses [Flask-Limiter](https://github.com/alisaifee/flask-limiter) to handle application rate limiting. In Flask, the `/lg` route, which is used for actual queries, is associated with the query rate limit, while the default `/` route is associated with the site rate limit. Both of these limits are configurabale in `hyperglass/hyperglass/configs/config.toml`. See [here](/configuration/general/#rate_limit_query) for more information.

2
docs/requirements.txt
View File

@@ -1,2 +0,0 @@
pygments
pymdown-extensions

BIN
docs/requires_ipv6_cidr.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 23 KiB

BIN
docs/traceroute_nanog.pdf
View File

Binary file not shown.

963
grafana.json Normal file
View File

@@ -0,0 +1,963 @@
{
"annotations": {
"list": [{
"builtIn": 1,
"datasource": "-- Grafana --",
"enable": true,
"hide": true,
"iconColor": "rgba(0, 211, 255, 1)",
"name": "Annotations & Alerts",
"type": "dashboard"
}]
},
"editable": true,
"gnetId": null,
"graphTooltip": 0,
"id": 7,
"iteration": 1560633009018,
"links": [],
"panels": [{
"cacheTimeout": null,
"colorBackground": true,
"colorPostfix": false,
"colorPrefix": false,
"colorValue": false,
"colors": [
"#40798c",
"#330036",
"#330036"
],
"format": "none",
"gauge": {
"maxValue": 100,
"minValue": 0,
"show": false,
"thresholdLabels": false,
"thresholdMarkers": true
},
"gridPos": {
"h": 3,
"w": 4,
"x": 0,
"y": 0
},
"id": 4,
"interval": null,
"links": [],
"mappingType": 1,
"mappingTypes": [{
"name": "value to text",
"value": 1
},
{
"name": "range to text",
"value": 2
}
],
"maxDataPoints": 100,
"nullPointMode": "connected",
"nullText": null,
"postfix": "",
"postfixFontSize": "50%",
"prefix": "",
"prefixFontSize": "50%",
"rangeMaps": [{
"from": "null",
"text": "N/A",
"to": "null"
}],
"sparkline": {
"fillColor": "rgba(31, 118, 189, 0.18)",
"full": false,
"lineColor": "rgb(31, 120, 193)",
"show": false
},
"tableColumn": "",
"targets": [{
"expr": "sum(count_data_total)",
"format": "time_series",
"instant": true,
"intervalFactor": 1,
"refId": "A"
}],
"thresholds": "",
"timeFrom": null,
"timeShift": null,
"title": "Queries Processed",
"type": "singlestat",
"valueFontSize": "200%",
"valueMaps": [{
"op": "=",
"text": "N/A",
"value": "null"
}],
"valueName": "total"
},
{
"aliasColors": {
"dtn01": "#79b791",
"hnl01": "#330036",
"las01": "#40798c",
"phx01": "#ff5e5b"
},
"breakPoint": "50%",
"cacheTimeout": null,
"combine": {
"label": "Others",
"threshold": 0
},
"fontSize": "80%",
"format": "short",
"gridPos": {
"h": 12,
"w": 7,
"x": 4,
"y": 0
},
"id": 7,
"interval": null,
"legend": {
"percentage": false,
"show": true,
"values": true
},
"legendType": "Under graph",
"links": [],
"maxDataPoints": 3,
"nullPointMode": "connected",
"pieType": "donut",
"strokeWidth": 1,
"targets": [{
"expr": "sum(count_data_total) by (loc_id)",
"format": "time_series",
"instant": true,
"interval": "",
"intervalFactor": 1,
"legendFormat": "{{loc_id}}",
"refId": "D"
}],
"timeFrom": null,
"timeShift": null,
"title": "Queries by Location",
"type": "grafana-piechart-panel",
"valueName": "total"
},
{
"aliasColors": {
"BGP AS Path": "#330036",
"BGP Community": "#ff5e5b",
"BGP Route": "#79b791",
"Ping": "#40798c",
"Traceroute": "#ffba49"
},
"breakPoint": "50%",
"cacheTimeout": null,
"combine": {
"label": "Others",
"threshold": 0
},
"fontSize": "80%",
"format": "short",
"gridPos": {
"h": 12,
"w": 7,
"x": 11,
"y": 0
},
"id": 2,
"interval": null,
"legend": {
"percentage": false,
"show": true,
"values": true
},
"legendType": "Under graph",
"links": [],
"maxDataPoints": 3,
"nullPointMode": "connected",
"pieType": "donut",
"strokeWidth": 1,
"targets": [{
"expr": "sum(count_data_total{type=\"bgp_route\"})",
"format": "time_series",
"instant": true,
"interval": "",
"intervalFactor": 1,
"legendFormat": "BGP Route",
"refId": "A"
},
{
"expr": "sum(count_data_total{type=\"bgp_aspath\"})",
"format": "time_series",
"instant": true,
"interval": "",
"intervalFactor": 1,
"legendFormat": "BGP AS Path",
"refId": "B"
},
{
"expr": "sum(count_data_total{type=\"bgp_community\"})",
"format": "time_series",
"instant": true,
"interval": "",
"intervalFactor": 1,
"legendFormat": "BGP Community",
"refId": "C"
},
{
"expr": "sum(count_data_total{type=\"ping\"})",
"format": "time_series",
"instant": true,
"interval": "",
"intervalFactor": 1,
"legendFormat": "Ping",
"refId": "D"
},
{
"expr": "sum(count_data_total{type=\"traceroute\"})",
"format": "time_series",
"instant": true,
"interval": "",
"intervalFactor": 1,
"legendFormat": "Traceroute",
"refId": "E"
}
],
"timeFrom": null,
"timeShift": null,
"title": "Queries by Type",
"type": "grafana-piechart-panel",
"valueName": "total"
},
{
"columns": [],
"fontSize": "100%",
"gridPos": {
"h": 12,
"w": 6,
"x": 18,
"y": 0
},
"id": 9,
"interval": "",
"links": [],
"pageSize": null,
"scroll": true,
"showHeader": true,
"sort": {
"col": 8,
"desc": true
},
"styles": [{
"alias": "Time",
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"pattern": "Time",
"type": "hidden"
},
{
"alias": "",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"decimals": 2,
"pattern": "__name__",
"thresholds": [],
"type": "hidden",
"unit": "short"
},
{
"alias": "Target",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "target",
"thresholds": [],
"type": "string",
"unit": "short"
},
{
"alias": "Count",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 0,
"mappingType": 1,
"pattern": "Value",
"thresholds": [],
"type": "number",
"unit": "short"
},
{
"alias": "",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "instance",
"thresholds": [],
"type": "hidden",
"unit": "short"
},
{
"alias": "",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "job",
"thresholds": [],
"type": "hidden",
"unit": "short"
},
{
"alias": "",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "source",
"thresholds": [],
"type": "hidden",
"unit": "short"
},
{
"alias": "",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "type",
"thresholds": [],
"type": "hidden",
"unit": "short"
},
{
"alias": "Location",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "loc_id",
"thresholds": [],
"type": "string",
"unit": "short"
}
],
"targets": [{
"expr": "topk(10, sum(count_data_total{target=~\"$target\"}) by (target))",
"format": "table",
"instant": true,
"intervalFactor": 1,
"refId": "A"
}],
"timeFrom": null,
"timeShift": null,
"title": "Top 10 Query Targets",
"transform": "table",
"type": "table"
},
{
"cacheTimeout": null,
"colorBackground": true,
"colorPostfix": false,
"colorPrefix": false,
"colorValue": false,
"colors": [
"#40798c",
"#ff5e5b",
"#330036"
],
"format": "none",
"gauge": {
"maxValue": 100,
"minValue": 0,
"show": false,
"thresholdLabels": false,
"thresholdMarkers": true
},
"gridPos": {
"h": 3,
"w": 4,
"x": 0,
"y": 3
},
"id": 10,
"interval": null,
"links": [],
"mappingType": 1,
"mappingTypes": [{
"name": "value to text",
"value": 1
},
{
"name": "range to text",
"value": 2
}
],
"maxDataPoints": 100,
"nullPointMode": "connected",
"nullText": null,
"postfix": "",
"postfixFontSize": "50%",
"prefix": "",
"prefixFontSize": "50%",
"rangeMaps": [{
"from": "null",
"text": "N/A",
"to": "null"
}],
"sparkline": {
"fillColor": "rgba(31, 118, 189, 0.18)",
"full": false,
"lineColor": "rgb(31, 120, 193)",
"show": false
},
"tableColumn": "",
"targets": [{
"expr": "sum(count_notfound_total)",
"format": "time_series",
"instant": true,
"intervalFactor": 1,
"refId": "A"
}],
"thresholds": "",
"timeFrom": null,
"timeShift": null,
"title": "404 Errors",
"type": "singlestat",
"valueFontSize": "200%",
"valueMaps": [{
"op": "=",
"text": "N/A",
"value": "null"
}],
"valueName": "total"
},
{
"cacheTimeout": null,
"colorBackground": true,
"colorPostfix": false,
"colorPrefix": false,
"colorValue": false,
"colors": [
"#40798c",
"#40798c",
"#330036"
],
"description": "",
"format": "none",
"gauge": {
"maxValue": 100,
"minValue": 0,
"show": false,
"thresholdLabels": false,
"thresholdMarkers": true
},
"gridPos": {
"h": 3,
"w": 4,
"x": 0,
"y": 6
},
"id": 11,
"interval": null,
"links": [],
"mappingType": 1,
"mappingTypes": [{
"name": "value to text",
"value": 1
},
{
"name": "range to text",
"value": 2
}
],
"maxDataPoints": 100,
"nullPointMode": "connected",
"nullText": null,
"postfix": "",
"postfixFontSize": "50%",
"prefix": "",
"prefixFontSize": "50%",
"rangeMaps": [{
"from": "null",
"text": "N/A",
"to": "null"
}],
"sparkline": {
"fillColor": "rgba(31, 118, 189, 0.18)",
"full": false,
"lineColor": "rgb(31, 120, 193)",
"show": false
},
"tableColumn": "",
"targets": [{
"expr": "sum(count_ratelimit_total{message=\"429 Too Many Requests: Query\"})",
"format": "time_series",
"instant": true,
"intervalFactor": 1,
"refId": "A"
}],
"thresholds": "",
"timeFrom": null,
"timeShift": null,
"title": "Rate Limit Exceeded: Query",
"type": "singlestat",
"valueFontSize": "200%",
"valueMaps": [{
"op": "=",
"text": "N/A",
"value": "null"
}],
"valueName": "total"
},
{
"cacheTimeout": null,
"colorBackground": true,
"colorPostfix": false,
"colorPrefix": false,
"colorValue": false,
"colors": [
"#40798c",
"#79b791",
"#330036"
],
"description": "",
"format": "none",
"gauge": {
"maxValue": 100,
"minValue": 0,
"show": false,
"thresholdLabels": false,
"thresholdMarkers": true
},
"gridPos": {
"h": 3,
"w": 4,
"x": 0,
"y": 9
},
"id": 12,
"interval": null,
"links": [],
"mappingType": 1,
"mappingTypes": [{
"name": "value to text",
"value": 1
},
{
"name": "range to text",
"value": 2
}
],
"maxDataPoints": 100,
"nullPointMode": "connected",
"nullText": null,
"postfix": "",
"postfixFontSize": "50%",
"prefix": "",
"prefixFontSize": "50%",
"rangeMaps": [{
"from": "null",
"text": "N/A",
"to": "null"
}],
"sparkline": {
"fillColor": "rgba(31, 118, 189, 0.18)",
"full": false,
"lineColor": "rgb(31, 120, 193)",
"show": false
},
"tableColumn": "",
"targets": [{
"expr": "sum(count_ratelimit_total{message=\"429 Too Many Requests: Site\"})",
"format": "time_series",
"instant": true,
"intervalFactor": 1,
"refId": "A"
}],
"thresholds": "",
"timeFrom": null,
"timeShift": null,
"title": "Rate Limit Exceeded: Site",
"type": "singlestat",
"valueFontSize": "200%",
"valueMaps": [{
"op": "=",
"text": "N/A",
"value": "null"
}],
"valueName": "total"
},
{
"columns": [],
"fontSize": "100%",
"gridPos": {
"h": 6,
"w": 24,
"x": 0,
"y": 12
},
"id": 6,
"links": [],
"pageSize": null,
"scroll": true,
"showHeader": true,
"sort": {
"col": 0,
"desc": true
},
"styles": [{
"alias": "Time",
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"pattern": "Time",
"type": "date"
},
{
"alias": "",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "__name__",
"thresholds": [],
"type": "hidden",
"unit": "short"
},
{
"alias": "",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "job",
"thresholds": [],
"type": "hidden",
"unit": "short"
},
{
"alias": "",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "Value",
"thresholds": [],
"type": "hidden",
"unit": "short"
},
{
"alias": "",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "instance",
"thresholds": [],
"type": "hidden",
"unit": "short"
},
{
"alias": "Location",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "loc_id",
"thresholds": [],
"type": "string",
"unit": "short"
},
{
"alias": "Source",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "source",
"thresholds": [],
"type": "string",
"unit": "short"
},
{
"alias": "Target",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "target",
"thresholds": [],
"type": "string",
"unit": "short"
},
{
"alias": "Query Type",
"colorMode": null,
"colors": [
"rgba(245, 54, 54, 0.9)",
"rgba(237, 129, 40, 0.89)",
"rgba(50, 172, 45, 0.97)"
],
"dateFormat": "YYYY-MM-DD HH:mm:ss",
"decimals": 2,
"mappingType": 1,
"pattern": "type",
"preserveFormat": false,
"sanitize": false,
"thresholds": [],
"type": "string",
"unit": "short",
"valueMaps": [{
"text": "BGP Route",
"value": "bgp_route"
},
{
"text": "BGP Community",
"value": "bgp_community"
},
{
"text": "BGP AS Path",
"value": "bgp_aspath"
},
{
"text": "Ping",
"value": "ping"
},
{
"text": "Traceroute",
"value": "traceroute"
}
]
}
],
"targets": [{
"expr": "count_data_total",
"format": "table",
"instant": true,
"intervalFactor": 1,
"refId": "A"
}],
"timeFrom": null,
"timeShift": null,
"title": "Query Log",
"transform": "table",
"type": "table"
}
],
"schemaVersion": 18,
"style": "dark",
"tags": [],
"templating": {
"list": [{
"allValue": null,
"current": {
"selected": false,
"text": "All",
"value": "$__all"
},
"datasource": "Prometheus",
"definition": "label_values(type)",
"hide": 0,
"includeAll": true,
"label": "Query Type",
"multi": false,
"name": "query_type",
"options": [],
"query": "label_values(type)",
"refresh": 1,
"regex": "",
"skipUrlSync": false,
"sort": 0,
"tagValuesQuery": "",
"tags": [],
"tagsQuery": "",
"type": "query",
"useTags": false
},
{
"allValue": null,
"current": {
"selected": true,
"text": "All",
"value": "$__all"
},
"datasource": "Prometheus",
"definition": "label_values(loc_id)",
"hide": 0,
"includeAll": true,
"label": "Location",
"multi": false,
"name": "location",
"options": [],
"query": "label_values(loc_id)",
"refresh": 1,
"regex": "",
"skipUrlSync": false,
"sort": 0,
"tagValuesQuery": "",
"tags": [],
"tagsQuery": "",
"type": "query",
"useTags": false
},
{
"allValue": null,
"current": {
"selected": true,
"text": "All",
"value": "$__all"
},
"datasource": "Prometheus",
"definition": "label_values(source)",
"hide": 0,
"includeAll": true,
"label": "Source IP",
"multi": false,
"name": "source",
"options": [],
"query": "label_values(source)",
"refresh": 1,
"regex": "",
"skipUrlSync": false,
"sort": 0,
"tagValuesQuery": "",
"tags": [],
"tagsQuery": "",
"type": "query",
"useTags": false
},
{
"allValue": null,
"current": {
"selected": true,
"text": "All",
"value": "$__all"
},
"datasource": "Prometheus",
"definition": "label_values(target)",
"hide": 0,
"includeAll": true,
"label": "Target",
"multi": false,
"name": "target",
"options": [],
"query": "label_values(target)",
"refresh": 1,
"regex": "",
"skipUrlSync": false,
"sort": 0,
"tagValuesQuery": "",
"tags": [],
"tagsQuery": "",
"type": "query",
"useTags": false
}
]
},
"time": {
"from": "now-6h",
"to": "now"
},
"timepicker": {
"refresh_intervals": [
"5s",
"10s",
"30s",
"1m",
"5m",
"15m",
"30m",
"1h",
"2h",
"1d"
],
"time_options": [
"5m",
"15m",
"1h",
"6h",
"12h",
"24h",
"2d",
"7d",
"30d"
]
},
"timezone": "",
"title": "hyperglass",
"uid": "1kYrhFnWk",
"version": 42
}

40
mkdocs.yml
View File

@@ -1,40 +0,0 @@
site_name: 'hyperglass documentation'
site_author: 'checktheroads | Matt Love'
site_url: 'https://hyperglass.readthedocs.io'
copyright: ''
nav:
- Home: 'index.md'
- Installation:
- 'Installing Hyperglass': 'installation/installing-hyperglass.md'
- 'HTTP/WSGI': 'installation/wsgi.md'
- 'Systemd': 'installation/systemd.md'
- 'Reverse Proxy & SSL': 'installation/reverseproxy.md'
- Configuration:
- 'Configuring Hyperglass': 'configuration/configuration.md'
- 'Devices': 'configuration/devices.md'
- 'Branding': 'configuration/branding.md'
- 'Features': 'configuration/features.md'
- Caching: 'caching.md'
- Rate Limiting: 'ratelimiting.md'
- Monitoring: 'monitoring.md'
- Development:
- 'Introduction': 'development/index.md'
- Extras:
- 'Common AS_PATH Regular Expressions': 'extras/common_as_path_regex.md'
- 'Securing Router Access': 'extras/securing-router-access.md'
- 'Supported Device Types': 'extras/supported-device-types.md'
# Theme Configuration
theme:
name: 'readthedocs'
# Extensions
markdown_extensions:
- admonition
- pymdownx.mark
- toc:
permalink: true
toc_depth: 1-3
# Social Links
extra:
social:
- type: 'github'
link: 'https://github.com/checktheroads/hyperglass'

31
screenshots.md
View File

@@ -1,31 +0,0 @@
<img src="hyperglass/static/images/hyperglass-dark.png" width=300></img>
# Main Page
![](screenshots/main.png)
# BGP Lookups
## BGP Route
![](screenshots/lookup_bgp_route.png)
## BGP Community
![](screenshots/lookup_bgp_community.png)
## BGP AS_PATH
![](screenshots/lookup_bgp_aspath.png)
# Ping
![](screenshots/lookup_ping.png)
# Traceroute
![](screenshots/lookup_traceroute.png)
# Help Text
![](screenshots/helptext.png)

BIN
screenshots/helptext.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 150 KiB

BIN
screenshots/lookup_bgp_aspath.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 353 KiB

BIN
screenshots/lookup_bgp_community.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 356 KiB

BIN
screenshots/lookup_bgp_route.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 635 KiB

BIN
screenshots/lookup_ping.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 243 KiB

BIN
screenshots/lookup_traceroute.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 282 KiB

BIN
screenshots/main.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 169 KiB