BGPCorsaro

BGPCorsaro is a command line tool that allow the user to process a BGP stream of data using plugins. The tool computes time intervals of fixed length (see the -i option) starting from a sorted stream of BGP records and systematically sends the following signals to the active plugins:

  • interval-start - a new interval starts,
  • new record - there is a new BGP record to process that belongs to the current interval,
  • interval-end - the current interval is finished.

BGPCorsaro is an interval driven tool with a modular architecture based on plugins (that can be run in cascade).

Plugins can be either:

  • Stateless: e.g., performing classification and tagging of BGP records; plugins following in the pipeline can use such tags to inform their processing.

  • Stateful: e.g., extracting statistics or aggregating data that are output at the end of each time bin. Since libBGPStream provides a sorted stream of records, BGPCorsaro can easily recognize the end of a time bin even when processing data from multiple collectors.

See the BGPStream technical report for an in-depth discussion of the architecture of BGPCorsaro

Usage

The BGPCorsaro tools requires the user to specify the stream time interval and a template to generate output files.

usage: bgpcorsaro -w <start>[,<end>] -O outfile [<options>]

data interface and stream filter options

   -d <interface> use the given bgpstream data interface to find available data
                   available data interfaces are:
       broker       Retrieve metadata information from the BGPStream Broker service (default)
       singlefile   Read a single mrt data file (a RIB and/or an update)
       csvfile      Retrieve metadata information from a csv file
       sqlite       Retrieve metadata information from a sqlite database
   -o <option-name,option-value>*
                  set an option for the current data interface.
                  use '-o ?' to get a list of available options for the current
                  data interface. (data interface can be selected
                  using -d)
   -p <project>   process records from only the given project (routeviews, ris)*
   -c <collector> process records from only the given collector*
   -t <type>      process records with only the given type (ribs, updates)*
   -w <start>[,<end>]
                  process records within the given time window
                    (omitting the end parameter enables live mode)*
   -P <period>    process a rib files every <period> seconds (bgp time)
   -j <peer ASN>  return valid elems originated by a specific peer ASN*
   -k <prefix>    return valid elems associated with a specific prefix*
   -y <community> return valid elems with the specified community*
                  (format: asn:value, the '*' metacharacter is
                  recognized)
    -l            enable live mode (make blocking requests for BGP records)
                  allows bgpcorsaro to be used to process data in real-time

The default data interface is the broker. Information about available collectors and the associated time intervals are available at the Data Providers page.

interval options

   -i <interval>  distribution interval in seconds (default: 60)
   -a             align the end time of the first interval
   -g <gap-limit> maximum allowed gap between packets (0 is no limit) (default: 0)
   -L             disable logging to a file

plugin options

    -x <plugin>    enable the given plugin (default: all)*
                   available plugins:
                    - pfxmonitor
                    - pacifier
                    - asmonitor
                   use -p "<plugin_name> -?" to see plugin options

logging options

   -n <name>      monitor name (default: localhost)
   -O <outfile>   use <outfile> as a template for file names.
                   - %X => plugin name
                   - %N => monitor name
                   - see man strftime(3) for more options
   -r <intervals> rotate output files after n intervals
   -R <intervals> rotate bgpcorsaro meta files after n intervals

(The * denotes an option that can be given multiple times.)


Available Plugins

Prefix Monitor -x pfxmonitor

Prefix Monitor is a stateful plugin that monitors prefixes overlapping with a given set of IP address ranges. For each BGPStream record, the plugin:

  1. selects only the RIB and Updates dump records related to prefixes that overlap with the given IP address ranges.
  2. tracks, for each <prefix, VP> pair, the ASN that originated the route to the prefix. At the end of each time bin, the plugin outputs the timestamp of the current bin, the number of unique prefixes identified and, the number of unique origin ASNs observed by all the VPs.

The pfxmonitor plugin requires the user to specify one or more prefixes to monitor. Such prefixes can be provided using the -l command line option repeatedly, or they can be given in a file using -L (one prefix per line).

plugin usage: pfxmonitor -l <pfx> -L<prefix-file>
       -l <prefix>        prefix to monitor*
       -L <prefix-file>   read the prefixes to monitor from file*
       -M                 consider only more specifics (default: false)
       -n <peer_cnt>   minimum number of unique peers' ASNs to declare prefix visible (default: 10)
       -m <prefix>        metric prefix (default: bgp)
       -i <name>          IP space name (default: ip-space)

By default, pfxmonitor keeps track of all the prefixes that overlap with at least one of the prefixes provided in input. If the user is interested only in the cases in which the same prefixes are announced or more specifics are announced, then she/he should use the -M option.

The -n option specifies the minimum number of unique peers' ASNs to declare prefix visible. In detail, a pair <prefix,origin ASn> is taken into account (for the computation of the output metrics) if and only if the same pair <prefix,origin ASn> is observed by at least peer_cnt unique peer ASNs.


-m and -i plugin options modify the metrics generated by the plugin, specifically, they change the following fields:

<metric-prefix>.pfxmonitor.<ip-space-name>.prefixes_cnt 1 1445306400
<metric-prefix>.pfxmonitor.<ip-space-name>.origin_ASns_cnt 1 1445306400


AS Monitor -x asmonitor

AS Monitor is a stateful plugin that monitors the prefixes that are announced by one or more AS numbers, and the prefixes and origins associated with overlapping IP address ranges. For each BGPStream record, the plugin:

  1. selects only the RIB and Updates dump records related to prefixes that are announced by the given AS numbers, monitored pfxs.
  2. tracks, for each <prefix, VP> pair, the ASN that originated the route to a prefix that overlaps with at least one monitored pfxs. At the end of each time bin, the plugin outputs the timestamp of the current bin, the number of unique prefixes identified and, the number of unique origin ASNs observed by all the VPs.

The asmonitor plugin requires the user to specify one or more AS numbers to monitor. Such ASns can be provided using the -a command line option repeatedly, or they can be given in a file using -A (one ASn per line).

plugin usage: asmonitor -a <asn> [options]
       -m <prefix>        metric prefix (default: bgp)
       -a <asn>           ASn to monitor*
       -A <asns-file>     read the ASn to monitor from file*
       -M                 consider only more specifics (default: false)
       -w <pfx-window>    how long a prefix is to be considered valid for monitoring purposes (default: 86400 s)
       -n <peer_cnt>      minimum number of unique peers' ASNs to declare prefix visible (default: 10)
       -i <name>          IP space name (default: ip-space)

By default, asmonitor keeps track of all the prefixes that overlap with at least one of the prefixes announced by one of the ASns provided in input. If the user is interested only in the cases in which the same prefixes are announced or more specifics are announced, then she/he should use the -M option.

The -n option specifies the minimum number of unique peers' ASNs to declare prefix visible. In detail, a pair <prefix,origin ASn> is taken into account (for the computation of the output metrics) if and only if the same pair <prefix,origin ASn> is observed by at least peer_cnt unique peer ASNs.


-m and -i plugin options modify the metrics generated by the plugin, specifically, they change the following fields:

<metric-prefix>.asmonitor.<ip-space-name>.v4.prefixes_cnt 20 1445306400
<metric-prefix>.asmonitor.<ip-space-name>.v4.overlapping_prefixes_cnt 0 1445306400
<metric-prefix>.asmonitor.<ip-space-name>.v4.origin_ASN_cnt 0 1445306400
<metric-prefix>.asmonitor.<ip-space-name>.v6.prefixes_cnt 2 1445306400
<metric-prefix>.asmonitor.<ip-space-name>.v6.overlapping_prefixes_cnt 0 1445306400
<metric-prefix>.asmonitor <ip-space-name>.v6.origin_ASN_cnt 0 1445306400


Pacifier -x pacifier

Documentation coming soon...