mirror of
https://github.com/checktheroads/hyperglass
synced 2024-05-11 05:55:08 +00:00
added docs, migrated input validated from JS to execute.py
This commit is contained in:
checktheroads
Binary file not shown.
|
Before Width: | Height: | Size: 64 KiB After Width: | Height: | Size: 18 KiB |
@@ -1,16 +0,0 @@
|
||||
Authentication parameters are stored in the `devices.toml` file, at `hyperglass/hyperglass/configuration/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.
|
||||
@@ -1,25 +0,0 @@
|
||||
Blacklisted querys are defined in `hyperglass/hyperglass/configuration/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>
|
||||
@@ -10,9 +10,10 @@
|
||||
}
|
||||
</style>
|
||||
|
||||
From `hyperglass/hyperglass/configuration/config.toml`:
|
||||
From `hyperglass/hyperglass/configuration/configuration.toml` `[branding]` table.
|
||||
|
||||
### site_title
|
||||
# Site Parameters
|
||||
#### site_title
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | -------------- |
|
||||
@@ -20,7 +21,7 @@ From `hyperglass/hyperglass/configuration/config.toml`:
|
||||
|
||||
HTML `<title>` element that is shown in a browser's title bar.
|
||||
|
||||
### title_mode
|
||||
#### title_mode
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------- |
|
||||
@@ -28,27 +29,17 @@ HTML `<title>` element that is shown in a browser's title bar.
|
||||
|
||||
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.
|
||||
|
||||
##### `"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
|
||||
#### title
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | -------------- |
|
||||
| String | `"hyperglass"` |
|
||||
|
||||
### subtitle
|
||||
#### subtitle
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | -------------------- |
|
||||
@@ -56,7 +47,7 @@ Displays only the Title text defined in the [title](#title) parameter.
|
||||
|
||||
See [primary_asn](#primary_asn) parameter.
|
||||
|
||||
### enable_footer
|
||||
#### enable_footer
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
@@ -64,7 +55,7 @@ See [primary_asn](#primary_asn) parameter.
|
||||
|
||||
Enables or disables entire footer element, which contains text defined in `hyperglass/hyperglass/render/templates/footer.md`.
|
||||
|
||||
### enable_credit
|
||||
#### enable_credit
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
@@ -72,87 +63,7 @@ Enables or disables entire footer element, which contains text defined in `hyper
|
||||
|
||||
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
|
||||
#### show_peeringdb
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
@@ -160,7 +71,93 @@ Sets the placeholder text that appears in the main search box.
|
||||
|
||||
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
|
||||
# Colors
|
||||
|
||||
#### 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_bg
|
||||
|
||||
| Type | Default Value | Preview |
|
||||
| ------ | ------------- | ----------------------------------------------------------------- |
|
||||
| String | `"#fbfffe"` | <span class="bd-color" style="background-color: #fbfffe;"></span> |
|
||||
|
||||
Sets the background color of the main page.
|
||||
|
||||
#### 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
|
||||
|
||||
#### 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.
|
||||
|
||||
# UI Text
|
||||
|
||||
#### placeholder_prefix
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------------------- |
|
||||
| String | `"Prefix, IP, Community, or AS_PATH"` |
|
||||
|
||||
Sets the placeholder text that appears in the main search box.
|
||||
|
||||
#### text_results
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------- |
|
||||
@@ -168,7 +165,7 @@ Enables or disables the PeeringDB link in the upper right corner. If `True`, the
|
||||
|
||||
Sets the header text of the results box.
|
||||
|
||||
### text_location
|
||||
#### text_location
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------- |
|
||||
@@ -176,7 +173,7 @@ Sets the header text of the results box.
|
||||
|
||||
Sets the placeholder text of the location selector.
|
||||
|
||||
### text_cache
|
||||
#### text_cache
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------------------------------------- |
|
||||
@@ -184,7 +181,7 @@ Sets the placeholder text of the location selector.
|
||||
|
||||
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
|
||||
#### text_limiter_title
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ----------------- |
|
||||
@@ -192,7 +189,7 @@ Sets the text at the bottom of the results box that states the cache timeout. `{
|
||||
|
||||
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
|
||||
#### text_limiter_subtitle
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------------------------------------------------------------------- |
|
||||
@@ -200,7 +197,7 @@ Sets the title text for the site-wide rate limit page. Users are redirected to t
|
||||
|
||||
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
|
||||
#### text_500_title
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ----------------- |
|
||||
@@ -208,7 +205,7 @@ Sets the subtitle text for the site-wide rate limit page. Users are redirected t
|
||||
|
||||
Sets the title text for the full general error page.
|
||||
|
||||
### text_415_subtitle
|
||||
#### text_500_subtitle
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
@@ -216,7 +213,7 @@ Sets the title text for the full general error page.
|
||||
|
||||
Sets the subtitle text for the full general error page.
|
||||
|
||||
### text_415_button
|
||||
#### text_500_button
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ----------------- |
|
||||
@@ -224,7 +221,7 @@ Sets the subtitle text for the full general error page.
|
||||
|
||||
Sets the button text for the full general error page.
|
||||
|
||||
### text_help_bgp_route
|
||||
#### text_help_bgp_route
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
@@ -232,7 +229,7 @@ Sets the button text for the full general error page.
|
||||
|
||||
Sets the BGP Route query help text, displayed when the **?** icon is hovered.
|
||||
|
||||
### text_help_bgp_community
|
||||
#### text_help_bgp_community
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
@@ -243,7 +240,7 @@ 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
|
||||
#### text_help_bgp_aspath
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
@@ -254,7 +251,7 @@ 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
|
||||
#### text_help_ping
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
@@ -262,7 +259,7 @@ Sets the BGP AS Path query help text, displayed when the **?** icon is hovered.
|
||||
|
||||
Sets the Ping query help text, displayed when the **?** icon is hovered.
|
||||
|
||||
### text_help_traceroute
|
||||
#### text_help_traceroute
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
@@ -273,7 +270,9 @@ 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
|
||||
# Fonts
|
||||
|
||||
#### primary_font_url
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
@@ -281,7 +280,7 @@ Sets the Traceroute query help text, displayed when the **?** icon is hovered.
|
||||
|
||||
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
|
||||
#### primary_font_name
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
@@ -289,7 +288,7 @@ Sets the web font URL for the primary font. This font is used for all titles, su
|
||||
|
||||
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
|
||||
#### mono_font_url
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
@@ -297,7 +296,7 @@ Sets the web font name for the primary font. This font is used for all titles, s
|
||||
|
||||
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
|
||||
#### mono_font_name
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
|
||||
@@ -1,83 +0,0 @@
|
||||
Commands are defined in `hyperglass/hyperglass/configuration/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)
|
||||
@@ -1,160 +1,103 @@
|
||||
Devices/routers are defined in `hyperglass/hyperglass/configuration/devices.toml`. `devices.toml` is effectively an array of hash tables/dictionaries/key value pairs:
|
||||
`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]]
|
||||
address = "10.0.0.1"
|
||||
[router.'pop1']
|
||||
address = "192.0.2.1"
|
||||
asn = "65000"
|
||||
src_addr_ipv4 = "192.0.2.1"
|
||||
src_addr_ipv4 = "192.0.2.251"
|
||||
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"
|
||||
display_name = "Washington, DC"
|
||||
port = "22"
|
||||
type = "cisco_ios"
|
||||
proxy = "jumpbox2"
|
||||
proxy = "jumpbox1"
|
||||
|
||||
[[router]]
|
||||
address = "10.0.0.3"
|
||||
[router.'pop2']
|
||||
address = "192.0.2.2"
|
||||
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"
|
||||
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 = ""
|
||||
```
|
||||
|
||||
### Device Keys
|
||||
# Credentials
|
||||
|
||||
#### address
|
||||
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).
|
||||
|
||||
IP address hyperglass will use to connect to the device.
|
||||
#### Example
|
||||
|
||||
#### asn
|
||||
```toml
|
||||
[credential.'default']
|
||||
username = "hyperglass"
|
||||
password = "secret_password"
|
||||
|
||||
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
|
||||
[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.
|
||||
|
||||
@@ -4,7 +4,7 @@ From `hyperglass/hyperglass/configuration/config.toml`:
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------- |
|
||||
| String | `"65000"` |
|
||||
| String | `"65000"` |
|
||||
|
||||
Your network's _primary_ ASN. Number only, e.g. `65000`, **not** `AS65000`.
|
||||
|
||||
@@ -12,7 +12,7 @@ Your network's _primary_ ASN. Number only, e.g. `65000`, **not** `AS65000`.
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
| Boolean | `False` |
|
||||
| Boolean | `False` |
|
||||
|
||||
Enables Flask debugging. May be used to enable other module debugs in the future.
|
||||
|
||||
@@ -26,8 +26,8 @@ Google Analytics ID number. For more information on how to set up Google Analyti
|
||||
|
||||
### message_error
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | --------------------- |
|
||||
| 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:
|
||||
@@ -45,16 +45,16 @@ Message presented to the user when invalid input is detected. `{input}` will be
|
||||
|
||||
### message_blacklist
|
||||
|
||||
| Type | Default Value |
|
||||
| ------ | ------------------------- |
|
||||
| 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 |
|
||||
| ------ | -------------------------------------------------------------------------------------------- |
|
||||
| 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).
|
||||
@@ -63,7 +63,7 @@ Message presented to the user when the [query limit](#rate_limit_query) is reach
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
| Boolean | `True` |
|
||||
| Boolean | `True` |
|
||||
|
||||
Enables or disables the BGP Route query type.
|
||||
|
||||
@@ -71,7 +71,7 @@ Enables or disables the BGP Route query type.
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
| Boolean | `True` |
|
||||
| Boolean | `True` |
|
||||
|
||||
Enables or disables the BGP Community query type.
|
||||
|
||||
@@ -79,7 +79,7 @@ Enables or disables the BGP Community query type.
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
| Boolean | `True` |
|
||||
| Boolean | `True` |
|
||||
|
||||
Enables or disables the BGP AS Path query type.
|
||||
|
||||
@@ -87,7 +87,7 @@ Enables or disables the BGP AS Path query type.
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
| Boolean | `True` |
|
||||
| Boolean | `True` |
|
||||
|
||||
Enables or disables the Ping query type.
|
||||
|
||||
@@ -95,38 +95,64 @@ Enables or disables the Ping query type.
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
| Boolean | `True` |
|
||||
| Boolean | `True` |
|
||||
|
||||
Enables or disables the Traceroute query type.
|
||||
|
||||
### rate_limit_query
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
| String | `"5"` |
|
||||
| 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"` |
|
||||
| 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` |
|
||||
| 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"` |
|
||||
| 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).
|
||||
|
||||
### enable_max_prefix
|
||||
|
||||
| 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>
|
||||
|
||||
### max_prefix_length_ipv4
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
| Integer | `24` |
|
||||
|
||||
If `enable_max_prefix` is enabled, the maxiumum prefix length allowed for IPv4 BGP Route queries.
|
||||
|
||||
### max_prefix_length_ipv6
|
||||
|
||||
| Type | Default Value |
|
||||
| ------- | ------------- |
|
||||
| Integer | `64` |
|
||||
|
||||
If `enable_max_prefix` is enabled, the maxiumum prefix length allowed for IPv6 BGP Route queries.
|
||||
|
||||
@@ -11,6 +11,98 @@ hyperglass/configuration/
|
||||
└── requires_ipv6_cidr.toml
|
||||
```
|
||||
|
||||
## `requires_ipv6_cidr.toml`
|
||||
## Blacklist
|
||||
|
||||
Blacklisted querys are defined in `hyperglass/hyperglass/configuration/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 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>
|
||||
|
||||
## Commands
|
||||
|
||||
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}"
|
||||
```
|
||||
|
||||
## IPv6 CIDR Format Required
|
||||
|
||||
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.toml` is a list (TOML array) of network operating systems that require this (in Netmiko format).
|
||||
|
||||
#### Example
|
||||
|
||||
```toml
|
||||
requires_ipv6_cidr = [
|
||||
"cisco_ios",
|
||||
"cisco_nxos"
|
||||
]
|
||||
```
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
Proxy servers are defined in `hyperglass/hyperglass/configuration/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.
|
||||
|
||||
!!! note "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`.
|
||||
@@ -1,8 +1,6 @@
|
||||
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.
|
||||
|
||||
# Creating Restricted Accounts
|
||||
|
||||
## Cisco IOS
|
||||
# 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:
|
||||
|
||||
@@ -21,7 +19,7 @@ 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
|
||||
# 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:
|
||||
|
||||
@@ -42,7 +40,7 @@ username hyperglass
|
||||
!!! 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
|
||||
# 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:
|
||||
|
||||
82
docs/extras/supported-device-types.md
Normal file
82
docs/extras/supported-device-types.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# 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
|
||||
```
|
||||
@@ -1,9 +1,11 @@
|
||||
# Download
|
||||
|
||||
## System Requirements
|
||||
#### System Requirements
|
||||
|
||||
!!! warning "Compatibility"
|
||||
To date, Hyperglass has only been installed tested on Mac OS X 10.14 and Ubuntu Linux 18.04. Installation instructions are specific to Ubuntu 18.04. Installation instructions for additional operating systems are forthcoming (contribution welcome!).
|
||||
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:
|
||||
|
||||
@@ -11,34 +13,38 @@ Hyperglass is written and tested on Python 3.7, but should be backwards compatib
|
||||
# apt install -y python3 python3-pip
|
||||
```
|
||||
|
||||
## Clone the repository
|
||||
#### Clone the repository
|
||||
|
||||
```console
|
||||
$ cd /opt/
|
||||
$ git clone https://github.com/checktheroads/hyperglass
|
||||
```
|
||||
|
||||
## Install Required Python Modules
|
||||
# Install
|
||||
|
||||
#### Python Dependencies
|
||||
|
||||
```console
|
||||
$ cd /opt/hyperglass/hyperglass
|
||||
$ cd /opt/hyperglass/
|
||||
$ pip3 install -r requirements.txt
|
||||
```
|
||||
|
||||
## Clone Example Configuration Files
|
||||
#### Migrate Configuration Files
|
||||
|
||||
```
|
||||
$ cd /opt/hyperglass/hyperglass/configuration/
|
||||
$ for f in *.example; do cp $f `basename $f .example`; done;
|
||||
```console
|
||||
$ cd /opt/hyperglass/
|
||||
$ python3 manage.py migrateconfig
|
||||
```
|
||||
|
||||
## Test the Application
|
||||
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/hyperglass/
|
||||
$ python3 app.py
|
||||
$ 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.
|
||||
|
||||
79
docs/installation/reverseproxy.md
Normal file
79
docs/installation/reverseproxy.md
Normal file
@@ -0,0 +1,79 @@
|
||||
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
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80ipv6only=on;
|
||||
|
||||
client_max_body_size 1024;
|
||||
|
||||
server_name lg.domain.tld;
|
||||
|
||||
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
|
||||
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 /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/)
|
||||
26
docs/installation/systemd.md
Normal file
26
docs/installation/systemd.md
Normal file
@@ -0,0 +1,26 @@
|
||||
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
|
||||
```
|
||||
@@ -6,45 +6,38 @@ Gunicorn is a WSGI server written in Python.
|
||||
|
||||
## Install
|
||||
```console
|
||||
# pip3 install gunicorn
|
||||
$ pip3 install gunicorn
|
||||
```
|
||||
|
||||
## Configure
|
||||
|
||||
Locate your `gunicorn` executable with `which gunicorn`.
|
||||
Migrate the example Gunicorn configuration file:
|
||||
```console
|
||||
$ cd /opt/hyperglass/
|
||||
$ python3 manage.py migrategunicorn
|
||||
```
|
||||
|
||||
Open `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:
|
||||
|
||||
```python
|
||||
import multiprocessing
|
||||
|
||||
command = "/usr/local/bin/gunicorn"
|
||||
pythonpath = "/opt/hyperglass/hyperglass"
|
||||
bind = "[::1]:8001"
|
||||
workers = multiprocessing.cpu_count() * 2
|
||||
user = "www-data"
|
||||
timeout = 60
|
||||
```
|
||||
|
||||
### 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:
|
||||
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
|
||||
# chown -R www-data:www-data /opt/hyperglass/hyperglass
|
||||
# chmod -R 744 /opt/hyperglass/hyperglass
|
||||
# cd /opt/hyperglass/
|
||||
# python3 manage.py fixpermissions --user <user> --group <group>
|
||||
```
|
||||
|
||||
<!-- # Supervisor Installation
|
||||
|
||||
To make cross-platform service functionality easier, it is recommended to use [`supervisord`](http://supervisord.org/) to manage the Hyperglass application. If you prefer, `systemd` or your service manager of choice may be used.
|
||||
|
||||
Install supervisord:
|
||||
|
||||
```console
|
||||
# apt install -y supervisor
|
||||
```
|
||||
|
||||
Create supervisord configuration for Hyperglass:
|
||||
|
||||
```console
|
||||
# nano /etc/supervisor/conf.d/hyperglass.conf
|
||||
[program:hyperglass]
|
||||
command = /usr/local/bin/gunicorn -c /opt/hyperglass/hyperglass/gunicorn_config.py hyperglass.wsgi
|
||||
directory = /opt/hyperglass/
|
||||
user = www-data
|
||||
```
|
||||
|
||||
Start supervisord:
|
||||
|
||||
```console
|
||||
# systemctl start supervisor
|
||||
# systemctl status supervisor
|
||||
``` -->
|
||||
!!! note "File Ownership"
|
||||
If the `--user` and `--group` options are not specified, `www-data` will be used.
|
||||
|
||||
BIN
docs/max_prefix_error.png
Normal file
BIN
docs/max_prefix_error.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
BIN
docs/ping_traceroute_cidr.png
Normal file
BIN
docs/ping_traceroute_cidr.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
BIN
docs/requires_ipv6_cidr.png
Normal file
BIN
docs/requires_ipv6_cidr.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Reference in New Issue
Block a user