_pybgpstream

This document describes the API of the _pybgpstream module, a low-level (almost) direct interface to the C libbgpstream library.

BGPStream

class _pybgpstream.BGPStream

The BGP Stream class provides a single stream of BGP Records.

add_filter(type, value)

Add a filter to an unstarted BGP Stream instance. Only those records/elems that match the filter(s) will be included in the stream.

If multiple filters of the same type are added, a record/elem is considered a match if it matches any of the filters. E.g. if add_filter(‘project’, ‘routeviews’) and add_filter(‘project’, ‘ris’) are used, then records that are from either the Route Views, or the RIS project will be included.

If multiple filters of different types are added, a record/elem is considered a match if it matches all of the filters. E.g. if add_filter(‘project’, ‘routeviews’) and add_filter(‘record-type’, ‘updates’) are used, then records that are both from the Route Views project, and are updates will be included.

project, collector, and record-type filter BGP records, whereas peer-asn, prefix, and community filter BGP elems. The prefix filter selects BGP elems related to the prefix or more specifics. The community filter is specified as a asn:value formatted string, the user can specify the ASn or the value and leave the other field not specified using the *. E.g. if add_filter(‘community’, ‘*:300’) is used then all the BGP elems having at least one community with value 300 will be included.

Parameters:
  • type (str) – The type of the filter, can be one of project, collector, record-type, peer-asn, prefix, community
  • value (str) – The value of the filter
Raises:
  • TypeError – if the type or value are not basestrings
  • ValueError – if the type is not valid
add_rib_period_filter(period)

Set the RIB period filter for the current stream. Configure the minimum BGP time interval between two consecutive RIB files that belong to the same collector. This information can be modified once the stream has started.

Parameters: period (int) – the period (in seconds)
Raises TypeError:
  if the start or end period is not int
add_interval_filter(start, stop)

Add an interval filter to an unstarted BGP Stream instance. Only those records that fall within the given interval will be included in the stream. Setting the stop parameter to 0 will enable live mode and effectively set an endless interval.

If multiple interval filters are added, then a record is included if it is inside any of the intervals.

Parameters:
  • start (int) – The start time of the interval (inclusive)
  • stop (int) – The end time of the interval (inclusive)
Raises TypeError:
 

if the start or end times are not ints

get_data_interfaces()

Gets a list of information about the available data interfaces. Each item in the list will have three fields: id, name, and description. The value of the name field can be used in subsequent calls to set_data_interface().

set_data_interface(interface_name)

Sets the data interface to stream BGP Records from.

Parameters:

interface_name (str) – The data interface to use, must be one of the name fields in the result of get_data_interfaces().

Raises:
  • TypeError – if the interface is not a basestring
  • ValueError – if the given interface is not valid
get_data_interface_options(interface_name)

Gets a dictionary of options for the given data interface. (Availabie data interfaces may be discovered using get_data_interfaces().)

Parameters:

interface_name (str) – The data interface to use, must be one of the name fields in the result of get_data_interfaces().

Returns:

A dictionary of options for the given data interface.

Return type:

dictionary

Raises:
  • TypeError – if interface_name is not a basestring
  • ValueError – if the given interface name is not valid
set_data_interface_option(interface_name, opt_name, opt_value)

Sets a data interface option.

Parameters:
  • interface_name (str) – The data interface to use, must be one of the name fields in the result of get_data_interfaces().
  • opt_name (str) – The option to set, must be one of the name fields in the result of get_data_interface_options() for the given data interface.
  • opt_value (str) – The option value to set.
Raises:
  • TypeError – if any of the parameters are not basestrings
  • ValueError – if the given data interface, or option name is not valid
set_live_mode()

Enables live mode. When this option is used, the stream will block waiting for new data to arrive if the end of the interval has not been reached. In this way a stream can be used to monitor realtime data (i.e. a call to get_next_record() will block until new data is available.)

start()

Starts the stream. This method must be called after all configuration options have been set (e.g. filters, options, etc.), and before the first call to get_next_record().

get_next_record(record)

Retrieves the next record from the stream, and stores the result into the given record object. Passing a record instance helps reduce the allocation overhead of this method. If the records are processing independently of each other, then the same record instance may be used for subsequent calls to this method. If the blocking mode is enabled, then this method may block if the stream reaches the end of the data available in the archive, and the end of the interval(s) has not been reached.

Parameters: record (BGPRecord) – A record instance into which the next record from the stream is stored.
Returns: True if there are more records in the stream, False if the end of the stream has been reached.
Return type: bool
Raises RuntimeError:
  if the provided record instance is invalid, if the stream has not been started, or if the stream encounters an error retrieving the next record

BGPRecord

class _pybgpstream.BGPRecord

The BGP Record class represents a single record obtained from a BGP Stream.

All attributes are read-only.

project

The name of the project that created the record. (basestring, readonly)

collector

The name of the collector that created the record. (basestring, readonly)

type

The type of the record, can be one of ‘update’, ‘rib’, or ‘unknown’. (basestring, readonly)

dump_time

The time associated with the dump that contained the record (e.g. the beginning of the MRT file that the record was found in.) (int, readonly)

time

The time that the record represents (i.e. the time the record was generated by the collector). (int, readonly)

status

The status of the record, can be one of ‘valid’, ‘filtered-source’, ‘empty-source’, ‘corrupted-source’, ‘unknown’. (basestring, readonly)

dump_position

The position that this record was found in the dump, can be one of ‘start’, ‘middle’, ‘end’, ‘unknown’. (basestring, readonly)

get_next_elem()

Get the next BGPElem from this record. Will return None when all the elems have been read.

Returns: a BGPElem object, or None if there are no more elems to read.
Return type: BGPElem
Raises RuntimeError:
  if a BGPElem object could not be created

BGPElem

class _pybgpstream.BGPElem

The BGP Elem class represents a single element obtained from a BGP Record instance using the BGPRecord.get_next_elem() method.

All attributes are read-only.

type

The type of the element, can be one of ‘rib’, ‘announcement’, ‘withdrawal’, ‘peerstate’, ‘unknown’. (basestring, readonly)

time

The time that the element represents. (int, readonly)

peer_address

The IP address of the peer that this element was received from. (basestring, readonly)

peer_asn

The ASN of the peer that this element was received from. (int, readonly)

fields

A dictionary of fields that differ depending on the type of the element. (dict, readonly)

Fields for each type are:
  • rib, announcement:
    • ‘next-hop’: The next-hop IP address (basestring)
    • ‘as-path’: The AS path (basestring)
    • ‘prefix’: The prefix (basestring)
    • ‘communities’: The communities (a list of dictionaries, each one representing a community; each dictionary has the asn and the value keys)
  • withdrawal
    • ‘prefix’: The prefix (basestring)
  • peerstate
    • ‘old-state’: The old state of the peer, can be one of ‘idle’, ‘connect’, ‘active’, ‘open-sent’, ‘open-confirm’, ‘established’. (basestring)
    • ‘new-state’: The new state of the peer, shares the same possible values as old-state. (basestring)