forked from mirrors/thatmattlove-hyperglass
91 lines
9.4 KiB
Text
91 lines
9.4 KiB
Text
---
|
|
id: parameters
|
|
title: Configuration Parameters
|
|
sidebar_label: Parameters
|
|
keywords: [hyperglass, configuration, parameters]
|
|
description: hyperglass configuration parameters.
|
|
---
|
|
|
|
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 lot 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 | `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. |
|
|
| `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). |
|
|
| `google_analytics` | String | | Google Analytics Tracking ID |
|
|
|
|
:::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.
|
|
:::
|
|
|
|
### 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="response-caching">➡️</PageLink> |
|
|
| `docs` | API documentation settings. | <PageLink to="rest-api">➡️</PageLink> |
|
|
| `logging` | File, syslog, and webhook settings. | <PageLink to="logging">➡️</PageLink> |
|
|
| `messages` | Customize almost all user-facing UI & API messages. | <PageLink to="messages">➡️</PageLink> |
|
|
| `queries` | Enable, disable, or configure query types. | <PageLink to="query-settings">➡️</PageLink> |
|
|
| `structured` | Configure structured data features. | <PageLink to="table-output">➡️</PageLink> |
|
|
| `web` | Web UI & branding settings. | <PageLink to="ui/configuration">➡️</PageLink> |
|
|
|
|
### Example
|
|
|
|
```yaml title="hyperglass.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: "127.0.0.1"
|
|
listen_port: 8001
|
|
log_file: /tmp/hyperglass.log
|
|
cors_origins: [lg.example.com, 192.0.2.1]
|
|
```
|