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

initial

Browse Source
This commit is contained in:
checktheroads
2019-05-07 23:21:41 -07:00
commit 47f1b938cd
125 changed files with 78836 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/configuration/authentication.md Normal file
View File

@@ -0,0 +1,16 @@
Authentication parameters are stored in the `devices.toml` file, at `hyperglass/hyperglass/config/devices.toml`. The array of tables simply stores the username and password for a device. SSH Key authentication is not yet supported.
Example:
```toml
[credential.'default']
username = "hyperglass"
password = "secret_password"
[credential.'other_credential']
username = "other_username"
password = "other_secret_password"
```
!!! warning "Security Warning"
These values are stored in plain text. Make sure the accounts are restricted and that the configuration file is stored in a secure location.

25
docs/configuration/blacklist.md Normal file
View File

@@ -0,0 +1,25 @@
Blacklisted querys are defined in `hyperglass/hyperglass/config/blacklist.toml`.
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 want to prevent users from looking up 198.18.0.0/15 or any contained host or prefix, you can add it to the blacklist:
```toml
blacklist = [
198.18.0.0/15
]
```
If you have multiple hosts/subnets you wish to blacklist, you can do so by adding a comma `,` after each entry (except the last):
```toml
blacklist = [
'198.18.0.0/15',
'10.0.0.0/8',
'192.168.0.0/16',
'2001:db8::/32'
'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"></img>

306
docs/configuration/branding.md Normal file
View File

@@ -0,0 +1,306 @@
<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/config/config.toml`:
### site_title
| Type | Default Value |
| ------ | -------------- |
| String | `"hyperglass"` |
HTML `<title>` element that is shown in a browser's title bar.
### title_mode
| Type | Default Value |
| ------ | ------------- |
| String | `"none"` |
Controls the title section on the main page.
#### Parameters
##### `"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.
### enable_footer
| Type | Default Value |
| ------- | ------------- |
| Boolean | `True` |
Enables or disables entire footer element, which contains text defined in `hyperglass/hyperglass/templates/footer.md`.
### enable_credit
| Type | Default Value |
| ------- | ------------- |
| Boolean | `True` |
Enables or disables hoverable icon on the left side of the footer, which links to the hyperglass repo.
### color_btn_submit
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#40798c"` | <span class="bd-color" style="background-color: #40798c;"></span> |
Sets color of the submit button.
### color_tag_loctitle
| 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.
### color_tag_cmdtitle
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#330036"` | <span class="bd-color" style="background-color: #330036;"></span> |
Sets color of the title portion of the command tag which appears at the top of the results box on the right side.
### color_tag_cmd
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#ff5e5b"` | <span class="bd-color" style="background-color: #ff5e5b;"></span> |
Sets color of the command name portion of the command tag which appears at the top of the results box on the right side.
### color_tag_loc
| 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.
### color_hero
| Type | Default Value | Preview |
| ------ | ------------- | ----------------------------------------------------------------- |
| String | `"#fbfffe"` | <span class="bd-color" style="background-color: #fbfffe;"></span> |
Sets the background color of the main page. The main page is a Bulma [fullheight hero class](https://bulma.io/documentation/layout/hero/) layout. This parameter will set the color of the entire hero `<section>` class, including navbar, head, body, and footer subclasses.
### color_progressbar
| 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.
### logo_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.
### logo_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.
### placeholder_prefix
| Type | Default Value |
| ------ | ------------------------------------- |
| String | `"Prefix, IP, Community, or AS_PATH"` |
Sets the placeholder text that appears in the main search box.
### show_peeringdb
| 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.
### text_results
| Type | Default Value |
| ------ | ------------- |
| String | `"Results"` |
Sets the header text of the results box.
### text_location
| Type | Default Value |
| ------ | ------------- |
| String | `"Location"` |
Sets the placeholder text of the location selector.
### 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).
### text_415_title
| Type | Default Value |
| ------ | ----------------- |
| String | `"Error"` |
Sets the title text for the full general error page.
### text_415_subtitle
| Type | Default Value |
| ------ | ------------------------- |
| String | `"Something went wrong."` |
Sets the subtitle text for the full general error page.
### text_415_button
| Type | Default Value |
| ------ | ----------------- |
| String | `"Home"` |
Sets the button text for the full general error page.
### text_help_bgp_route
| Type | Default Value |
| ------ | ------------------------- |
| String | `"Performs BGP table lookup based on IPv4/IPv6 prefix."` |
Sets the BGP Route query help text, displayed when the **?** icon is hovered.
### text_help_bgp_community
| Type | Default Value |
| ------ | ------------------------- |
| String | `'Performs BGP table lookup based on <a href="https://tools.ietf.org/html/rfc4360">Extended</a> or <a href="https://tools.ietf.org/html/rfc8195">Large</a> community value.'` |
Sets the BGP Community query help text, displayed when the **?** icon is hovered.
!!! note
Since there are double quotes (`" "`) in the `<a>` HTML tags, single quotes (`' '`) are required for the TOML string.
### text_help_bgp_aspath
| Type | Default Value |
| ------ | ------------------------- |
| String | `'Performs BGP table lookup based on <code>AS_PATH</code> regular expression.<br>For commonly used BGP regular expressions, <a href="https://hyperglass.readthedocs.io/en/latest/Extras/common_as_path_regex/">click here</a>.'` |
Sets the BGP AS Path query help text, displayed when the **?** icon is hovered.
!!! note
Since there are double quotes (`" "`) in the `<a>` HTML tags, single quotes (`' '`) are required for the TOML string.
### text_help_ping
| Type | Default Value |
| ------ | ------------------------- |
| String | `"Sends 5 ICMP echo requests to the target."` |
Sets the Ping query help text, displayed when the **?** icon is hovered.
### text_help_traceroute
| Type | Default Value |
| ------ | ------------------------- |
| String | `'Performs UDP Based traceroute to the target.<br>For information about how to interpret traceroute results, <a href="https://www.nanog.org/meetings/nanog45/presentations/Sunday/RAS_traceroute_N45.pdf">click here</a>.'` |
Sets the Traceroute query help text, displayed when the **?** icon is hovered.
!!! note
Since there are double quotes (`" "`) in the `<a>` HTML tags, single quotes (`' '`) are required for the TOML string.
### 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. This font is used for all titles, subtitles, and non-code/preformatted text. The value is passed as a Jinja2 variable to the head block in the base template.
### primary_font_name
| Type | Default Value |
| ------ | ------------------------- |
| String | `"Nunito"` |
Sets the web font name for the primary font. This font is used for all titles, subtitles, and non-code/preformatted text. The value is passed as a Jinja2 variable to generate `hyperglass/hyperglass/static/sass/hyperglass.scss`, which ultimately get passed to CSS.
### mono_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. This font is used for all query output text, as well as the command title and command name tag. The value is passed as a Jinja2 variable to the head block in the base template.
### mono_font_name
| Type | Default Value |
| ------ | ------------------------- |
| String | `"Fira Mono"` |
Sets the web font URL for the monospace/code/preformatted text font. This font is used for all query output text, as well as the command title and command name tag. The value is passed as a Jinja2 variable to generate `hyperglass/hyperglass/static/sass/hyperglass.scss`, which ultimately get passed to CSS.

83
docs/configuration/commands.md Normal file
View File

@@ -0,0 +1,83 @@
Commands are defined in `hyperglass/hyperglass/config/commands.toml`. Formatted as a nested array of tables, each table defines the commands that will be used to execute the queries on the routers.
Each table contains three nested tables:
##### dual
Commands that are IP protocol agnostic:
- `bgp_community`
- `bgp_aspath`
##### ipv4
Commands that are IPv4-specific:
- `bgp_route`
- `ping`
- `traceroute`
##### ipv6
Commands that are IPv6-specific:
- `bgp_route`
- `ping`
- `traceroute`
#### Default Configuration
```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}"
```
Every attempt has been made to filter out as much "noise" as possible from the command output.
##### `{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)

160
docs/configuration/devices.md Normal file
View File

@@ -0,0 +1,160 @@
Devices/routers are defined in `hyperglass/hyperglass/config/devices.toml`. `devices.toml` is effectively an array of hash tables/dictionaries/key value pairs:
```toml
[[router]]
address = "10.0.0.1"
asn = "65000"
src_addr_ipv4 = "192.0.2.1"
src_addr_ipv6 = "2001:db8::1"
credential = "default"
location = "pop1"
name = "router1.pop1"
port = "22"
type = "cisco_xr"
proxy = "jumpbox1"
[[router]]
address = "10.0.0.2"
asn = "65000"
src_addr_ipv4 = "192.0.2.2"
src_addr_ipv6 = "2001:db8::2"
credential = "default"
location = "pop2"
name = "router1.pop2"
port = "22"
type = "cisco_ios"
proxy = "jumpbox2"
[[router]]
address = "10.0.0.3"
asn = "65000"
src_addr_ipv4 = "192.0.2.3"
src_addr_ipv6 = "2001:db8::3"
credential = "default"
location = "pop3"
name = "router1.pop3"
port = "22"
type = "juniper"
proxy = "jumpbox3"
```
### Device Keys
#### 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
Display name/hostname of device.
#### port
TCP port for SSH connection to device.
#### type
Device type/vendor name as recognized by [Netmiko](https://github.com/ktbyers/netmiko). See [supported device types](#supported-device-types) for a full list.
#### proxy
Name of SSH proxy/jumpbox, if any, used for connecting to the device. See [here](/configuration/proxy.md) for more information on proxying.
### Supported Device Types
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
```

132
docs/configuration/general.md Normal file
View File

@@ -0,0 +1,132 @@
From `hyperglass/hyperglass/config/config.toml`:
### primary_asn
| Type | Default Value |
| ------ | ------------- |
| String | `"65000"` |
Your network's _primary_ ASN. Number only, e.g. `65000`, **not** `AS65000`.
### debug
| Type | Default Value |
| ------- | ------------- |
| Boolean | `False` |
Enables Flask debugging. May be used to enable other module debugs in the future.
### google_analytics
| Type | Default Value |
| ------ | ------------- |
| String | None |
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).
### message_error
| Type | Default Value |
| ------ | --------------------- |
| String | `"{input} is invalid."` |
Message presented to the user when invalid input is detected. `{input}` will be formatted as the input received from the main search field. For each command, input is validated via regular expression in the following patterns:
| Command | Pattern |
| ------------- | -------------------------------------------- |
| BGP Route | Valid IPv4 or IPv6 Address |
| BGP Community | Valid new-format, 32 bit, or large community |
| BGP AS Path | Any pattern |
| Ping | Valid IPv4 or IPv6 Address |
| Traceroute | Valid IPv4 or IPv6 Address |
!!! note
The BGP AS Path command currently allows `(.*)` to be submitted to the end device. Obviously, the device itself will return an error for garbage input, but ideally this would be "locked down" further. If you have an idea for a regex pattern to validate an `AS_PATH` regex, please submit a PR.
### message_blacklist
| Type | Default Value |
| ------ | ------------------------- |
| String | `"{input} is not allowed."` |
Message presented to the user when an IPv4 or IPv6 address matches the `blacklist.toml` array. `{input}` will be formatted as the input received from the main search field. For information on how this works, please see the [blacklist documentation](/configuration/blacklist).
### message_rate_limit_query
| Type | Default Value |
| ------ | -------------------------------------------------------------------------------------------- |
| String | `"Query limit of {rate_limit_query} per minute reached. Please wait one minute 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. For information on how this works, please see the [rate limiting documentation](/ratelimiting/query).
### enable_bgp_route
| Type | Default Value |
| ------- | ------------- |
| Boolean | `True` |
Enables or disables the BGP Route query type.
### enable_bgp_community
| Type | Default Value |
| ------- | ------------- |
| Boolean | `True` |
Enables or disables the BGP Community query type.
### enable_bgp_aspath
| Type | Default Value |
| ------- | ------------- |
| Boolean | `True` |
Enables or disables the BGP AS Path query type.
### enable_ping
| Type | Default Value |
| ------- | ------------- |
| Boolean | `True` |
Enables or disables the Ping query type.
### enable_traceroute
| Type | Default Value |
| ------- | ------------- |
| Boolean | `True` |
Enables or disables the Traceroute query type.
### rate_limit_query
| Type | Default Value |
| ------- | ------------- |
| String | `"5"` |
Sets the number of queries **per minute** allowed by `remote_address` of the request. For information on how this works, please see the [rate limiting documentation](/ratelimiting/query).
### rate_limit_site
| Type | Default Value |
| ------- | ------------- |
| String | `"120"` |
Sets the number of site loads **per minute** allowed by `remote_address` of the request. For information on how this works, please see the [rate limiting documentation](/ratelimiting/site).
### cache_timeout
| Type | Default Value |
| -------- | ------------- |
| Integer | `120` |
Sets the number of **seconds** to cache the back-end response. For information on how this works, please see the [caching documentation](/caching).
### cache_directory
| Type | Default Value |
| -------- | ------------------------------------ |
| String | `"hyperglass/hyperglass/.flask_cache"` |
Sets the directory where the back-end responses are cached. For information on how this works, please see the [caching documentation](/caching).

45
docs/configuration/proxy.md Normal file
View File

@@ -0,0 +1,45 @@
Proxy servers are defined in `hyperglass/hyperglass/config/devices.toml`. Each proxy definition is a unique TOML table, for 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}"
```
When a proxy server is defined under the `[[router]]` heading in `devices.toml`, 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.
#### 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.
!!! warning "Security Warning"
These values are stored in plain text. Make sure the accounts are restricted and that the configuration file is stored in a secure location.
#### type
Device type/vendor name as recognized by [Netmiko](https://github.com/ktbyers/netmiko). See [supported device types](#supported-device-types) for a full list.
!!! info "Compatibility"
Hyperglass has only been tested with `linux_ssh` as of this writing.
#### 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`.