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

docs updates for beta-22

Browse Source
This commit is contained in:
checktheroads
2020-04-15 11:17:16 -07:00
parent 183248e703
commit 939e4da3f3
6 changed files with 104 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/docs/cache.mdx
View File

@@ -12,13 +12,13 @@ hyperglass uses [Redis](https://redis.io/) for cache storage. Every query is cac
Common Redis parameters are configurable, in case you already have a dedicated Redis server you'd prefer to use, instead of running it on the same server as hyperglass:
| Parameter | Type | Default | Description |
| :---------- | :-----: | :------------ | :--------------------------------------------------------------------------- |
| `host` | String | `'localhost'` | Redis server IP address or hostname. |
| `port` | Integer | `6379` | Redis server TCP port. |
| `database` | Integer | `0` | Database ID for hyperglass. |
| `timeout` | Integer | `120` | Time in seconds query output will be kept in the Redis cache. |
| `show_text` | Boolean | `true` | Show the <Link to="/docs/ui#text">cache message</Link> in the hyperglass UI. |
| Parameter | Type | Default | Description |
| :---------- | :-----: | :------------ | :------------------------------------------------------------ |
| `host` | String | `'localhost'` | Redis server IP address or hostname. |
| `port` | Integer | `6379` | Redis server TCP port. |
| `database` | Integer | `1` | Database ID for hyperglass. |
| `timeout` | Integer | `120` | Time in seconds query output will be kept in the Redis cache. |
| `show_text` | Boolean | `true` | Show the [cache message](ui.mdx#text) in the hyperglass UI. |
:::important Caching
hyperglass caches every query response to a Redis database, and always responds to a request with the cached value. If hyperglass receives a query for which it has no matching cached entry, the query parameters are used to created a new cache entry, hyperglass executes the request normally, writes the response to the cache, and then returns the response to the end user.

4
docs/docs/configuration.mdx
View File

@@ -50,10 +50,9 @@ The following global settings can be set in `hyperglass.yaml`:
| `site_title` | String | `'hyperglass'` | The name of your hyperglass site. This field is used in the UI & API documentation to set fields such as the `<title/>` HTML tag, and the terms & conditions footer component. |
| `site_description` | String | `'{org_name} Network Looking Glass'` | A short description of your hyperglass site. This field is used in th UI & API documentation to set the `<meta name="description"/>` tag. `{org_name}` may be used to insert the value of the `org_name` field. |
| `site_keywords` | List | | Keywords pertaining to your hyperglass site. This field is used to generate `<meta name="keywords"/>` HTML tags, which helps tremendously with [SEO](https://support.google.com/webmasters/answer/7451184). |
| `request_timeout` | Integer | `30` | Global timeout in seconds for all requests. The UI uses this field's exact value when submitting queries. The backend uses this field's value, minus one second, for its own timeout handling. This is to ensure a contextual timeout error is presented to the end user in the event of a backend application timeout. |
| `request_timeout` | Integer | `90` | Global timeout in seconds for all requests. The UI uses this field's exact value when submitting queries. The backend uses this field's value, minus one second, for its own timeout handling. This is to ensure a contextual timeout error is presented to the end user in the event of a backend application timeout. |
| `listen_address` | String | `'localhost'` | Local IPv4/IPv6 Address the hyperglass application listens on to serve web traffic. |
| `listen_port` | Integer | `8001` | Local TCP port the hyperglass application listens on to serve web traffic. |
| `log_directory` | String | | Path to a directory, to which hyperglass can write logs. If none is set, hyperglass will write logs to a file located at `/tmp/`, with a uniquely generated name for each time hyperglass is started. |
| `cors_origins` | List | `[]` | Allowed [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) hosts. By default, no CORS hosts are allowed. |
| `netmiko_delay_factor` | Integer \| Float | `0.1` | Override the [Netmiko global delay factor](https://ktbyers.github.io/netmiko/docs/netmiko/index.html). |
@@ -85,6 +84,7 @@ From the top level, the following subsections may be defined and configured:
| :--------- | :-------------------------------------------------- | :-----------------------------------------: |
| `cache` | Redis server & cache timeout settings. | <PageLink to="/docs/cache">➡️</PageLink> |
| `docs` | API documentation settings. | <PageLink to="/docs/api">➡️</PageLink> |
| `logging` | File, syslog, and webhook settings. | <PageLink to="/docs/logging">➡️</PageLink> |
| `messages` | Customize almost all user-facing UI & API messages. | <PageLink to="/docs/messages">➡️</PageLink> |
| `queries` | Enable, disable, or configure query types. | <PageLink to="/docs/queries">➡️</PageLink> |
| `web` | Web UI & branding settings. | <PageLink to="/docs/ui">➡️</PageLink> |

4
docs/docs/devices.mdx
View File

@@ -1,7 +1,7 @@
---
id: devices
title: Adding Devices
sidebar_label: Adding Devices
title: Devices
sidebar_label: Devices
keywords: [hyperglass, authentication, ssl, proxy, access list, prefix list, acl, help]
description: Adding devices to hyperglass
---

89
docs/docs/logging.mdx Normal file
View File

@@ -0,0 +1,89 @@
---
id: logging
title: Logging
sidebar_label: Logging
keywords: [hyperglass, logging, webhook, hooks, syslog]
description: hyperglass Logging
---
hyperglass supports multiple types of logging, for both application troubleshooting and general reporting.
## File Logging
By default, hyperglass writes all log messages to a log file located at `/tmp/hyperglass.log`. This behavior and other file logging parameters may be overridden if needed:
| Parameter | Type | Default | Description |
| :---------- | :----: | :------- | :------------------------------------------------- |
| `directory` | String | `'/tmp'` | Valid directory where the log file can be written. |
| `format` | String | `'text'` | Log format - may be either `'text'` or `'json'`. |
| `max_size` | String | `'50MB'` | Maximum log file size before logs are rotated. |
The `logging` subsection contains additional subsections of its own for configuring other logging methods:
| Section | Description | All Options |
| :------- | :-------------------- | :------------------------------------: |
| `syslog` | Syslog settings | <PageLink to="#syslog">➡️</PageLink> |
| `http` | HTTP webhook settings | <PageLink to="#webhooks">➡️</PageLink> |
:::note
You do not have to set `enable: false` to disable syslogging or webhooks - if there is no configuration under the `syslog` or `http` subsections, it the option is disabled by default. The `enable` option exists for easy toggling without having to delete the other settings.
:::
## Syslog
If syslogging is enabled, all of the same log messages written to the file and/or stdout will be forwarded to the syslog server.
| Parameter | Type | Default | Description |
| :-------- | :-----: | :------ | :------------------------------------------------ |
| `enable` | Boolean | `true` | Optionally disable syslogging even if configured. |
| `host` | String | | Syslog target IP address or hostname. |
| `port` | Integer | `514` | Syslog target UDP port number. |
## Webhooks
If http logging is enabled, an HTTP POST will be sent to the configured target every time a query is submitted, _after_ it is validated.
| Parameter | Type | Default | Description |
| :----------- | :-----: | :------ | :-------------------------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Optionally disable webhooks even if configured. |
| `host` | String | | HTTP URL to webhook target. |
| `headers` | Mapping | | Any arbitrary mappings, which will be sent as HTTP headers. |
| `params` | Mapping | | Any arbitrary mappings, which will be sent as URL parameters (e.g. `http://example.com/log?param=value`). |
| `verify_ssl` | Boolean | `true` | Verify SSL certificate of target. |
| `timeout` | Integer | `5` | Time in seconds before request times out. |
### Authentication
Basic and API key authentication are supported.
| Parameter | Type | Default | Description |
| :--------- | :----: | :-------- | :------------------------------------------------------------------------ |
| `mode` | String | `'basic'` | Authentication mode. Must be `'basic'` or `'api_key'` |
| `username` | String | | Username for basic authentication. |
| `password` | String | | Password for basic authentication, or API Key for API key authentication. |
:::important
If `api_key` is used, the header `X-API-Key: {key}` is added to the request, where `{key}` is the password.
:::
## Full example
```yaml
logging:
directory: /var/log
format: json
max_size: 10 MB
syslog:
host: syslog.example.com
http:
host: "https://example.com/logs"
authentication:
mode: basic
username: your username
password: your password
headers:
X-Special-Header: your header value
params:
app: hyperglass # URL would be https://example.com/logs?app=hyperglass
verify_ssl: false
```

2
docs/docs/ui.mdx
View File

@@ -156,7 +156,7 @@ By default, no Opengraph image is set. If you define one with `image`, hyperglas
| `query_target` | String | `'Target'` | Query Target (IP/hostname/community/AS Path) form label. |
| `query_type` | String | `'Query Type'` | Query Type (BGP Route, Ping, Traceroute, etc.) form label. |
| `query_vrf` | String | `'Routing Table'` | Query VRF form label. |
| `subtitle` | String | `'AS{primary_asn}'` | Subtitle text. `{primary_asn}` will be replaced with the <PageLink to="/docs/configuration#global-settings"><Code>primary_asn</Code></PageLink> value. |
| `subtitle` | String | `'Network Looking Glass'` | Subtitle text. value. |
| `title` | String | `'hyperglass'` | Title text. |
| `title_mode` | String | `'text_only'` | Set the title mode. <MiniNote>Must be <Code>text_only</Code>, <Code>logo_only</Code>, <Code>logo_subtitle</Code>, or <Code>all</Code></MiniNote> |

5
docs/sidebars.js
View File

@@ -10,13 +10,14 @@ module.exports = {
label: "Configuration",
items: [
"configuration",
"queries",
"logging",
"cache",
"devices",
"commands",
"ui",
"cache",
"api",
"messages",
"queries",
],
},
{ type: "category", label: "Linux Agent", items: ["agent/installation"] },