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
Files
bb8cc55dc7918e01c87c89f81b6876e121cb6f2a
checktheroads-hyperglass/docs/docs/configuration.mdx

121 lines
10 KiB
Plaintext
Raw Blame History

---
id: configuration
title: Configuration
sidebar_label: Configuration
keywords: [configuration]
description: Configuring hyperglass
---
import Link from "@docusaurus/Link";
import MiniNote from "../src/components/MiniNote";
import PageLink from "../src/components/PageLink";
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).
:::tip Validation
On the back end, hyperglass uses strict configuration schema validation, so it's virtually impossible to configure hyperglass incorrectly without receiving a contextual warning about what's missing or incorrect about a configuration.
:::
## Configuration Files
hyperglass configuration consists of three separate [YAML](https://yaml.org/) configuration files:
- `hyperglass.yaml`
- Defines configuration parameters for the application and UI
<MiniNote>This file is not required for hyperglass to run</MiniNote>
- `devices.yaml`
- Defines devices (routers), SSH proxy servers, and credentials
<MiniNote>
This file <strong>is required</strong> for hyperglass to run
</MiniNote>
- `commands.yaml`
- Defines commands for custom network operating systems, or overrides default hyperglass command sets.
<MiniNote>This file is not required for hyperglass to run</MiniNote>
Configuration files may be located in one of the following directories:
- `/etc/hyperglass`
- `~/hyperglass`
## Global Settings
The following global settings can be set in `hyperglass.yaml`:
| Parameter | Type | Default | Description |
| :--------------------- | :--------------: | :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `debug` | Boolean | `false` | Enable application-wide debug mode. **This will generate a log of logs!** |
| `developer_mode` | Boolean | `false` | If enabled, the hyperglass backend (Python) and frontend (React/Javascript) applications are "unlinked", so that React tools can be used for front end development. A `<Debugger />` convenience component is also displayed in the UI for easier UI development.' |
| `primary_asn` | String | `'65000'` | Your network's primary ASN. This field is used to set some useful defaults such as the subtitle and PeeringDB URL. |
| `org_name` | String | `'Beloved Hyperglass User'` | Your organization's name. This field is used in the UI & API documentation to set fields such as `<meta/>` HTML tags for SEO and the terms & conditions footer component. |
| `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. |
| `listen_address` | String | `'localhost'` | Local IP Address or hostname 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_file` | String | | Path to a log file 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). |
:::note
The `netmiko_delay_factor` parameter should only be used if you're experiencing strange SSH connection issues. By default, Netmiko uses a `global_delay_factor` of `1`, which tends to be a bit slow for running a simple show command. hyperglass overrides this to `0.1` by default, but you can override this to whatever value suits your environment if needed.
:::
#### Example
```yaml
debug: false
developer_mode: false
org_name: Beloved Hyperglass User
site_title: hyperglass
site_description: "{org_name} Network Looking Glass"
site_keywords: [hyperglass, looking glass, routing, bgp]
request_timeout: 30
listen_address: localhost
listen_port: 8001
log_file: /tmp/hyperglass.log
cors_origins: [localhost:3000, 192.0.2.1]
```
### Subsections
From the top level, the following subsections may be defined and configured:
| Section | Description | All Options |
| :--------- | :-------------------------------------------------- | :-----------------------------------------: |
| `cache` | Redis server & cache timeout settings. | <PageLink to="/docs/cache">➡️</PageLink> |
| `docs` | API documentation settings. | <PageLink to="/docs/api">➡️</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> |
## Adding Devices
To add, as an example, a Cisco router, add the following to your `devices.yaml`, with the relevant details changed for your device:
```yaml
routers:
- name: router01.pop01
address: 10.0.0.1
network: AS65000
credential:
username: username
password: password
location: pop01
display_name: Phoenix, AZ
port: 22
nos: cisco_ios
vrfs:
- name: default
ipv4:
source_address: 192.0.2.1
ipv6:
source_address: 2001:db8::1
```
There are a lot more options, but this is enough to get started. For all device configuration options, <Link to="/docs/devices">see here</Link>.
:::tip YAML
If you have a lot of devices with shared configuration parameters, you may want to look into **YAML Anchors and Aliases**. If you've never used them before, they can be pretty weird looking at first read. Atlassian [has a pretty decent guide](https://confluence.atlassian.com/bitbucket/yaml-anchors-960154027.html).
:::
View Git Blame Copy Permalink