checktheroads-hyperglass/docs/development/index.md

Hyperglass Development

Hyperglass is maintained as a Github project under the BSD 3-Clause Clear License. Hyperglass users are encouraged to submit Github issues for feature requests and bug reports.

License

The intent behind the the BSD 3-Clause Clear License is to ensure that anyone can use or modify Hyperglass in any way they wish, as long as credit and copyright notice is provied. If you have any questions about this, or wish to request any special permissions, please contact matt@allroads.io.

Structure

Under the main hyperglass/hyperglass/ directory, the following basic structure is in place:

hyperglass/
├── __init__.py
├── command/
├── configuration/
├── gunicorn_config.py
├── hyperglass.py
├── manage.py
├── render/
├── static/
└── wsgi.py

Scripts

hyperglass.py

Main Flask application. Passes input to the command.execute module.

manage.py

Management script for perfoming one-off actions. For now, the only action implemented is a manual clearing of the Flask-cache cache. To clear the cache, run python3 manage.py --clearcache.

Directories

command/

hyperglass/command/
├── __init__.py
├── construct.py
├── execute.py
└── parse.py

execute.py

Matches router name to router IP, OS, and credentials. Passes data to cmd_construct.py, uses the results to execute the Netmiko action. Also performs error handling in the event of a blacklist match.

construct.py

Constructs full commands to run on routers from hyperglass/hyperglass/config/commands.toml. Also performs error handling in the event of input errors.

parser.py

Parses output before presentation to the user. For the time being, only BGP output from Cisco IOS is parsed. This is because for BGP Community and AS_PATH lookups, Cisco IOS returns results for all address families, including VPNv4. This script ensures that only IPv4 and IPv6 address family output is returned.

configuration/

The configuration/ directory contains all TOML config files used by Hyperglass:

hyperglass/configuration/
├── __init__.py
├── blacklist.toml
├── commands.toml
├── config.toml
├── devices.toml
└── requires_ipv6_cidr.toml

As a module, configuration imports configuration from TOML configuration files, defines default values, and exports each as a variable that can be called in other scripts.

static/

The static/ directory contains all static HTML/CSS/JS files used for serving the site:

hyperglass/static/
├── css/
│   ├── hyperglass.css
│   └── icofont
├── images/
│   ├── brand.svg
│   ├── favicon
│   ├── hyperglass-dark.png
│   └── hyperglass-light.png
├── js/
│   ├── hyperglass.js
│   ├── jquery-3.4.0.min.js
│   └── jquery-3.4.0.min.map
└── sass/
    ├── base
    ├── components
    ├── custom
    ├── elements
    ├── grid
    ├── hyperglass.scss
    ├── layout
    └── utilities

• css/hyperglass.css Final CSS file compiled from Sass file hyperglass.scss. Sass compiles all the .sass files located under sass/ and combines them into a single CSS file.
• css/icofont/ Completely free alternative to FontAwesome - Icofont.
• js/hyerpglass.js Basic Javascript helper to perform AJAX queries necessary to pull in dynamic information and render content.

render/

The render/ directory contains the render module, which renders HTML and Sass templates, compiles Sass to CSS.

hyperglass/render/
├── __init__.py
└── templates/
    ├── 415.html
    ├── 429.html
    ├── base.html
    ├── footer.html
    ├── footer.md
    ├── hyperglass.scss
    └── index.html

render/templates/ contains the Jinja2 templates themselves:

• 415.html General error page template.
• 429.html Site load rate limit page.
• base.html Base template inherited by all other templates. Contains HTML head, JavaScript, etc.
• footer.html Footer template containing footer text and hyperglass credit link.
• footer.md Text that appears in the footer, if enabled. Markdown will be rendered as HTML.
• hyperglass.scss Generates SCSS file for Bulma and local customizations.
• index.html Main page template.