Skip to content
hyperglass API for Free Range Routing
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


hyperglass-frr is a restful API for the Free Range Routing stack, for use by hyperglass. hyperglass-frr ingests a HTTP POST request with JSON data and constructs 1 of 5 shell commands to run based on the passed parameters. For example:

  "query_type": "ping",
  "afi": "ipv4",
  "source": "",
  "target": ""

Would construct (by default) ping -4 -c 5 -I, execute the command, and return the output as a string. For BGP commands, FRRouting's vtysh is used to get the output. For example:

  "query_type": "bgp_route",
  "afi": "ipv6",
  "target": "2606:4700:4700::/48"

Would construct (by default) vtysh -u -c "show bgp ipv6 unicast 2606:4700:4700::/48", execute the command, and return the output as a string.


Currently, hyperglass-frr has only been tested on Ubuntu Server 18.04. A sample systemd service file is included to run hyperglass-frr as a service.

Clone the repository

$ cd /opt/
$ git clone

Install requirements

$ cd /opt/hyperglass-frr/
$ pip3 install -r requirements.txt

Create service account

# useradd hyperglass-frr
# usermod -a -G frrvty hyperglass-frr

Install systemd service

# cp /opt/hyperglass-frr/hyperglass-frr.service.example /etc/systemd/system/hyperglass-frr.service
# systemctl daemon-reload
# systemctl enable hyperglass-frr

Generate API Key

$ cd /opt/hyperglass-frr
$ python3 generate-key
Your API Key is: B3K1ckWUpwNyFU1F
Your Key Hash is: $pbkdf2-sha256$29000$9T5njNFaS6lVag1B6H2vFQ$mLEbQD5kOAgjfZZ1zEVlrke6wE8vBEHzK.zI.7MOAVo

Copy the API Key, in this example B3K1ckWUpwNyFU1F and add it to configuration.toml:

# listen_addr = "*"
# port = 8080
key = "B3K1ckWUpwNyFU1F"

If needed, you can uncomment the listen_addr or port varibales if you need to define a specific listen address or TCP port for hyperglass-frr to run on. For exmaple:

listen_addr = ""
port = 8001
key = "B3K1ckWUpwNyFU1F"

In hyperglass, configure devices.toml to use the Key Hash (in this example $pbkdf2-sha256$29000$9T5njNFaS6lVag1B6H2vFQ$mLEbQD5kOAgjfZZ1zEVlrke6wE8vBEHzK.zI.7MOAVo) as your FRRouting device's password:

address = ""
asn = "65000"
src_addr_ipv4 = ""
src_addr_ipv6 = "2001:db8::1"
credential = "frr_api_router1"
location = "pop1"
display_name = "POP 1"
port = "8080"
type = "frr"
proxy = ""

username = "frr"
password = "$pbkdf2-sha256$29000$9T5njNFaS6lVag1B6H2vFQ$mLEbQD5kOAgjfZZ1zEVlrke6wE8vBEHzK.zI.7MOAVo"

Start hyperglass-frr

# systemctl restart hyperglass-frr
# systemctl status hyperglass-frr


hyperglass-frr should now be active, and you can run a simple test to verify that it is working apart from your main hyperglass implementation:

import json
import requests
query = '{"query_type": "bgp_route", "afi": "ipv4", "target": ""}'
query_json = json.dumps(query)
headers = {'Content-Type': 'application/json', 'X-API-Key': '$pbkdf2-sha256$29000$m9M6R.j9HwMgJGRs7f0/Jw$5HERwfOIn3P0U/M9t5t04SmgRmTzk3435Lr0duqz07w'}
url = ""
output =, headers=headers, data=query_json)
You can’t perform that action at this time.