Skip to content
hyperglass API for BIRD
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.
.gitignore added BIRD 2.0 support Jun 23, 2019
.pylintrc Add contributing guidelines Jun 24, 2019
LICENSE Add README warning & License Jun 23, 2019 README updates Jun 24, 2019

hyperglass-bird supports both BIRD versions 1.6 and 2.0.


hyperglass-bird is a restful API for the BIRD Internet Routing Daemon, for use by hyperglass. hyperglass-bird ingests an 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 in version 1.6, BIRD's birdc and birdc6 are used to get the output. For example:

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

Would construct (by default) birdc6 -r show route all where 2606:4700:4700::/48 ~ net, execute the command, and return the output as a string.

BGP AS Path and Community queries are converted from "standard" hyperglass-supported syntax to BIRD's syntax:

  "query_type": "bgp_aspath",
  "afi": "dual",
  "target": "_65000$"

Would construct birdc -r show route all where bgp_path ~ [= * 65000 =] and birdc6 -r show route all where bgp_path ~ [= * 65000 =] and concatenate the output for both commands.


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


If using BIRD 1.6, hyperglass-bird requires that bird6 and birdc6 be fully functional, even if IPv6 is not used.

Clone the repository

$ cd /opt/
$ git clone

Install requirements

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

Install systemd service

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

Update Permissions

# chown -R bird:bird /opt/hyperglass-bird

Generate API Key

$ cd /opt/hyperglass-bird
$ 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-bird 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 = "bird_api_router1"
location = "pop1"
display_name = "POP 1"
port = "8080"
type = "bird"
proxy = ""

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

Start hyperglass-bird

# systemctl restart hyperglass-bird
# systemctl status hyperglass-bird


hyperglass-bird 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)
>>> print(output.text)
You can’t perform that action at this time.