BGPmon.net WebServices API

The BGPmon.net WebServices API allows you to connect the BGPmon.net monitorings service to your own network management services.
This page contains more information regarding the BGPmon.net WebServices API.

The BGPmon WebServices APi uses the SOAP protocol, this allows you to call BGPmon.net API function from anywhere on the Internet. SOAP messages are XML encoded messages that are transported over HTTP. Many programming languages provide SOAP or XML/RPC libraries, you should be able to use your favourite programming language to interface with the BGPmon.net WebServices API.

Curious and want to play around with the BGPmon.net WebServices API? Try the Generic Soap client at www.soapclient.com and find out which functions are currently available.
Below you'll find a number of examples that should help you getting started. If you have your own example and want to share this with the community, please sent me an email and I'll add it to this page.

Functions

Below you will find a quick overview of the available function. All functions are also described in great detail the WSDL file.

getIPInfo() This function will return a set of information about a prefix or IP address. It has only one argument: an IPv4 or IPv6 address or prefix. It will return the best match prefix (longest prefix match) found in the routing tables. It will also return the prefix descrription, country code, origin AS and Origin AS description.
In case the prefix is announced by multiple Origin ASNs it will return this information for each origin AS.

GetAlerts() this will return all alerst. It has 3 arguments that allow you to filter on type of alerts. The first argument is active, this indicates whether you want all alerts or just the currently active ones. The second argument is days. This indicates how many days back in time you want to go. The last argument is maxcode. This allows you to specify which alarms code you'd like to retrieve. All alarms types are represented by a code, see faq. This argument is an inclusive filter, meaning that if you specify 22 you will receive alerts with code 1 to 22. The returned result is ordered by date and alert_code.

GetAlertDetails() This will return a list of peers and their BGP messages that detected this alert.

GetASname() Will return the name of the ASN. This function has 1 argument AS which is the ASnumber.

GetASPrefixes() returns a list of all prefixes announced by this AS. This function has 1 argument AS which is the ASnumber.

getCountry() Takes a prefix as input and returns the country code. This works for both IPv4 and IPv6. So here you go a free IPv6 Geo Location library.

WSDL

The BGPmon.net API is described in a WSDL file, this file can be found here. A more human readable version can be found here.

Authentication

To access some of the SOAP functions related to your BGPmon.net account you'll have to authenticate. Functions that require authenticataion are: GetAlertDetails() and GetAlerts(); You'll have to add your BGPmon.net email address and password as input parameters, also see the WSDL.

Examples

It's always easier to develop code based on some examples. Below you'll find two examples that make use of the BGPmon.net WebServices API using SOAP. One example is written in Perl and one in PHP.

If you create your own script and you think it might be useful for others then please sent me an email so I can post your script here as well.

Whois interface

There is a whois interace written in perl that uses the getIPInfo() to serve whois queries. The whois interace accepts any IPv4 or IPv6 address/prefix. The whois deamon will return the best match prefix for this address, as well as country code and the origin AS that announces this prefix.

The whois service can be used in verbose mode (default) or with the - m flag. The latter is useful for when the output needs to be parsed by a script. Below you will see an example of how to use this interface


$ whois -h whois.bgpmon.net 8.8.8.8
% This is the BGPmon.net whois Service
% You can use this whois gateway to retrieve information
% about an IP adress or prefix
% We support both IPv4 and IPv6 address.
%
% For more information visit:
% http://bgpmon.net/bgpmonapi.php

Prefix:              8.8.8.0/24
Prefix description:  Google
Country code:        US
Origin AS:           15169
Origin AS Name:      GOOGLE - Google Inc.

This example show the machine readable output. Note that in case of multiple origin ASNs, multiple objects are returned.

$ whois -h whois.bgpmon.net " -m 2001::"
BGP Prefix|CC|Origin AS| Origin AS Name| Prefix Description
2001::/32|unknown|25525|REASONNET-AS Reasonnet IP Networks B.V. number|Proxy-registered route object
2001::/32|unknown|12637|SEEWEB Seeweb Srl|Proxy-registered route object
2001::/32|unknown|12859|NL-BIT BIT BV|Proxy-registered route object
2001::/32|unknown|1257|TELE2|Proxy-registered route object
2001::/32|unknown|6939|HURRICANE - Hurricane Electric, Inc.|Proxy-registered route object
2001::/32|unknown|21155|ASN-PROSERVE ProServe B.V. Networks|Proxy-registered route object
2001::/32|unknown|29259|DE-IABG-TELEPORT IABG Teleport, DE|Proxy-registered route object
2001::/32|unknown|29432|TREX-AS TREX Tampere Region Exchange Oy|Proxy-registered route object
2001::/32|unknown|1741|FUNETAS FUNET autonomous system|Proxy-registered route object

Perl Nagios plugin

This Perl example connects to the BGPmon API and retrieves the requested alerts. Based on the number and type of alerts it will generate a nagios alarm. The nagios script takes a number of arguments, which allow you to filter in type of alarms. Two arguments are mandatory, your email address and password.

The script requires two external libraries, SOAP::Lite.
Please take a look at the code If you are interested in developing your own perl script that utilizes the BGPmon.net API.
Make sure also to read the verbose loop. That demonstrates how to loop through the returned results. It also shows how to retrieve the BGP messages that each peer deteacted.
The Perl script can be found here: Source Code

Usage

BGPmon.net Soap API:: nagios plugin
usage:   ./bgpmon-nagios.pl -l  -p  [-d ] [-n ] [-c ] [-v]
example: ./bgpmon-nagios.pl -l 'demo@bgpmon.net' -p 'demo' -d 3 -n 1 -c 23

[-h]          : Print this message

[-l]   : email address / BGPmon.net login name -l 'andree@bgpmon.net'
              : Mandatory argument.

[-p]   : BGPmon.net password
              : Mandatory argument.

[-d]    : Number of days of data, -d 3 means from now to 3 days ago (default)
              : Optional argument.

[-n]  : flag for active alarms only. 1(default) is active only, 0 also cleared alarms
              : Optional argument.

[-c] : Include alarms up to (inclusive) max code. 
              : default is 22 (all hijacks and more specifics).  Optional argument.

[-v] 	      : Verbose mode, will print all details as well using getAlertDetails()
              : Will also print ASnames using getASName()


Andree Toonk: andree@bgpmon.net  
2009-09-27

PHP BGPmon RSS client example.

This is an simple example demonstrating how easy it is to use the BGPmon.net API in php.

This client uses the BGPmon.net API to represent the results in RSS format. You can use this to display the results in your favorite RSS reader or in a external application that takes RSS input.
To use this example you'll need to add your BGPmon email and password to the code. You'll need to use PHP5 for this script, as this version has native support for SOAP.

The PHP RSS example has 3 optional arguments:
* days: number of days you want the alarms for. 3 meaning from now to 3 days ago
* active: 0 or 1, indicating if you want active alarms only (default) or all alerts.
* maxcode: Include alarms up to (inclusive) max code

This is the example at work for the bgpmon demo account: http://bgpmon.net/rssclient.php?days=600&active=0&maxcode=100
The source code for this script can be found below:


<?php
 
 /////////////////////////////////////////////////////
 // PHP RSS client demonstrating the BGPmon SOAP API
 // Andree Toonk, September 2009
 /////////////////////////////////////////////////////
 
 // Configuration Part
 $email = 'demo@bgpmon.net';
 $passw = 'demo';
 $wsdl_url = "http://bgpmon.net/soap/server.php?wsdl";
 // End Config
 
 // Set defaults:
 $days = 3;
 $maxcode = 100;
 $active = 1;
 
 if ((isset($_GET['days'])) && (is_numeric($_GET['days']))) {
     $days = $_GET['days'];
 } 
 if ((isset($_GET['maxcode'])) && (is_numeric($_GET['maxcode']))) {
     $maxcode = $_GET['maxcode'];
 } 
 if ((isset($_GET['active'])) && (is_numeric($_GET['active'])) && ($_GET['active'] == 0)) {
     $active = 0;
 } 
 
 // Start rendering RSS headers
 
 header('Content-type: text/xml');
 ?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
 <channel>
 <title>BGPmon.net Alerts</title>
 <description>BGPmon.net Alerts</description>
 <link>http://bgpmon.net/</link>
 <?
 
 // Now we make the call, to read the WSDL file
 $client = new SoapClient($wsdl_url);
 
 // Next step is to call the getAlerts function:
 // Also use getASName() to retrieve AS names for origin and transit AS
 try {
 foreach ($client->getAlerts($email,$passw,$active,$days,$maxcode) as $key => $value) {
     print "<item>";
     print "\t<title>" . htmlentities("Code: $value->alert_code for your prefix: $value->monitored_network")." </title>\n";
     $body = "Code:$value->alert_code<br>";
     $body .= "Your prefix: $value->monitored_network (AS$value->monitored_AS)<br>";
     $body .= "Update time: $value->date<br>";
     $body .= "Detected by #peers: $value->no_peers<br>";
     $body .= "Detected prefix: $value->announced_prefix<br>";
     $body .= "Announced by: $value->origin_AS (".  $client->getASName($value->origin_AS) . ")<br>";
     $body .= "Transit AS : $value->transit_AS (".  $client->getASName($value->transit_AS) . ")" ;
     $url = "http://www.bgpmon.net/alerts.php?details&amp;alert_id=$value->alert_id";
     print "\t<description> <![CDATA[$body]]></description>\n";
     print "\t<link>$url</link>\n";
     print "\t<guid isPermaLink=\"false\">$url</guid>\n";
     print "\t<pubDate> $value->date </pubDate>\n";
     print "</item>\n";
 }
 print "</channel></rss>";
 
 } catch (SoapFault $exception) {
     print "<item><title>SOAP Fault</title><description><pre> $exception</pre>
     </description><guid
     isPermaLink=\"false\">$url</guid></item></channel></rss>";
 } 
 // That's all folks
 ?>