GitHub

DB_REST - OpenBMP Database REST Service

Simple DB REST interface to the OpenBMP database. This is an example of how to interact with the database.

Demo server is still in development.

JSON

All queries have the following JSON syntax/output:

{ <table_name> : {
    	cols: <number of columns>,
 		data: [ { <column name>:<value>, ... }, 
 		        ... 
 		      ],
		size: <total number of rows in result>,
        queryTime_ms: <ms value - the duration in ms>,
        fetchTime_ms: <ms value - the duration in ms>
        }
}

REST API's

Below documentations the various REST URL/API's.

BASE URL is always /db_rest/v1

DEMO Server Base URL is http://demo.openbmp.org:8001/db_rest/v1

Routers

BMP Router view.

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/routers	withgeo - Adds the geo location columns for router based on the router IP address limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns the list of BMP routers currently known in the database	Demo
GET	/db_rest/v1/routers/status/count		Returns a count of DOWN and UP BMP routers	Demo
GET	/db_rest/v1/routers/status/up		Returns the BMP routers that are up	Demo
GET	/db_rest/v1/routers/status/down		Returns the BMP routers that are down	Demo

BGP Peers

BGP Peer view.

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/peer	withgeo - Adds the geo location columns for the peer based on the peer IP address limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns a list of BGP peers	Demo
GET	/db_rest/v1/peer/localip/{localIP}	withgeo - Adds the geo location columns for the peer based on the peer IP address limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns a list of BGP peers by local IP address	Demo
GET	/db_rest/v1/peer/remoteip/{remoteIP}	withgeo - Adds the geo location columns for the peer based on the peer IP address limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns a list of BGP peers by remote/peer IP address	Demo
GET	/db_rest/v1/peer/asn/{Peer ASN}	withgeo - Adds the geo location columns for the peer based on the peer IP address limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns a list of BGP peers by Peer ASN	Demo
GET	/db_rest/v1/peer/type/count		Returns peer counts by status IP version type	Demo
GET	/db_rest/v1/peer/type/count/router		Returns a list of routers with count of peers by IP Type	Demo
GET	/db_rest/v1/peer/type/v4	withgeo - Adds the geo location columns for the peer based on the peer IP address	Returns list of IPv4 peers	Demo
GET	/db_rest/v1/peer/type/v6	withgeo - Adds the geo location columns for the peer based on the peer IP address	Returns list of IPv6 peers	Demo
GET	/db_rest/v1/peer/status/count		Returns peer counts by peer status	Demo
GET	/db_rest/v1/peer/status/up	withgeo - Adds the geo location columns for the peer based on the peer IP address	Returns a list of BGP peers that are UP	Demo
GET	/db_rest/v1/peer/status/down	withgeo - Adds the geo location columns for the peer based on the peer IP address	Returns a list of BGP peers that are DOWN	Demo
GET	/db_rest/v1/peer/prefix		Returns a list of BGP peers and their Pre-Policy and Post-Policy RIB counts.	Demo
GET	/db_rest/v1/peer/prefix/{peerIP}		Returns a list of BGP peers and their Pre-Policy and Post-Policy RIB counts by peer address	Demo
GET	/db_rest/v1/peer/router/{Router IP}	withgeo - Adds the geo location columns for the peer based on the peer IP address limit - Max results to return orderby - SQL ORDER BY clause	Returns a list of BGP peers based on Router IP or Router Name	Demo

RIB

Unicast IPv4/IPv6 RIB/routes view.

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/rib	limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns the RIB entries. Default limit is 1000. Should use WHERE clause to filter or use one of the below URI's instead.	[Demo](http://demo.openbmp.org:8001/db_rest/v1/rib?where=PrefixLen >= 8 and PrefixLen <= 9)
GET	/db_rest/v1/rib/asn/{ASN}	limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns a list of prefixes by Origin ASN.	Demo
GET	/db_rest/v1/rib/asn/{ASN}/count	limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns a list of prefixes by Origin ASN.	Demo
GET	/db_rest/v1/rib/prefix/{Prefix}	limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns a list of prefixes by Prefix starts with.	Demo
GET	/db_rest/v1/rib/prefix/{Prefix}/{length}	limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause	Returns a list of prefixes by Prefix/Length.	Demo
GET	/db_rest/v1/rib/lookup/{IP}	where - SQL WHERE clause orderby - SQL ORDER BY clause aggregates - Set to return aggregates distinct - Set to return only a distinct list of prefixes	Finds the longest match prefix based on the IP (more specific) supplied.	Demo
GET	/db_rest/v1/rib/history/{prefix}/{length}	limit - Max results to return where - SQL WHERE clause orderby - SQL ORDER BY clause days number of days to include in search.	Returns the RIB history for a given prefix/length. Default limit is 1000. Can use WHERE clause to filter on PeerName to restrict to a specific peer.	Demo

Upstream BGP ASN's (peers)

List the upstream ASN's for the given ASN. This query simply looks at the AS PATH and parses out the LEFT most ASN next to the ASN provided.

For example

AS PATH 1 = 100 200 300 400 500 600 700
AS PATH 2 = 40 50 60 70 400 888 600 700
A query on ASN = 400 returns { 300, 70 } since both of those ASN's are the left most ASN's next to ASN 400.

Method	URI	Description	Demo URL
GET	/db_rest/v1/upstream/{asn}	List all upstream ASN's for the given ASN	Demo
GET	/db_rest/v1/upstream/{asn}/count	List all upstream ASN's for the given ASN and count the number of distinct prefixes (each prefix/len + peer is counted)	Demo
GET	/db_rest/v1/upstream/{asn}/peer/count	List all upstream ASN's for the given ASN and count the number of distinct prefixes per peer	Demo

Downstream BGP ASN's (peers)

List the downstream ASN's for the given ASN. This query simply looks at the AS PATH and parses out the RIGHT most ASN next to the ASN provided. This will return a an empty ASN which is for itself.

For example

AS PATH 1 = 100 200 300 400 500 600 700
AS PATH 2 = 40 50 60 70 400 888 600 700
A query on ASN = 400 returns { 500, 888 } since both of those ASN's are the right most ASN's next to ASN 400.

Method	URI	Description	Demo URL
GET	/db_rest/v1/downstream/{asn}	List all downstream ASN's for the given ASN	Demo
GET	/db_rest/v1/downstream/{asn}/count	List all downstream ASN's for the given ASN and count the number of distinct prefixes (each prefix/len + peer is counted)	Demo
GET	/db_rest/v1/downstream/{asn}/peer/count	List all downstream ASN's for the given ASN and count the number of distinct prefixes per peer	Demo
GET	/db_rest/v1/downstream/peer/{peerHashId}	Distinctly lists the ASN's that are directly to the right of the peer ASN. E.g. ASPath's { "10 20, 30", "10 9 8"} would produce a list containing 20 and 9 since those ASNs are to the right of the peering ASN of 10. Each AS will have the ASN name, organization, and country.	Demo

Updates Over Time

Each update is logged. Attributes that vary by router/peer/prefix will get an update log entry.

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/updates/top	limit - Max results to return hours - Number of hours to include in top	Return the top prefixes by number of updates in past 'hours'. Limit defaults to 25 and hours defaults to 2.	Demo
GET	/db_rest/v1/updates/peer/{peerHashId}/top	limit - Max results to return hours - Number of hours to include in top	For given peer, return the top prefixes by number of updates in past 'hours'. Limit defaults to 25 and hours defaults to 2.	Demo
GET	/db_rest/v1/updates/top/interval/{minutes}	minutes - Interval in minutes limit - Max results to return hours - Number of hours to include in top	Return the count of updates per interval for up to max limit size. Limit defaults to 25.	Demo
GET	/db_rest/v1/updates/peer/{peerHashId}/top/interval/{minutes}	minutes - Interval in minutes limit - Max results to return hours - Number of hours to include in top	For given peer, return the count of updates per interval for up to max limit size. Limit defaults to 25.	Demo

Withdrawns Over Time

Each prefix withdrawn is logged.

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/withdrawns/top	limit - Max results to return hours - Number of hours to include in top	Return the top prefixes by number of prefixes withdrawn in past 'hours'. Limit defaults to 25 and hours defaults to 2.	Demo
GET	/db_rest/v1/withdrawns/peer/{peerHashId}/top	limit - Max results to return hours - Number of hours to include in top	For given peer, return the top prefixes by number of prefixes withdrawn in past 'hours'. Limit defaults to 25 and hours defaults to 2.	Demo
GET	/db_rest/v1/withdrawns/top/interval/{minutes}	minutes - Interval in minutes limit - Max results to return hours - Number of hours to include in top	Return the count of updates per interval for up to max limit size. Limit defaults to 25.	Demo
GET	/db_rest/v1/withdrawns/peer/{peerHashId}/top/interval/{minutes}	minutes - Interval in minutes limit - Max results to return hours - Number of hours to include in top	Return the count of updates per interval for up to max limit size. Limit defaults to 25.	Demo

AS Stastistics

Per ASN statistics

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/asn_stats	limit - Max results to return	Returns a list of all active ASN's in the DB	Demo
GET	/db_rest/v1/asn_stats/{asn}	limit - Max results to return	Returns the AS statistics for the provided ASN	Demo
GET	/db_rest/v1/asn_stats/ipv4	IPv4 limit - Max results to return topTransit= Get the top transit prefixes topOrigin= Get the top originating ASN's	Get the top ASN's originating prefixes or that are transit to other ASN's	Demo
GET	/db_rest/v1/asn_stats/ipv6	IPv6 limit - Max results to return topTransit= Get the top transit prefixes topOrigin= Get the top originating ASN's	Get the top ASN's originating prefixes or that are transit to other ASN's	Demo

Whois ASN Information

Whois information for ASN's

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/whois/asn	where - SQL WHERE clause limit - Max results to return	Returns all whois information	[Demo](http://demo.openbmp.org:8001/db_rest/v1/whois/asn?where=org_name like%20'%cisco%')
GET	/db_rest/v1/whois/asn/count	where - SQL WHERE clause	Returns the count of ASN matches based on WHERE clause	[Demo](http://demo.openbmp.org:8001/db_rest/v1/whois/asn/count?where=org_name like%20'%cisco%')
GET	/db_rest/v1/whois/asn/{asn}	where - SQL WHERE clause	Returns the whois info for the given ASN	Demo

Geolocation IP Information

Geolocation IP address information from DB-IP, IP2Location, or MaxMind.

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/geoip/{IP}	where - SQL WHERE clause	Returns the geolocation data based on the IP supplied	Demo

BGP-LS Information

BGP-LS general/raw link state DB information

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/linkstate/nodes	where - SQL WHERE clause limit - Limit the number of results orderby - Order by clause	Returns the list of link state nodes	Demo
GET	/db_rest/v1/linkstate/nodes/peer/{peerHashId}	where - SQL WHERE clause limit - Limit the number of results orderby - Order by clause	Returns the list of link state nodes for the given peer hash id Get the peer hash ID by listing the nodes.	Demo
GET	/db_rest/v1/linkstate/nodes/peer/{peerHashId}/{nodeHashId}	where - SQL WHERE clause limit - Limit the number of results orderby - Order by clause	Returns the the specific node by peer hash id and node hash id Get the node and peer hash ID by listing the nodes.	Demo
GET	/db_rest/v1/linkstate/links	where - SQL WHERE clause limit - Limit the number of results orderby - Order by clause	Returns the list of link state links	Demo
GET	/db_rest/v1/linkstate/links/peer/{peerHashId}	where - SQL WHERE clause limit - Limit the number of results orderby - Order by clause	Returns the list of link state links for given peer hash id	Demo
GET	/db_rest/v1/linkstate/prefixes	where - SQL WHERE clause limit - Limit the number of results orderby - Order by clause	Returns the list of link state prefixes	Demo
GET	/db_rest/v1/linkstate/prefixes/peer/{peerHashId}	where - SQL WHERE clause limit - Limit the number of results orderby - Order by clause	Returns the list of link state prefixes for given peer hash id	Demo

BGP-LS SPF Information

BGP-LS shortest path first (SPF) information.

Running any GET below will result in a SPF generated routing table rooted at the given router id. IS-IS will have a router ID as well, so we use router id regardless of OSPF or IS-IS. This keeps it consistent between the two.

In order to ensure that fast/repeated queries do not result in running SPF's when there's no change, there is a built in timer that will only generate a new RIB for the given protocol and router ID at most every 15 seconds.

SPF's are calculated on a per-BGP-peer basis. A single BGP peer provides all link state information so the SPF does not need to span multiple bgp-ls peers. You should first run a GET /db_rest/v1/linkstate/nodes to identify which peer and node you would like to run the SPF against.

Method	URI	Parameters	Description	Demo URL
GET	/db_rest/v1/linkstate/spf/peer/{peerHashId}/ospf/{routerId}	where - SQL WHERE clause limit - Limit the number of results orderby - Order by clause	Runs OSPF SPF and generates a RIB for the given bgp-ls peer and router-id. The generated RIB is returned.	Demo
GET	/db_rest/v1/linkstate/spf/peer/{peerHashId}/isis/{routerId}	where - SQL WHERE clause limit - Limit the number of results orderby - Order by clause	Runs IS-IS SPF and generates a RIB for the given bgp-ls peer and router-id. The generated RIB is returned.	Demo

Drawing the topology

The returned result will contain two path columns/fields.

path_hash_ids - Comma delimited list of node hash ID's
path_router_ids - Comma delimited list of node router ID's

The first entry in the path will always be the root node. For example, if the SPF was ran for 200.1.1.1, then 200.1.1.1 will be the first path entry. The last entry in the path will always be the node where the prefix originates.

{
   prefix: "100.1.1.4/32",
   Type: "0",
   metric: 21,
   src_router_id: "100.1.1.4",
   nei_router_id: "100.1.1.3",
   path_router_ids: "100.1.1.2,100.1.1.3,100.1.1.4",
   path_hash_ids: "0ec92251bd07fc3a917ace4fcc564c83,d9ea9b11a9c9e2a9e91acfb91711f4a8,af17bf43842d5bac5702c5971334cce0",
   neighbor_addr: "192.168.1.10",
   peer_hash_id: "54ecaeeec115457cbce466ff48857aa7"
}

Build

Source is available in Github

Before building, edit the src/main/webapp/META-INF/context.xml file and change the settings to match your DB install (username, password, and hostname).

To build the WAR file, run mvn clean package

You have to have maven version 3 installed. To install maven see maven3

Install

To install, simply copy the db_rest.war file to the <tomcat>/webapps directory.

Name		Name	Last commit message	Last commit date
Latest commit History 141 Commits
src/main		src/main
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pom.xml		pom.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

DB_REST - OpenBMP Database REST Service

JSON

REST API's

Routers

BGP Peers

RIB

Upstream BGP ASN's (peers)

For example

Downstream BGP ASN's (peers)

For example

Updates Over Time

Withdrawns Over Time

AS Stastistics

Whois ASN Information

Geolocation IP Information

BGP-LS Information

BGP-LS SPF Information

Drawing the topology

Build

Install

About

Releases

Packages

Languages

License

BinaryDevil/db_rest

Folders and files

Latest commit

History

Repository files navigation

DB_REST - OpenBMP Database REST Service

JSON

REST API's

Routers

BGP Peers

RIB

Upstream BGP ASN's (peers)

For example

Downstream BGP ASN's (peers)

For example

Updates Over Time

Withdrawns Over Time

AS Stastistics

Whois ASN Information

Geolocation IP Information

BGP-LS Information

BGP-LS SPF Information

Drawing the topology

Build

Install

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages