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 lot 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.
google_analyticsStringGoogle 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:

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.➡️

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: [lg.example.com, 192.0.2.1]