Configuration Parameters

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).

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 configuration files:

  • hyperglass.yaml
    • Defines configuration parameters for the application and UI
      This file is not required for hyperglass to run
  • devices.yaml
    • Defines devices (routers), SSH proxy servers, and credentials
      This file is required for hyperglass to run
  • commands.yaml
    • Defines commands for custom network operating systems, or overrides default hyperglass command sets.
      This file is not required for hyperglass to run

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:

ParameterTypeDefaultDescription
debugBooleanfalseEnable application-wide debug mode. This will generate a log of logs!
developer_modeBooleanfalseIf 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_asnString'65000'Your network's primary ASN. This field is used to set some useful defaults such as the subtitle and PeeringDB URL.
org_nameString'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_titleString'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_descriptionString'{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_keywordsListKeywords pertaining to your hyperglass site. This field is used to generate <meta name="keywords"/> HTML tags, which helps tremendously with SEO.
request_timeoutInteger90Global 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_addressString'localhost'Local IPv4/IPv6 Address the hyperglass application listens on to serve web traffic.
listen_portInteger8001Local TCP port the hyperglass application listens on to serve web traffic.
cors_originsList[]Allowed CORS hosts. By default, no CORS hosts are allowed.
netmiko_delay_factorInteger | Float0.1Override the Netmiko global delay factor.
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

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: [localhost:3000, 192.0.2.1]

Subsections

From the top level, the following subsections may be defined and configured:

SectionDescriptionAll Options
cacheRedis server & cache timeout settings.➡️
docsAPI documentation settings.➡️
loggingFile, syslog, and webhook settings.➡️
messagesCustomize almost all user-facing UI & API messages.➡️
queriesEnable, disable, or configure query types.➡️
structuredConfigure structured data features.➡️
webWeb UI & branding settings.➡️

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:

devices.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, see here.

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.