From 3f4474794822d7827e0b7fa8d060402c1c3256a0 Mon Sep 17 00:00:00 2001 From: checktheroads Date: Wed, 8 May 2019 10:39:20 -0700 Subject: [PATCH] fixed requirements issue, added more docs --- README.md | 37 ++++++++++-------- docs/installation/installing-hyperglass.md | 44 ++++++++++++++++++++++ hyperglass/config/config.toml.example | 2 +- mkdocs.yml | 5 ++- requirements.txt | 2 +- screenshots.md | 1 + 6 files changed, 72 insertions(+), 19 deletions(-) create mode 100644 docs/installation/installing-hyperglass.md diff --git a/README.md b/README.md index 51f558f..7d8b154 100644 --- a/README.md +++ b/README.md @@ -9,18 +9,18 @@ ![GitHub top language](https://img.shields.io/github/languages/top/checktheroads/hyperglass.svg) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) - ## Features -- BGP Route, BGP Community, BGP AS_PATH, Ping, Traceroute -- Full IPv6 support -- [Netmiko](https://github.com/ktbyers/netmiko)-based connection handling -- Customizable commands for each function by vendor -- Clean, google-esq GUI based on the [Bumla](https://bulma.io) framework -- Customizable colors, logo, web fonts, error messages, UI text -- TOML-based config file for all customizable parameters (no databases!) -- Configurable IP/Prefix "blacklist" to prevent lookup of internal/private prefixes -- Configurable rate limiting, powered by [Flask-Limiter](https://github.com/alisaifee/flask-limiter) -- Query response caching with configurable cache timeout, powered by [Flask-Caching](https://github.com/sh4nks/flask-caching) + +- BGP Route, BGP Community, BGP AS_PATH, Ping, Traceroute +- Full IPv6 support +- [Netmiko](https://github.com/ktbyers/netmiko)-based connection handling +- Customizable commands for each function by vendor +- Clean, google-esq GUI based on the [Bumla](https://bulma.io) framework +- Customizable colors, logo, web fonts, error messages, UI text +- TOML-based config file for all customizable parameters (no databases!) +- Configurable IP/Prefix "blacklist" to prevent lookup of internal/private prefixes +- Configurable rate limiting, powered by [Flask-Limiter](https://github.com/alisaifee/flask-limiter) +- Query response caching with configurable cache timeout, powered by [Flask-Caching](https://github.com/sh4nks/flask-caching) ## Documentation @@ -31,18 +31,23 @@ Documentation can be found [here](https://hyperglass.readthedocs.io), or in the For screenshots, see [here](screenshots.md), or the `screenshots/` directory. ## Platform Support + Theoretically, any vendor supported by Netmiko can be supported by Hyperglass. However, I am currently listing platforms I have personally tested and verified full functionality with: ### Routers -- Cisco IOS-XR: `cisco_xr` -- Cisco Classic IOS/IOS-XE: `cisco_ios` -- Juniper JunOS: `junos` + +- Cisco IOS-XR: `cisco_xr` +- Cisco Classic IOS/IOS-XE: `cisco_ios` +- Juniper JunOS: `junos` ### Proxies -- Linux: `linux_ssh` + +- Linux: `linux_ssh` ## Acknowledgements -- This project originally started as a fork of vraulsan's [looking-glass](https://github.com/vraulsan/looking-glass) project. The guts of the Flask components still remain from that project, but almost everything else has been rewritten. Nevertheless, the inspiration for building hyperglass came from here. + +- This project originally started as a fork of vraulsan's [looking-glass](https://github.com/vraulsan/looking-glass) project. The guts of the Flask components still remain from that project, but almost everything else has been rewritten. Nevertheless, the inspiration for building hyperglass came from here. ## License + [Clear BSD License](https://github.com/checktheroads/hyperglass/master/LICENSE) diff --git a/docs/installation/installing-hyperglass.md b/docs/installation/installing-hyperglass.md new file mode 100644 index 0000000..ad0bccb --- /dev/null +++ b/docs/installation/installing-hyperglass.md @@ -0,0 +1,44 @@ +# Download + +## System Requirements + +!!! warning "Compatibility" + To date, Hyperglass has only been installed tested on Mac OS X 10.14 and Ubuntu Linux 18.04. Installation instructions are specific to Ubuntu 18.04. Installation instructions for additional operating systems are forthcoming (contribution welcome!). + +Hyperglass is written and tested on Python 3.7, but should be backwards compatible with any Python 3 version (albeit untested). If needed, install Python 3 and PyPi 3 on your system: + +```console +# apt install -y python3 python3-pip +``` + +## Clone the repository + +```console +$ cd /opt/ +$ git clone https://github.com/checktheroads/hyperglass +``` + +## Install Required Python Modules + +```console +$ cd /opt/hyperglass/hyperglass +$ pip3 install -r requirements.txt +``` + +## Clone Example Configuration Files + +``` +$ cd /opt/hyperglass/hyperglass/config/ +$ for f in *.example; do cp $f `basename $f .example`; done; +``` + +## Test the Application + +At this stage, Hyperglass should be able to start up with the built-in Flask development server. This will be enough to verify that the application itself can run, and provie a means to test branding customizations, router connectivity, etc., prior to placing a production-grade WSGI & web server in front of Hyperglass. + +```console +$ cd /opt/hyperglass/hyperglass/ +$ python3 app.py +``` + +You should now be able to access hyperglass by loading the name or IP on port 5000 in a web browser, for example: `http://10.0.0.1:5000`. Note that the Flask development server is **not** suited for production use. This will simply verify that the application and dependencies have been correctly installed. Production deployment will be covered in the next sections. diff --git a/hyperglass/config/config.toml.example b/hyperglass/config/config.toml.example index d780168..d84c468 100644 --- a/hyperglass/config/config.toml.example +++ b/hyperglass/config/config.toml.example @@ -1,7 +1,7 @@ # General site-wide parameters [[general]] primary_asn = "" -debug = true +debug = false google_analytics = "" message_error = "" message_blacklist = "" diff --git a/mkdocs.yml b/mkdocs.yml index a4f96c4..911e524 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,7 +5,10 @@ copyright: '' nav: - Home: 'index.md' - Installation: - - 'installation.md' + - 'Installing Hyperglass': 'installation/installing-hyperglass.md' + - 'HTTP/WSGI': 'installation/wsgi.md' + - 'Reverse Proxy': 'installation/reverseproxy.md' + - 'Running Hyperglass as a Service': 'installation/supervisord.md' - Configuration: - 'Configuring Hyperglass': 'configuration.md' - 'General Parameters': 'configuration/general.md' diff --git a/requirements.txt b/requirements.txt index 8b70058..6923f7e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ Flask Flask-Limiter -flask-cache +flask-caching Jinja2 toml netmiko diff --git a/screenshots.md b/screenshots.md index fc857e2..4d9f7b2 100644 --- a/screenshots.md +++ b/screenshots.md @@ -11,6 +11,7 @@ ![](screenshots/lookup_bgp_route.png) ## BGP Community + ![](screenshots/lookup_bgp_community.png) ## BGP AS_PATH