diff --git a/docs/docs/configuration.mdx b/docs/docs/configuration.mdx index e7a65c2..03dbd87 100644 --- a/docs/docs/configuration.mdx +++ b/docs/docs/configuration.mdx @@ -6,8 +6,11 @@ keywords: [configuration] description: Configuring hyperglass --- +import Link from "@docusaurus/Link"; import Admonition from "react-admonitions"; -import R from "../src/components/required"; +import R from "../src/components/Required"; +import MiniNote from "../src/components/MiniNote"; +import Code from "../src/components/JSXCode"; hyperglass is meant to be _extremely_ customizable, but with reasonable defaults that most operators won't need to override. Even though there are a _lot_ of configuration options, all of them can be left untouched and hyperglass will work (although, it's recommended to at least set the organization name). @@ -74,11 +77,215 @@ There are a lot more options, but this is enough to get started. ## All Device Parameters -| Parameter | Type | Description | -| ------------------- | ------- | ------------------------------------------------------------------------------------------------------- | -| `name` | String | Device hostname. This is not user-facing. | -| `address` | String | Device management hostname or IP address. | -| `network` | String | Primary network this device is a member of. Used for device grouping. Usually something like 'AS65000'. | -| `display_name` | String | Device's user-facing name. | -| `port` | Integer | TCP port used to connect to the device. | -| `nos` | String | Network Operating System. Must be a [supported platform](/docs/platforms) | +| Parameter | Type | Description | +| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `name` | String | Device hostname. This is not user-facing. | +| `address` | String | Device management hostname or IP address. | +| `network` | String | Primary network this device is a member of. Used for device grouping. Usually something like 'AS65000'. | +| `display_name` | String | Device's user-facing name. | +| `port` | Integer | TCP port used to connect to the device. | +| `nos` | String | Network Operating System. Must be a supported platform. | +| `credential` | | Device Credential Configuration | +| `vrfs` | | Device VRF Configuration | +| `proxy` | | SSH Proxy Configuration | +| `ssl` | | SSL Configuration for devices using [hyperglass-agent](https://github.com/checktheroads/hyperglass-agent). | + +### `proxy` + +Any device that uses SSH (see platforms for breakdown) can be accessed through an intermediary SSH "proxy". The process is nearly identical to using local SSH tunneling, e.g. `ssh -L local_port:remote_device:remote_port username@proxy_server -p proxy_port`. + +| Parameter | Type | Default | Description | +| ----------------- | ------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `name` | String | | Proxy hostname. | +| `address` | String | | Proxy management hostname or IP address. | +| `credential` | | | Proxy Credential Configuration | +| `nos` | String | `'linux_ssh'` | Proxy's network operating system. Must be a supported platform. | +| `port` | Integer | `22` | TCP port user to connect to the proxy. | + + + Currently only linux_ssh has been tested and validated for use as an SSH proxy. +; + +### `credential` + +While all devices require a credential mapping, the credential values themselves may be used in different ways depending on the device NOS. For SSH devices, the credential is used as a typical SSH username and password. + +For HTTP devices (i.e. devices using [hyperglass-agent](https://github.com/checktheroads/hyperglass-agent)), the username is ignored and the password is used as a secret for [JSON Web Token](https://tools.ietf.org/html/rfc7519) encoding/decoding. + +| Parameter | Type | Description | +| --------------- | ------ | ------------------------------------------------------------ | +| `username` | String | Username | +| `password` | String | Password Passwords will never be logged | + +### `ssl` + +HTTP devices may optionally use SSL for the connection between hyperglass and the device. This is **disabled** by default, which means devices will use unencrypted HTTP by default. + +If SSL is enabled, the public key of the device must be provided in the form of an accessible absolute file path. With SSL enabled and a valid certificate specified, every connection to the device will use HTTPS in addition to payload encoding with [JSON Web Tokens](https://tools.ietf.org/html/rfc7519). + +| Parameter | Type | Description | +| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enable` | Boolean | Enable or disable the use of SSL. If enabled, a certificate file must be specified (hyperglass does not support connecting to a device over an unverified SSL session). | +| `cert` | String | Absolute path to agent's public RSA key. | + +### `vrfs` + +The VRFs section is a list of available VRFs for a given device. Each VRF may be configured with the following fields: + +| Parameter | Type | Description | +| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | String | The VRF's name, as known **by the device**. hyperglass sends this field to the device for queries, so it needs to match the device's configuration. | +| `display_name` | String | The VRF's user-facing name. This field's value is visible in the UI. If this is not specified, hyperglass will try to create a "pretty" display name based on the `name` field. | +| `info` | | Per-VRF Contextual Help Configuration | +| `ipv4` | | VRF's IPv4 Configuration | +| `ipv6` | | VRF's IPv6 Configuration | + +#### `ipv4` + +May be set to `null` to disable IPv4 for this VRF, on the parent device. + +| Parameter | Type | Description | +| --------------------- | ------ | --------------------------------------------------------------------- | +| `source_address` | String | Device's source IPv4 address for directed queries (ping, traceroute). | +| `access_list` | | IPv4 Access List Configuration | + +#### `ipv6` + +May be set to `null` to disable IPv6 for this VRF, on the parent device. + +| Parameter | Type | Description | +| --------------------- | ------ | --------------------------------------------------------------------- | +| `source_address` | String | Device's source IPv6 address for directed queries (ping, traceroute). | +| `access_list` | | IPv6 Access List Configuration | + +#### `access_list` + +The `access_list` block can be thought of like a prefix-list from Cisco IOS. It is a list of rules, where the first matching rule is the action executed. + +| Parameter | Type | Default | Description | +| -------------- | ------- | ------------- | --------------------------------------------------------------------------- | +| `network` | String | | This rule's IPv4 or IPv6 base prefix | +| `action` | String | `'permit'` | This rule's action. Must be `permit` or `deny` | +| `ge` | Integer | `0` | To match this rule, the target prefix must be greater than or equal to `ge` | +| `le` | Integer | `32` \| `128` | To match this rule, the target prefix must be less than or equal to `le` | + +#### `info` + +Each VRF may enable, disable, or customize the contextual help menu for each enabled query type. The following parameters may be defined under any query type: + +| Parameter | Type | Default | Description | +| --------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | +| `enable` | Boolean | `true` | Enable or disable the help menu for this command. | +| `file` | String | | Path to a plain text or markdown file containing customized help information for this command. | +| `params` | Object | | Any arbitrary key/value pairs where the value will replace any occurrences of the key when wrapped in braces (e.g. `{key}`) | + +For example: + +```yaml +info: + bgp_route: + enable: true + file: /etc/hyperglass/customer_bgp_route.md + params: + vrf_name: Customer A + ping: + enable: false + bgp_community: + enable: true + file: /etc/hyperglass/customer_bgp_community.md + params: + vrf_name: Customer A + community: "65000" +``` + +### Full Example + +Below is a full example with nearly every available knob turned: + +```yaml +routers: + # HTTP/hyperglass-agent device + - name: router01 + display_name: HTTP Router + address: 192.0.2.1 + network: + - name: primary + display_name: AS65000 + credential: + username: madeup + password: txeTTIqwhKSJi4V3tefXQASf5AyGZ6cPsycS9nYLpKk + ssl: + enable: true + cert: /etc/hyperglass/certs/router01.pem + port: 8080 + nos: frr + vrfs: + - name: default + ipv4: + source_address: 192.0.2.1 + access_list: + - network: 10.0.0.0/8 + action: deny + ge: 8 + le: 32 + - network: 0.0.0.0/0 + action: permit + le: 24 # Only allow /24 or smaller prefixes + ipv6: + source_address: 2001:db8::1 + access_list: + - network: ::/0 + action: permit + proxy: null + + # SSH/netmiko device + - name: router02 + address: 10.0.0.1 + network: + name: primary + display_name: AS65000 + credential: + username: user + password: pass + display_name: SSH Router + port: 22 + nos: cisco_ios + vrfs: + - name: default + ipv4: + source_address: 192.0.2.2 + access_list: + - network: 10.0.0.0/8 + action: deny + ge: 8 + le: 32 + - network: 0.0.0.0/0 + action: permit + ipv6: + source_address: 2001:db8::2 + access_list: + - network: ::/0 + action: permit + le: 64 # Only allow /64 or smaller prefixes + - name: special_customer + display_name: Customer Name + ipv4: + source_address: 172.16.0.1 + access_list: + - network: 172.16.0.0/16 + action: allow + ipv6: null # disable IPv6 for this VRF + info: + bgp_route: + file: /etc/hyperglass/help/customer_bgp_route.md + params: + customer_name: Customer Name + proxy: + name: jump_server + address: 10.0.1.100 + port: 22 + credential: + username: user + password: pass + nos: linux_ssh +``` diff --git a/docs/src/components/JSXCode.js b/docs/src/components/JSXCode.js new file mode 100644 index 0000000..2162b30 --- /dev/null +++ b/docs/src/components/JSXCode.js @@ -0,0 +1,17 @@ +import React from "react"; + +export default ({ children }) => ( + + {children} + +); diff --git a/docs/src/components/MiniNote.js b/docs/src/components/MiniNote.js new file mode 100644 index 0000000..d4f0d7b --- /dev/null +++ b/docs/src/components/MiniNote.js @@ -0,0 +1,17 @@ +import React from "react"; + +export default ({ children }) => ( + <> +
+ + {children} + + +); diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 0732fcd..7231375 100755 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -6,6 +6,7 @@ /* You can override the default Infima variables here. */ :root { + --ifm-font-size-sm: 12px; --ifm-color-secondary: #314cb6; --ifm-color-secondary-dark: #2c44a4; --ifm-color-secondary-darker: #2a419b;