NAME

Net::BGPdump - Perl extension for libBGPdump

SYNOPSIS

  use Net::BGPdump qw( :all );

  my $io = Net::BGPdump->open($file);

  while (<$io>) {
    next unless $_->{type_id} == BGP_MSG_UPDATE;
    print "TIME: $_->{time}\n";
    print "TYPE: $_->{type}\n";
    printf("FROM: %s AS%d\n", $_->{peer_addr}, $_->{peer_as});
    printf("TO: %s AS%d\n", $_->{dest_addr}, $_->{dest_as});
    print "ORIGIN: $_->{origin}\n";
    print "ASPATH: $_->{as_path}\n";
    print "NEXT_HOP: $_->{next_hop}\n";
    if ($_->{announce}) {
      print "ANNOUNCE\n";
      for my $cidr (@{$_->{announce}}) {
        print "  $cidr\n";
      }
    }
    if ($_->{withdraw}) {
      print "WITHDRAW\n";
      for my $cidr (@{$_->{withdraw}}) {
        print "  $cidr\n";
      }
    }
  }

DESCRIPTION

Net::BGPDump is a perl extension for libBGPdump, a C library designed to help with analyzing dump files produced by Zebra/Quagga or MRT. These include update files as well as table dump (or RIB) files.

The bgpdump library can be found here:

METHODS

The following methods are available to IO objects:

open($filename, %opts)

Opens a bgpdump file produced by Zebra/Quagga or MRT and returns a Net::BGPdump IO object. Files can be uncompressed, gzip or bzip2. Use a filename of '-' for reading STDIN.

The following keyword filtering options are accepted. The constants used for these options are exported via the :const or :all export tags, or individually.

ipv6

Include or exclude records involving IPv6 (default: 1)

ipv4

Include or exclude records involving IPv4 (default: 1)

begin_time
end_time

Exclude records with timestamps < begin_time or >= end_time.

Note: opening and handling more than one table dump file (as opposed to update files) will likely cause problems. See the BUGS section below for more information.

close()

Close the Net::BGPdump IO object.

read()

Return the next record as a hash reference. Records are possibly subject to filtering on ipv6 or time as specified in the open() constructor.

read_msg()

Return the next update record as a hash reference. This limits records to either MRTD or ZEBRA messages and discards things such as keepalive records. Records are possibly subject to filtering on ipv6 or time as specified in the open() constructor.

closed()

Return whether or not the file has been closed.

eof()

Return whether or not the end of the file has been reached.

filename()

Return the filename this IO object is reading.

file_type()

Return the type of file this IO object has opened: 'uncompressed', 'bzip2', or 'gzip'.

records()

Return the total number of records read so far from the file.

parsed_fail()

Return the number of records that have failed to parse so far.

parsed_ok()

Return the number of records successfully poarsed so far.

OPERATORS

IO objects can be used as filehandles, so <$io> works as though read_msg() was called.

ADDITIONAL CONSTANTS

Record types:

  BGPDUMP_TYPE_MRTD_BGP
  BGPDUMP_TYPE_MRTD_TABLE_DUMP
  BGPDUMP_TYPE_TABLE_DUMP_V2
  BGPDUMP_TYPE_ZEBRA_BGP

Record subtypes:

  BGPDUMP_SUBTYPE_MRTD_BGP_NULL
  BGPDUMP_SUBTYPE_MRTD_BGP_UPDATE
  BGPDUMP_SUBTYPE_MRTD_BGP_PREFUPDATE
  BGPDUMP_SUBTYPE_MRTD_BGP_STATE_CHANGE
  BGPDUMP_SUBTYPE_MRTD_BGP_SYNC
  BGPDUMP_SUBTYPE_MRTD_BGP_OPEN
  BGPDUMP_SUBTYPE_MRTD_BGP_NOTIFICATION
  BGPDUMP_SUBTYPE_MRTD_BGP_KEEPALIVE
  BGPDUMP_SUBTYPE_MRTD_BGP_ROUT_REFRESH

  BGPDUMP_SUBTYPE_MRTD_TABLE_DUMP_AFI_IP6
  BGPDUMP_SUBTYPE_MRTD_TABLE_DUMP_AFI_IP6_32BIT_AS
  BGPDUMP_SUBTYPE_MRTD_TABLE_DUMP_AFI_IP
  BGPDUMP_SUBTYPE_MRTD_TABLE_DUMP_AFI_IP_32BIT_AS

  BGPDUMP_SUBTYPE_TABLE_DUMP_V2_PEER_INDEX_TABLE
  BGPDUMP_SUBTYPE_TABLE_DUMP_V2_RIB_IPV4_UNICAST
  BGPDUMP_SUBTYPE_TABLE_DUMP_V2_RIB_IPV4_MULTICAST
  BGPDUMP_SUBTYPE_TABLE_DUMP_V2_RIB_IPV6_UNICAST
  BGPDUMP_SUBTYPE_TABLE_DUMP_V2_RIB_IPV6_MULTICAST
  BGPDUMP_SUBTYPE_TABLE_DUMP_V2_RIB_GENERIC
  BGPDUMP_PEERTYPE_TABLE_DUMP_V2_AFI_IP
  BGPDUMP_PEERTYPE_TABLE_DUMP_V2_AFI_IP6
  BGPDUMP_PEERTYPE_TABLE_DUMP_V2_AS2
  BGPDUMP_PEERTYPE_TABLE_DUMP_V2_AS4

  BGPDUMP_SUBTYPE_ZEBRA_BGP_MESSAGE
  BGPDUMP_SUBTYPE_ZEBRA_BGP_MESSAGE_AS4
  BGPDUMP_SUBTYPE_ZEBRA_BGP_STATE_CHANGE
  BGPDUMP_SUBTYPE_ZEBRA_BGP_STATE_CHANGE_AS4

Message types:

  BGP_MSG_UPDATE
  BGP_MSG_OPEN
  BGP_MSG_NOTIFY
  BGP_MSG_KEEPALIVE
  BGP_MSG_ROUTE_REFRESH_01
  BGP_MSG_ROUTE_REFRESH

The following constants can also be exported:

  BGP_STATE_IDLE
  BGP_STATE_CONNECT
  BGP_STATE_ACTIVE
  BGP_STATE_OPENSENT
  BGP_STATE_OPENCONFIRM
  BGP_STATE_ESTABLISHED

BUGS

* Opening and reading more than one table dump file (as opposed to mere update files) will likely cause a segfault since libbgpdump uses a single global index table each time a file of that type is opened and frees the structure whenever one of the files is closed, even if the other one is still using the index table.

* Corrupt files will cause perl to silently abort when a bad record is encountered and cannot be caught using eval(). This happens when libbgpdump attempts to call the err() function -- there is some sort of name collision with the perl library. Until this is fixed, files must unfortunately be checked ahead of time with gunzip or bunzip2.

COPYRIGHT & LICENSE

Copyright (C) 2015-2016 by Carnegie Mellon University

Use of the Net-BGPdump library and related source code is subject to the terms of the following licenses:

GNU General Public License (GPL) Rights pursuant to Version 2, June 1991 Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013

NO WARRANTY

See GPL.txt and LICENSE.txt for more details.