diff --git a/docs/components/color.tsx b/docs/components/color.tsx index 480a9a0..0234cba 100644 --- a/docs/components/color.tsx +++ b/docs/components/color.tsx @@ -1,30 +1,29 @@ type ColorProps = { - hex: string; - noText?: boolean; + hex: string; + noText?: boolean; }; export const Color = (props: ColorProps) => { - const { hex, noText = false } = props; - console.log(props); - return ( - - - {noText ? '' : hex} - - - ); + const { hex, noText = false } = props; + return ( + + + {noText ? "" : hex} + + + ); }; diff --git a/docs/components/docs-button.tsx b/docs/components/docs-button.tsx new file mode 100644 index 0000000..c06c177 --- /dev/null +++ b/docs/components/docs-button.tsx @@ -0,0 +1,36 @@ +import NextLink from "next/link"; +import { Button } from "nextra/components"; + +const DocsIcon = () => ( + + Docs + + +); + +export interface DocsButtonProps extends React.ComponentProps<"button"> { + href: string; + side?: "left" | "right"; +} + +export const DocsButton = (props: DocsButtonProps) => { + const { href, side = "left", ...rest } = props; + return ( + + + + ); +}; diff --git a/docs/components/not-supported-icon.tsx b/docs/components/not-supported-icon.tsx new file mode 100644 index 0000000..5176aa2 --- /dev/null +++ b/docs/components/not-supported-icon.tsx @@ -0,0 +1,14 @@ +export const NotSupported = (props: React.ComponentProps<"svg">) => ( + + Not Supported + + + +); diff --git a/docs/components/platforms.tsx b/docs/components/platforms.tsx new file mode 100644 index 0000000..dda7d70 --- /dev/null +++ b/docs/components/platforms.tsx @@ -0,0 +1,44 @@ +import { Code, Table, Td, Th, Tr } from "nextra/components"; +import platforms from "~/platforms.json"; +import { NotSupported } from "./not-supported-icon"; +import { Supported } from "./supported-icon"; + +export const SupportedPlatforms = () => ( + +); + +export const PlatformTable = () => ( + + + + + + + {platforms.map((spec) => ( + + + + + ))} + +
Platform KeysNatively Supported
+ {spec.keys.map((key) => ( + + {key} + + ))} + {spec.native ? : }
+); diff --git a/docs/components/supported-icon.tsx b/docs/components/supported-icon.tsx new file mode 100644 index 0000000..f053c38 --- /dev/null +++ b/docs/components/supported-icon.tsx @@ -0,0 +1,13 @@ +export const Supported = (props: React.ComponentProps<"svg">) => ( + + Supported + + +); diff --git a/docs/pages/configuration/_meta.json b/docs/pages/configuration/_meta.json index 502e513..e40165b 100644 --- a/docs/pages/configuration/_meta.json +++ b/docs/pages/configuration/_meta.json @@ -1,4 +1,5 @@ { + "overview": "Overview", "config": "Config File", "devices": "Devices File", "directives": "Directives File", diff --git a/docs/pages/configuration/config.mdx b/docs/pages/configuration/config.mdx index 15209c2..85262af 100644 --- a/docs/pages/configuration/config.mdx +++ b/docs/pages/configuration/config.mdx @@ -1,8 +1,11 @@ +--- +title: Configuration File +description: hyperglass config.yaml file reference +--- + The `config.yaml` file is broken into multiple sections: -# Global - -Top level parameters: +## Top Level Parameters | Parameter | Type | Default Value | Description | | :----------------- | :-------------- | :------------------------------- | :------------------------------------------------------------ | @@ -24,171 +27,18 @@ site_description: Beloved Hyperglass User Network Looking Glass site_title: Beloved Hyperglass User ``` -## Cache +## Other Configuration Sections -hyperglass relies on [Redis](https://redis.io/) as an in-memory key/value store for configuration management and request/response caching. If Redis is already [installed](/installation) on your system, you should only need to set these parameters if you need to customize how hyperglass connects to Redis. +| Parameter | Docs | Description | +| :----------- | :--------------------------------------------------------------------- | :--------------------------------------------------------------- | +| `cache` | [Caching Docs](/configuration/config/caching.mdx) | Customize how hyperglass caches responses. | +| `logging` | [Logging Docs](/configuration/config/logging.mdx) | Customize file logging, syslog, webhooks, etc. | +| `messages` | [Messages Docs](/configuration/config/messages.mdx) | Customize messages shown to users. | +| `structured` | [Structured Output Docs](/configuration/config/structured-ouptput.mdx) | Customize how hyperglass handles structured output from devices. | +| `web` | [Web UI Docs](/configuration/config/web-ui.mdx) | Customize the look and feel of hyperglass's web UI. | -| Parameter | Type | Default Value | Description | -| :--------------- | :----- | :------------ | :----------------------------- | -| `cache.host` | String | localhost | Redis IP address or hostname. | -| `cache.port` | Number | 6379 | Redis TCP port. | -| `cache.database` | Number | 1 | Redis database number (0-15). | -| `cache.password` | String | | Redis password, if one is set. | +## Caveats -#### Example with Defaults - -```yaml filename="config.yaml" -cache: - host: localhost - port: 6379 - database: 1 - password: null -``` - -## Docs - -Behind the scenes, hyperglass uses [FastAPI](https://fastapi.tiangolo.com/), which automatically generates documentation for the hyperglass REST API. The `docs` section allows users to customize the look, feel, and text used for the REST API documentation. - -| Parameter | Type | Default Value | Description | -| :----------------- | :------ | :----------------------------- | :---------------------------------------------------------------------------------------------- | -| `docs.base_url` | String | https://lg.example.com | Used for REST API samples. See the [demo](https://demo.hyperglass.dev/api/docs) for an example. | -| `docs.enable` | Boolean | `true` | Enable or disable the REST API documentation. | -| `docs.mode` | String | redoc | FastAPI supports two UI libraries/themes for autogenerated docs: `redoc` and `swagger`. | -| `docs.path` | String | /api/docs | Path to the REST API documentation. | -| `docs.title` | String | `site_title` API Documentation | API docs title. Uses the `site_title` parameter from the [global](#global) parameters. | -| `docs.description` | String | | API docs description. Appears below the title. | - -The documentation for API endpoints follow a common schema: - -- `devices` -- `info` -- `queries` -- `query` - -### Schema - -| Parameter | Type | Description | -| :------------ | :----- | :------------------------------------------------------------------------------- | -| `title` | String | API endpoint title, displayed as the header text above the API endpoint section. | -| `description` | String | API endpoint description, displayed inside each API endpoint section. | -| `summary` | String | API endpoint summary, displayed beside the API endpoint path. | - -### Parameters - -| Parameter | Default Value | -| :------------------------- | :------------------------------------------------------------------------------------------ | -| `docs.devices.title` | Devices | -| `docs.devices.description` | List of all devices/locations with associated identifiers, display names, networks, & VRFs. | -| `docs.devices.summary` | Devices List | -| `docs.info.title` | System Information | -| `docs.info.description` | General information about this looking glass. | -| `docs.info.summary` | System Information | -| `docs.queries.title` | Supported Queries | -| `docs.queries.description` | List of supported query types. | -| `docs.queries.summary` | Query Types | -| `docs.query.title` | Supported Query | -| `docs.query.description` | Request a query response per-location. | -| `docs.query.summary` | Query the Looking Glass | - -#### Example with Defaults - -```yaml filename="config.yaml" -docs: - base_url: https://lg.example.com - enable: true - mode: redoc - path: /api/docs - title: Beloved Hyperglass User Looking Glass API Documentation - description: null - # API Endpoints ↓ - devices: - title: Devices - description: List of all devices/locations with associated identifiers, display names, networks, & VRFs. - summary: Devices List - info: - title: System Information - description: General information about this looking glass. - summary: System Information - queries: - title: Supported Queries - description: List of supported query types. - summary: Query Types - query: - title: Supported Query - description: Request a query response per-location. - summary: Query the Looking Glass -``` - -## Messages - -hyperglass provides as much control over user-facing text/messages as possible. The following messages may be adjusted as needed: - -| Parameter | Type | Default Value | Description | -| :------------------------------ | :----- | :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `messages.authentication_error` | String | Authentication error occurred. | Displayed when hyperglass is unable to authenticate to a device. Usually, this indicates a configuration error. | -| `messages.connection_error` | String | Error connecting to \{device_name\}: \{error\} | Displayed when hyperglass is unable to connect to a device. Usually, this indicates a configuration error. `{device_name}` and `{error}` will be used to display the device in question and the specific connection error. | -| `messages.general` | String | Something went wrong. | Displayed when errors occur that hyperglass didn't anticipate or handle correctly. Seeing this error message may indicate a bug in hyperglass. If you see this in the wild, try enabling [debug mode](#global) and review the logs to pinpoint the source of the error. | -| `messages.invalid_input` | String | \{target\} is not valid. | Displayed when a query target's value is invalid in relation to the corresponding query type. `{target}` will be used to display the invalid target. | -| `messages.invalid_query` | String | \{target\} is not a valid \{query_type\} target. | Displayed when a query target's value is invalid in relation to the corresponding query type. `{target}` and `{query_type}` may be used to display the invalid target and corresponding query type. | -| `messages.no_input` | String | \{field\} must be specified. | Displayed when a required field is not specified. `{field}` will be used to display the name of the field that was omitted. | -| `messages.no_output` | String | The query completed, but no matching results were found. | Displayed when hyperglass can connect to a device and execute a query, but the response is empty. | -| `messages.not_found` | String | \{type\} '\{name\}' not found. | Displayed when an object property does not exist in the configuration. `{type}` corresponds to a user-friendly name of the object type (for example, 'Device'), `{name}` corresponds to the object name that was not found. | -| `messages.request_timeout` | String | Request timed out. | Displayed when the [`request_timeout`](#global) time expires. | -| `messages.target_not_allowed` | String | \{target\} is not allowed. | Displayed when a query target is implicitly denied by a configured rule. `{target}` will be used to display the denied query target. | - -##### Example - -```yaml filename="config.yaml" -message: - general: Something with wrong. -``` - -## Structured - -Devices that support responding to a query with structured or easily parsable data can have their response data placed into an easier to read table (or JSON, when using the REST API). Currently, the following platforms have structured data supported in hyperglass: - -- Juniper Junos -- Arista EOS - -When structured output is available, hyperglass checks the RPKI state of each BGP prefix returned using one of two methods: - -1. From the router's perspective -2. From the perspective of [Cloudflare's RPKI Service](https://rpki.cloudflare.com/) - -Additionally, hyperglass provides the ability to control which BGP communities are shown to the end user. - -| Parameter | Type | Default Value | Description | -| :----------------------------- | :-------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------- | -| `structured.rpki` | String | router | Use `router` to use the router's view of the RPKI state (1 above), or `external` to use Cloudflare's view (2 above). | -| `structured.communities.mode` | String | deny | Use `deny` to deny any communities listed in `structured.communities.items`, or `permit` to _only_ permit communities listed. | -| `structured.communities.items` | List of Strings | | List of communities to match. | - -#### Community Filtering Examples - -##### Deny Listed Communities by Regex pattern - -```yaml filename="config.yaml" {5-6} -structured: - communities: - mode: deny - items: - - '^65000:1\d+$' # don't show any communities starting with 65000:1. 65000:1234 would be denied, but 65000:4321 would be permitted. - - "65000:2345" # don't show the 65000:2345 community. -``` - -##### Permit only Listed Communities - -```yaml filename="config.yaml" {5-6} -structured: - communities: - mode: permit - items: - - "^65000:.*$" # permit any communities starting with 65000, but no others. - - "1234:1" # permit only the 1234:1 community. -``` - -### Caveats - -#### Arista EOS +### Arista EOS For whatever reason, the tested version of Arista EOS does not supply certain details about routes in its JSON output when running commands `show ip bgp regex ` or `show ip bgp community `. Specifically, the the route's timestamp and any attached communities are not supplied. When these commands are used with Arista EOS, hyperglass sets the timestamp to the current time, and the community to an empty list. diff --git a/docs/pages/configuration/config/_meta.json b/docs/pages/configuration/config/_meta.json index 8124e7b..2c2561d 100644 --- a/docs/pages/configuration/config/_meta.json +++ b/docs/pages/configuration/config/_meta.json @@ -1,4 +1,8 @@ { + "api-docs": "API Docs", + "caching": "Caching", "logging": "Logging & Webhooks", + "messages": "Messages", + "structured-output": "Structured Output", "web-ui": "Web UI" } diff --git a/docs/pages/configuration/config/api-docs.mdx b/docs/pages/configuration/config/api-docs.mdx new file mode 100644 index 0000000..4122045 --- /dev/null +++ b/docs/pages/configuration/config/api-docs.mdx @@ -0,0 +1,73 @@ +## API Docs + +Behind the scenes, hyperglass uses [FastAPI](https://fastapi.tiangolo.com/), which automatically generates documentation for the hyperglass REST API. The `docs` section allows users to customize the look, feel, and text used for the REST API documentation. + +| Parameter | Type | Default Value | Description | +| :----------------- | :------ | :----------------------------- | :---------------------------------------------------------------------------------------------- | +| `docs.base_url` | String | https://lg.example.com | Used for REST API samples. See the [demo](https://demo.hyperglass.dev/api/docs) for an example. | +| `docs.enable` | Boolean | `true` | Enable or disable the REST API documentation. | +| `docs.mode` | String | redoc | FastAPI supports two UI libraries/themes for autogenerated docs: `redoc` and `swagger`. | +| `docs.path` | String | /api/docs | Path to the REST API documentation. | +| `docs.title` | String | `site_title` API Documentation | API docs title. Uses the `site_title` parameter from the [global](#global) parameters. | +| `docs.description` | String | | API docs description. Appears below the title. | + +The documentation for API endpoints follow a common schema: + +- `devices` +- `info` +- `queries` +- `query` + +### Schema + +| Parameter | Type | Description | +| :------------ | :----- | :------------------------------------------------------------------------------- | +| `title` | String | API endpoint title, displayed as the header text above the API endpoint section. | +| `description` | String | API endpoint description, displayed inside each API endpoint section. | +| `summary` | String | API endpoint summary, displayed beside the API endpoint path. | + +### Parameters + +| Parameter | Default Value | +| :------------------------- | :------------------------------------------------------------------------------------------ | +| `docs.devices.title` | Devices | +| `docs.devices.description` | List of all devices/locations with associated identifiers, display names, networks, & VRFs. | +| `docs.devices.summary` | Devices List | +| `docs.info.title` | System Information | +| `docs.info.description` | General information about this looking glass. | +| `docs.info.summary` | System Information | +| `docs.queries.title` | Supported Queries | +| `docs.queries.description` | List of supported query types. | +| `docs.queries.summary` | Query Types | +| `docs.query.title` | Supported Query | +| `docs.query.description` | Request a query response per-location. | +| `docs.query.summary` | Query the Looking Glass | + +#### Example with Defaults + +```yaml filename="config.yaml" +docs: + base_url: https://lg.example.com + enable: true + mode: redoc + path: /api/docs + title: Beloved Hyperglass User Looking Glass API Documentation + description: null + # API Endpoints ↓ + devices: + title: Devices + description: List of all devices/locations with associated identifiers, display names, networks, & VRFs. + summary: Devices List + info: + title: System Information + description: General information about this looking glass. + summary: System Information + queries: + title: Supported Queries + description: List of supported query types. + summary: Query Types + query: + title: Supported Query + description: Request a query response per-location. + summary: Query the Looking Glass +``` diff --git a/docs/pages/configuration/config/caching.mdx b/docs/pages/configuration/config/caching.mdx new file mode 100644 index 0000000..839b8e1 --- /dev/null +++ b/docs/pages/configuration/config/caching.mdx @@ -0,0 +1,16 @@ +## Cache + +hyperglass automatically caches responses to reduce the number of times devices are queried for the same information. + +| Parameter | Type | Default Value | Description | +| :---------------- | :------ | :------------ | :------------------------------------------------------------------------------ | +| `cache.timeout` | Number | 120 | Number of seconds for which to cache device responses. | +| `cache.show_text` | Boolean | True | If true, an indication that a user is viewing cached information will be shown. | + +### Example with Defaults + +```yaml filename="config.yaml" +cache: + timeout: 120 + show_text: true +``` diff --git a/docs/pages/configuration/config/messages.mdx b/docs/pages/configuration/config/messages.mdx new file mode 100644 index 0000000..135a788 --- /dev/null +++ b/docs/pages/configuration/config/messages.mdx @@ -0,0 +1,23 @@ +## Message Customization + +hyperglass provides as much control over user-facing text/messages as possible. The following messages may be adjusted as needed: + +| Parameter | Type | Default Value | Description | +| :------------------------------ | :----- | :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `messages.authentication_error` | String | Authentication error occurred. | Displayed when hyperglass is unable to authenticate to a device. Usually, this indicates a configuration error. | +| `messages.connection_error` | String | Error connecting to \{device_name\}: \{error\} | Displayed when hyperglass is unable to connect to a device. Usually, this indicates a configuration error. `{device_name}` and `{error}` will be used to display the device in question and the specific connection error. | +| `messages.general` | String | Something went wrong. | Displayed when errors occur that hyperglass didn't anticipate or handle correctly. Seeing this error message may indicate a bug in hyperglass. If you see this in the wild, try enabling [debug mode](#global) and review the logs to pinpoint the source of the error. | +| `messages.invalid_input` | String | \{target\} is not valid. | Displayed when a query target's value is invalid in relation to the corresponding query type. `{target}` will be used to display the invalid target. | +| `messages.invalid_query` | String | \{target\} is not a valid \{query_type\} target. | Displayed when a query target's value is invalid in relation to the corresponding query type. `{target}` and `{query_type}` may be used to display the invalid target and corresponding query type. | +| `messages.no_input` | String | \{field\} must be specified. | Displayed when a required field is not specified. `{field}` will be used to display the name of the field that was omitted. | +| `messages.no_output` | String | The query completed, but no matching results were found. | Displayed when hyperglass can connect to a device and execute a query, but the response is empty. | +| `messages.not_found` | String | \{type\} '\{name\}' not found. | Displayed when an object property does not exist in the configuration. `{type}` corresponds to a user-friendly name of the object type (for example, 'Device'), `{name}` corresponds to the object name that was not found. | +| `messages.request_timeout` | String | Request timed out. | Displayed when the [`request_timeout`](#global) time expires. | +| `messages.target_not_allowed` | String | \{target\} is not allowed. | Displayed when a query target is implicitly denied by a configured rule. `{target}` will be used to display the denied query target. | + +##### Example + +```yaml filename="config.yaml" +message: + general: Something with wrong. +``` diff --git a/docs/pages/configuration/config/structured-output.mdx b/docs/pages/configuration/config/structured-output.mdx new file mode 100644 index 0000000..ca9757c --- /dev/null +++ b/docs/pages/configuration/config/structured-output.mdx @@ -0,0 +1,59 @@ +## Structured + +Devices that support responding to a query with structured or easily parsable data can have their response data placed into an easier to read table (or JSON, when using the REST API). Currently, the following platforms have structured data supported in hyperglass: + +- Arista EOS +- Juniper Junos + +When structured output is available, hyperglass checks the RPKI state of each BGP prefix returned using one of two methods: + +1. From the router's perspective +2. From the perspective of [Cloudflare's RPKI Service](https://rpki.cloudflare.com/) + +Additionally, hyperglass provides the ability to control which BGP communities are shown to the end user. + +| Parameter | Type | Default Value | Description | +| :----------------------------- | :-------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------- | +| `structured.rpki` | String | router | Use `router` to use the router's view of the RPKI state (1 above), or `external` to use Cloudflare's view (2 above). | +| `structured.communities.mode` | String | deny | Use `deny` to deny any communities listed in `structured.communities.items`, or `permit` to _only_ permit communities listed. | +| `structured.communities.items` | List of Strings | | List of communities to match. | + +### RPKI Examples + +#### Show RPKI State from the Device's Perspective + +```yaml filename="config.yaml" copy {2} +structured: + rpki: router +``` + +#### Show RPKI State from a Public/External Perspective + +```yaml filename="config.yaml" copy {2} +structured: + rpki: external +``` + +### Community Filtering Examples + +#### Deny Listed Communities by Regex pattern + +```yaml filename="config.yaml" {5-6} +structured: + communities: + mode: deny + items: + - '^65000:1\d+$' # don't show any communities starting with 65000:1. 65000:1234 would be denied, but 65000:4321 would be permitted. + - "65000:2345" # don't show the 65000:2345 community. +``` + +#### Permit only Listed Communities + +```yaml filename="config.yaml" {5-6} +structured: + communities: + mode: permit + items: + - "^65000:.*$" # permit any communities starting with 65000, but no others. + - "1234:1" # permit only the 1234:1 community. +``` diff --git a/docs/pages/configuration/devices.mdx b/docs/pages/configuration/devices.mdx index df1c40e..6b6b525 100644 --- a/docs/pages/configuration/devices.mdx +++ b/docs/pages/configuration/devices.mdx @@ -1,63 +1,64 @@ +import { Callout } from "nextra-theme-docs"; +import { SupportedPlatforms } from "~/components/platforms"; +import { DocsButton } from "~/components/docs-button"; + +## Device Configuration Parameters + Each configured device may have the following parameters: -| Parameter | Type | Default Value | Description | -| :------------------ | :-------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | String | | Display name of the device. | -| `description` | String | | Description of the device, displayed as a subtle label. | -| `avatar` | String | | Path to an avatar/logo image for this site. Used when [`web.location_display_mode`](configuration/config/web-ui.mdx) is set to `gallery`. | -| `address` | String | | IPv4 address, IPv6 address, or hostname of the device. | -| `group` | String | | Group name, used to visually group devices in the UI. | -| `port` | Number | | TCP port on which to connect to the device. | -| `platform` | String | | Device platform/OS. Must be a [supported platform](platforms.mdx). | -| `structured_output` | Boolean | `true` | Disable structured output for a device that supports it. | -| `directives` | List of Strings | | Enable referenced directives configured in the [directives config file](configuration/directives.mdx). | -| `driver` | String | netmiko | Specify which driver to use for this device. Currently, only `netmiko` is supported. | -| `driver_config` | Mapping | | Mapping/dict of options to pass to the connection driver. | -| `attrs` | Mapping | | Mapping/dict of variables, as referenced in configured directives. | -| `credential` | Mapping | | Mapping/dict of a [credential configuration](#credential-onfiguration). | -| `http` | Mapping | | Mapping/dict of HTTP client options, if this device is connected via HTTP. | -| `proxy` | Mapping | | Mapping/dict of SSH proxy to use for this device's requests. | +| Parameter | Type | Default Value | Description | +| :------------------ | :-------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | String | | Display name of the device. | +| `description` | String | | Description of the device, displayed as a subtle label. | +| `avatar` | String | | Path to an avatar/logo image for this site. Used when [`web.location_display_mode`](/configuration/config/web-ui.mdx) is set to `gallery`. | +| `address` | String | | IPv4 address, IPv6 address, or hostname of the device. | +| `group` | String | | Group name, used to visually group devices in the UI. | +| `port` | Number | | TCP port on which to connect to the device. | +| `platform` | String | | Device platform/OS. Must be a [supported platform](/platforms.mdx). | +| `structured_output` | Boolean | True | Disable structured output for a device that supports it. | +| `directives` | List of Strings | | Enable referenced directives configured in the [directives config file](/configuration/directives.mdx). | +| `driver` | String | netmiko | Specify which driver to use for this device. Currently, only `netmiko` is supported. | +| `driver_config` | Mapping | | Mapping/dict of options to pass to the connection driver. | +| `attrs` | Mapping | | Mapping/dict of variables, as referenced in configured directives. | +| `credential` | Mapping | | Mapping/dict of a [credential configuration](/configuration/devices/credentials.mdx). | +| `http` | Mapping | | Mapping/dict of [HTTP client options](/configuration/devices/http-device.mdx), if this device is connected via HTTP. | +| `proxy` | Mapping | | Mapping/dict of [SSH proxy config](/configuration/devices/ssh-proxy.mdx) to use for this device's requests. | -## Credential Configuration + -| Parameter | Type | Default Value | Description | -| :-------------------- | :----- | :------------ | :----------------------------------------------------- | -| `credential.username` | String | | Username to use for authentication to the device. | -| `credential.password` | String | | Password to use for authentication to the device. | -| `credential.key` | String | | Path to SSH key used for authentication to the device. | +hyperglass ships with predefined [directives](/configuration/directives.mdx) (commands) for the following [platforms](platforms.mdx): -## SSH Proxy Configuration + -| Parameter | Type | Default Value | Description | -| :----------------- | :------ | :------------ | :---------------------------------------------------------------------- | -| `proxy.address` | String | | IPv4 address, IPv6 address, or hostname of SSH proxy. | -| `proxy.port` | Number | 22 | TCP port to use for connecting to the SSH proxy. | -| `proxy.platform` | String | linux_ssh | Currently, only `linux_ssh` is supported. | -| `proxy.credential` | Mapping | | Mapping/dict of a [credential configuration](#credential-onfiguration). | +All built in directives require that the following `attrs` be defined on each device using the directive: -## HTTP Configuration +| Attribute | Value | +| :-------- | :-------------------------------------------------------- | +| `source4` | IPv4 address used to source Ping and Traceroute commands. | +| `source6` | IPv6 address used to source Ping and Traceroute commands. | -| Parameter | Type | Default Value | Description | -| :---------------------- | :------ | :------------ | :--------------------------------------------------------------------------------------------------------------------- | -| `http.attribute_map` | Mapping | | Mapping/dict of hyperglass query fields as keys, and hyperglass query field replacements as values. | -| `http.basic_auth` | Mapping | | If basic authentication is required, provide a mapping/dict containing the basic authentication username and password. | -| `http.body_format` | String | json | Body format, options are `json` `yaml` `xml` `text` | -| `http.follow_redirects` | Boolean | `false` | Follow HTTP redirects from server. | -| `http.headers` | Mapping | | Mapping/dict of http headers to append to requests. | -| `http.method` | String | GET | HTTP method to use for requests. | -| `http.path` | String | / | HTTP URI/Path. | -| `http.query` | Mapping | | Mapping/Dict of URL Query Parameters. | -| `http.retries` | Number | 0 | Number of retries to perform before request failure. | -| `http.scheme` | String | https | HTTP schema, must be `http` or `https` | -| `http.source` | String | | Request source IP address. | -| `http.ssl_ca` | String | | Path to SSL CA certificate file for SSL validation. | -| `http.ssl_client` | String | | Path to client SSL certificates for request. | -| `http.timeout` | Number | 5 | Request timeout in seconds. | -| `http.verify_ssl` | Boolean | `true` | If `false`, invalid certificates for HTTPS hosts will be ignored. | +**Example** -# Examples +```yaml filename="devices.yaml" {5-7} copy +devices: + - name: New York, NY + address: 192.0.2.1 + platform: cisco_ios + attrs: + source4: 192.0.2.1 + source6: "2001:db8::1" +``` -## Simple + + + + If you do not utilize IPv6 in your network, you'll need to create your own directive that only + has IPv4 commands. + + +## Examples + +### Simple ```yaml filename="devices.yaml" copy devices: @@ -75,7 +76,7 @@ devices: password: your password ``` -## With Directives +### With Directives In this example, an additional directive `cisco-show-lldp-neighbors` is added to the built-in directives. @@ -91,7 +92,7 @@ devices: - cisco-show-lldp-neighbors ``` -## Disable Built-in Directives +### Disable Built-in Directives In this example, _only_ the `cisco-show-lldp-neighbors` directive will be available. Built-in directives are disabled. @@ -108,7 +109,7 @@ devices: - cisco-show-lldp-neighbors ``` -## Enable Specifc Built-in Directives +### Enable Specifc Built-in Directives In this example, only specified built-in directives are made available. @@ -123,20 +124,3 @@ devices: directives: - builtin: [bgp_route, traceroute] ``` - -## With an SSH Proxy - -```yaml filename="devices.yaml" copy {8-12} -devices: - - name: New York, NY - address: 192.0.2.1 - platform: cisco_ios - credential: - username: you - password: your password - proxy: - address: 192.0.0.123 - credential: - username: your proxy's username - password: your proxy's password -``` diff --git a/docs/pages/configuration/devices/_meta.json b/docs/pages/configuration/devices/_meta.json new file mode 100644 index 0000000..ada061b --- /dev/null +++ b/docs/pages/configuration/devices/_meta.json @@ -0,0 +1,5 @@ +{ + "credentials": "Credentials", + "http-device": "HTTP Device", + "ssh-proxy": "SSH Proxy" +} diff --git a/docs/pages/configuration/devices/credentials.mdx b/docs/pages/configuration/devices/credentials.mdx new file mode 100644 index 0000000..463ff68 --- /dev/null +++ b/docs/pages/configuration/devices/credentials.mdx @@ -0,0 +1,35 @@ +Each device must be configured with credentials with which hyperglass can log into the device and execute commands. + +## Credential Configuration + +| Parameter | Type | Default Value | Description | +| :-------------------- | :----- | :------------ | :----------------------------------------------------- | +| `credential.username` | String | | Username to use for authentication to the device. | +| `credential.password` | String | | Password to use for authentication to the device. | +| `credential.key` | String | | Path to SSH key used for authentication to the device. | + +### Examples + +#### Username & Password + +```yaml filename="devices.yaml" copy {5-7} +devices: + - name: New York, NY + address: 192.0.2.1 + platform: cisco_ios + credential: + username: you + password: your password +``` + +#### SSH Private Key + +```yaml filename="devices.yaml" copy {5-7} +devices: + - name: San Francisco, CA + address: 192.0.2.2 + platform: juniper + credential: + username: you + key: /path/to/your/ssh/key +``` diff --git a/docs/pages/configuration/devices/http-device.mdx b/docs/pages/configuration/devices/http-device.mdx new file mode 100644 index 0000000..ce14abe --- /dev/null +++ b/docs/pages/configuration/devices/http-device.mdx @@ -0,0 +1,85 @@ +hyperglass supports collecting output from a generic HTTP endpoint. + +## HTTP Configuration + +| Parameter | Type | Default Value | Description | +| :---------------------- | :------ | :------------ | :--------------------------------------------------------------------------------------------------------------------- | +| `http.attribute_map` | Mapping | | Mapping/dict of hyperglass query fields as keys, and hyperglass query field replacements as values. | +| `http.basic_auth` | Mapping | | If basic authentication is required, provide a mapping/dict containing the basic authentication username and password. | +| `http.body_format` | String | json | Body format, options are `json` `yaml` `xml` `text` | +| `http.follow_redirects` | Boolean | `false` | Follow HTTP redirects from server. | +| `http.headers` | Mapping | | Mapping/dict of http headers to append to requests. | +| `http.method` | String | GET | HTTP method to use for requests. | +| `http.path` | String | / | HTTP URI/Path. | +| `http.query` | Mapping | | Mapping/Dict of URL Query Parameters. | +| `http.retries` | Number | 0 | Number of retries to perform before request failure. | +| `http.scheme` | String | https | HTTP schema, must be `http` or `https` | +| `http.source` | String | | Request source IP address. | +| `http.ssl_ca` | String | | Path to SSL CA certificate file for SSL validation. | +| `http.ssl_client` | String | | Path to client SSL certificates for request. | +| `http.timeout` | Number | 5 | Request timeout in seconds. | +| `http.verify_ssl` | Boolean | `true` | If `false`, invalid certificates for HTTPS hosts will be ignored. | + +### Example + +#### Basic + +The following example will send an HTTP POST request to `https://192.0.2/path/to/query/device` with HTTP basic authentication, and will not verify the SSL certificate. + +```yaml filename="devices.yaml" copy +devices: + - name: New York, NY + address: 192.0.2.1 + http: + path: /path/to/query/device + method: POST + verify_ssl: false + basic_auth: + username: you + password: your password +``` + +Given the following hyperglass query: + +| Field | Value | +| :------------- | :------------------ | +| Query Target | `192.0.2.0/24` | +| Query Location | `your_location` | +| Query Type | `example_directive` | + +The body of the request will be: + +```json +{ + "query_target": "192.0.2.0/24", + "query_location": "your_location", + "query_type": "example_directive" +} +``` + +#### Non-HTTPS Request + +The following example will send an HTTP GET request to `http://192.0.2.1/path/to/query/device`: + +```yaml filename="devices.yaml" {6} copy +devices: + - name: New York, NY + address: 192.0.2.1 + http: + path: /path/to/query/device + scheme: http +``` + +#### Header Authentication + +The following example will send an HTTP GET request to `https://192.0.2.1/path/to/query/device` with an `Authorization` header: + +```yaml filename="devices.yaml" {6-7} copy +devices: + - name: New York, NY + address: 192.0.2.1 + http: + path: /path/to/query/device + headers: + Authorization: your special token +``` diff --git a/docs/pages/configuration/devices/ssh-proxy.mdx b/docs/pages/configuration/devices/ssh-proxy.mdx new file mode 100644 index 0000000..99d19f1 --- /dev/null +++ b/docs/pages/configuration/devices/ssh-proxy.mdx @@ -0,0 +1,30 @@ +In cases where access to the devices is secured behind a "jump box" or other intermediary server/device, hyperglass can use SSH local port forwarding to SSH to an intermedary device first, and then to the device. + +## SSH Proxy Configuration + +| Parameter | Type | Default Value | Description | +| :----------------- | :------ | :------------ | :----------------------------------------------------------------------------------- | +| `proxy.address` | String | | IPv4 address, IPv6 address, or hostname of SSH proxy. | +| `proxy.port` | Number | 22 | TCP port to use for connecting to the SSH proxy. | +| `proxy.platform` | String | linux_ssh | Currently, only `linux_ssh` is supported. | +| `proxy.credential` | Mapping | | Mapping/dict of a [credential configuration](/configuration/config/credentials.mdx). | + +### Examples + +#### Use an SSH Proxy When Connecting to a Device + +```yaml filename="devices.yaml" copy +devices: + - name: New York, NY + address: 192.0.2.1 + credential: + username: you + password: your password + proxy: + address: 203.0.113.1 + credential: + username: your proxy username + password: your proxy password +``` + +In the above example, the credentials `your proxy username`/`your proxy password` will be used to authenticate from the hyperglass server to the SSH proxy, and the credentials `you`/`your password` will be used to authentiate from the SSH proxy to the device. diff --git a/docs/pages/configuration/examples/add-your-own-command.mdx b/docs/pages/configuration/examples/add-your-own-command.mdx index 345e613..a8f588a 100644 --- a/docs/pages/configuration/examples/add-your-own-command.mdx +++ b/docs/pages/configuration/examples/add-your-own-command.mdx @@ -1,37 +1,60 @@ -While hyperglass does come with several built-in commands or [directives](/configuration/directives-file-reference), you can also add your own. For example, say you want to add a command that shows the BGP summary from a device: +import { Steps } from "nextra/components"; -## 1. Create the Directive +## Add Your Own Command -```yaml filename="directives.yaml" +While hyperglass does come with several built-in [directives](/configuration/configuration/directives.mdx) (commands), you can also add your own. For example, say you want to add a command that shows the BGP summary from a device: + + + +### Create the Directive + +```yaml filename="directives.yaml" copy show-bgp-summary: - name: BGP Summary - rules: - - condition: null - command: show bgp all summary - field: null + name: BGP Summary + rules: + - condition: null + command: show bgp all summary + field: null ``` -## 2. Associate the Directive with the Device +### Associate the Directive with the Device -```yaml filename="devices.yaml" +```yaml filename="devices.yaml" {5-6} copy devices: - - name: Your Router - address: 192.0.2.1 - platform: cisco_ios - directives: - - show-bgp-summary + - name: Your Router + address: 192.0.2.1 + platform: cisco_ios + directives: + - show-bgp-summary ``` + + +## Default Directives + By default, all built-in directives are _also_ enabled. If you wish to _only_ enable directives you specify, you can use `builtins: false` as a directive: -```yaml filename="devices.yaml" +```yaml filename="devices.yaml" {6-7} copy devices: - - name: Your Router - address: 192.0.2.1 - platform: cisco_ios - directives: - - builtins: false - - show-bgp-summary + - name: Your Router + address: 192.0.2.1 + platform: cisco_ios + directives: + - builtins: false + - show-bgp-summary ``` -When this is specified, _only_ the `show-bgp-summary` directive will be enabled. +In the above example, _only_ the `show-bgp-summary` directive will be enabled. + +You can also selectively enable certain built-in directives: + +```yaml filename="devices.yaml" {6} copy +devices: + - name: Your Router + address: 192.0.2.1 + platform: cisco_ios + directives: + - builtins: [bgp_route, traceroute] +``` + +In the above example, _only_ the BGP Route and Traceroute built-in directives will be enabled. diff --git a/docs/pages/configuration/examples/basic-configuration.mdx b/docs/pages/configuration/examples/basic-configuration.mdx index 831735e..f399916 100644 --- a/docs/pages/configuration/examples/basic-configuration.mdx +++ b/docs/pages/configuration/examples/basic-configuration.mdx @@ -14,8 +14,6 @@ To get started, hyperglass only needs to know about your devices. ## Simple Device Configuration -Create a file called `devices.yaml` in the directory `/etc/hyperglass`. - ```yaml filename="devices.yaml" devices: - name: NYC Router 1 diff --git a/docs/pages/configuration/examples/customize-the-ui.mdx b/docs/pages/configuration/examples/customize-the-ui.mdx index a84122f..da8a998 100644 --- a/docs/pages/configuration/examples/customize-the-ui.mdx +++ b/docs/pages/configuration/examples/customize-the-ui.mdx @@ -2,28 +2,47 @@ description: Customize hyperglass to fit your needs. --- -### Change the title and organization name +import { DocsButton } from "../../../components/docs-button"; + +### Change the Title and Organization Name ```yaml filename="config.yaml" site_title: Our super neat looking glass org_name: Cool Company ``` -### Change the logo +### Change the Logo -```yaml filename="config.yaml" +```yaml filename="config.yaml" {2-4} copy web: - logo: - light: - dark: + logo: + light: + dark: ``` -### Change the color scheme +### Change the Color Scheme -```yaml filename="config.yaml" +```yaml filename="config.yaml" copy {3-5} web: - theme: - colors: - primary: '#d84b4b' - secondary: '#118ab2' + theme: + colors: + primary: "#d84b4b" + secondary: "#118ab2" +``` + +### Add a Link to the Footer + +```yaml filename="config.yaml" copy +web: + links: + - title: PeeringDB + url: https://www.peeringdb.com/65000 + show_icon: true + side: right + order: 1 + - title: Our Website + url: https://example.com + show_icon: false + side: left + order: 0 ``` diff --git a/docs/pages/configuration.mdx b/docs/pages/configuration/overview.mdx similarity index 64% rename from docs/pages/configuration.mdx rename to docs/pages/configuration/overview.mdx index 184d02e..cc36ae4 100644 --- a/docs/pages/configuration.mdx +++ b/docs/pages/configuration/overview.mdx @@ -1,34 +1,16 @@ import { Code, Table, Td, Th, Tr } from "nextra/components"; import { Callout } from "nextra-theme-docs"; -import platforms from "~/platforms.json"; -import { Supported } from "./platforms.mdx"; - -export const Platforms = () => ( -
    - {platforms.reduce((final, platform) => { - if (platform.native) { - const element = ( -
  • - - {platform.name} -
    • - ); - final = [...final, element]; - } - return final; - }, [])} -
-); +import { SupportedPlatforms } from "~/components/platforms"; Once you've gotten started with a basic configuration, you'll probably want to customize the look and feel of hyperglass by changing the logo or color scheme. Fortunately, there are _a lot_ ways to customize hyperglass. ## Configuration Files -| File Name | Purpose | -| :----------- | :------------------------------------------------------------------------- | -| `config` | Application-wide configuration such as logging, web UI customization, etc. | -| `devices` | Your devices and their associated configurations. | -| `directives` | Custom [directives](configuration/directives.mdx) (commands). | +| File Name | Docs | Purpose | +| :----------- | :---------------------------------------------------: | :------------------------------------------------------------------------- | +| `config` | [Config File Docs](/configuration/config.mdx) | Application-wide configuration such as logging, web UI customization, etc. | +| `devices` | [Devices File Docs](/configuration/devices.mdx) | Your devices and their associated configurations. | +| `directives` | [Directives File Docs](/configuration/directives.mdx) | Custom directives (commands). | **File Extensions**
@@ -78,9 +60,9 @@ main = { ## Built-in Directives -hyperglass ships with predefined [directives](configuration/directives.mdx) for the following [platforms](platforms.mdx): +hyperglass ships with predefined [directives](/configuration/directives.mdx) for the following [platforms](platforms.mdx): - + All built in directives require that the following `attrs` be defined on each device using the directive: diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index add56fb..7f37ab7 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -4,19 +4,7 @@ description: Get started with hyperglass --- import { Cards, Card } from "nextra/components"; -import platforms from "~/platforms.json"; - -export const Platforms = () => ( -
    - {platforms.reduce((final, platform) => { - if (platform.native) { - const element =
  • {platform.name}
    • ; - final = [...final, element]; - } - return final; - }, [])} -
-); +import { SupportedPlatforms } from "~/components/platforms"; ## What is hyperglass? @@ -30,7 +18,7 @@ hyperglass was created with the lofty goal of benefiting the internet community - Full IPv6 support - Customizable everything: features, theme, UI/API text, error messages, commands - Built in support for: - + - Configurable support for any other [supported platform](platforms.mdx) - Optionally access devices via an SSH proxy/jump server - VRF support diff --git a/docs/pages/platforms.mdx b/docs/pages/platforms.mdx index 0d63f89..19a71d8 100644 --- a/docs/pages/platforms.mdx +++ b/docs/pages/platforms.mdx @@ -2,58 +2,8 @@ description: Platforms supported by hyperglass --- -import { Code, Table, Td, Th, Tr } from "nextra/components"; import { Callout } from "nextra-theme-docs"; -import platforms from "~/platforms.json"; - -export const NotSupported = () => ( - - - - -); - -export const Supported = (props) => ( - - - -); - -export const Platforms = () => ( - - - - - - - {platforms.map((spec) => ( - - - - - ))} - -
Platform KeysNatively Supported
- {spec.keys.map((key) => ( - - {key} - - ))} - {spec.native ? : }
-); +import { PlatformTable } from "~/components/platforms"; hyperglass uses [Netmiko](https://github.com/ktbyers/netmiko) to interact with devices via SSH/telnet. [All platforms supported by Netmiko](https://github.com/ktbyers/netmiko/blob/develop/PLATFORMS.md) are supported by hyperglass. @@ -69,7 +19,7 @@ hyperglass uses [Netmiko](https://github.com/ktbyers/netmiko) to interact with d
- + ## Other Platforms diff --git a/hyperglass/models/config/cache.py b/hyperglass/models/config/cache.py index 1a2b6e1..0871b94 100644 --- a/hyperglass/models/config/cache.py +++ b/hyperglass/models/config/cache.py @@ -1,26 +1,12 @@ -"""Validation model for Redis cache config.""" +"""Validation model for cache config.""" -# Standard Library -import typing as t - -# Third Party -from pydantic import SecretStr, IPvAnyAddress # Local from ..main import HyperglassModel -class CachePublic(HyperglassModel): +class Cache(HyperglassModel): """Public cache parameters.""" timeout: int = 120 show_text: bool = True - - -class Cache(CachePublic): - """Validation model for params.cache.""" - - host: t.Union[IPvAnyAddress, str] = "localhost" - port: int = 6379 - database: int = 1 - password: t.Optional[SecretStr] = None diff --git a/hyperglass/models/config/devices.py b/hyperglass/models/config/devices.py index 6d4df1b..b683d3e 100644 --- a/hyperglass/models/config/devices.py +++ b/hyperglass/models/config/devices.py @@ -203,12 +203,22 @@ class Device(HyperglassModelWithId, extra="allow"): def validate_platform(cls: "Device", value: t.Any, values: t.Dict[str, t.Any]) -> str: """Validate & rewrite device platform, set default `directives`.""" + if value == "http": + if values.get("http") is None: + raise ConfigError( + "Device '{device}' has platform 'http' configured, but no http parameters are defined.", + device=values["name"], + ) + if value is None: - # Ensure device platform is defined. - raise ConfigError( - "Device '{device}' is missing a 'platform' (Network Operating System) property", - device=values["name"], - ) + if values.get("http") is not None: + value = "http" + else: + # Ensure device platform is defined. + raise ConfigError( + "Device '{device}' is missing a 'platform' (Network Operating System) property", + device=values["name"], + ) if value in SCRAPE_HELPERS.keys(): # Rewrite platform to helper value if needed. diff --git a/hyperglass/models/ui.py b/hyperglass/models/ui.py index 3dfacfc..3e2c106 100644 --- a/hyperglass/models/ui.py +++ b/hyperglass/models/ui.py @@ -6,7 +6,7 @@ import typing as t # Local from .main import HyperglassModel from .config.web import WebPublic -from .config.cache import CachePublic +from .config.cache import Cache from .config.params import ParamsPublic from .config.messages import Messages @@ -54,7 +54,7 @@ class UIContent(HyperglassModel): class UIParameters(ParamsPublic, HyperglassModel): """UI Configuration Parameters.""" - cache: CachePublic + cache: Cache web: WebPublic messages: Messages version: str