bgpstream.h¶

Public Macros

BGPSTREAM_MAJOR_VERSION¶

BGPSTREAM_MID_VERSION¶

BGPSTREAM_MINOR_VERSION¶

BGPSTREAM_FOREVER¶

Used to specify an interval that never ends (i.e., when processing in live mode).

Public Opaque Data Structures

typedef struct bgpstream bgpstream_t¶

Opaque handle that represents a BGP Stream instance.

Public Enums

enum bgpstream_filter_type_t¶

The type of the filter to be applied.

Values:

BGPSTREAM_FILTER_TYPE_PROJECT¶

Filter records based on associated project (e.g.

‘ris’)

BGPSTREAM_FILTER_TYPE_COLLECTOR¶

Filter records based on collector (e.g.

‘rrc01’)

BGPSTREAM_FILTER_TYPE_ROUTER¶

Filter records based on router (e.g.

‘route-views.routeviews.org’)

BGPSTREAM_FILTER_TYPE_RECORD_TYPE¶

Filter records based on record type (e.g.

‘updates’)

BGPSTREAM_FILTER_TYPE_ELEM_PEER_ASN¶

Filter elems based on peer ASN.

BGPSTREAM_FILTER_TYPE_ELEM_ORIGIN_ASN¶

Filter elems based on peer ASN.

BGPSTREAM_FILTER_TYPE_ELEM_PREFIX¶

Filter elems based on prefix.

BGPSTREAM_FILTER_TYPE_ELEM_COMMUNITY¶

Filter elems based on the community attribute.

BGPSTREAM_FILTER_TYPE_ELEM_PREFIX_EXACT¶

Filter elems based on exact prefix.

BGPSTREAM_FILTER_TYPE_ELEM_PREFIX_MORE¶

Filter elems based on a more specific prefix.

BGPSTREAM_FILTER_TYPE_ELEM_PREFIX_LESS¶

Filter elems based on a less specific prefix.

BGPSTREAM_FILTER_TYPE_ELEM_PREFIX_ANY¶

Filter elems based on any matching prefix, regardless of specificity.

BGPSTREAM_FILTER_TYPE_ELEM_ASPATH¶

Filter elems based on an AS path regex.

BGPSTREAM_FILTER_TYPE_ELEM_EXTENDED_COMMUNITY¶

Filter elems based on an extended community attribute.

BGPSTREAM_FILTER_TYPE_ELEM_IP_VERSION¶

Filter elems based on the IP address version.

BGPSTREAM_FILTER_TYPE_ELEM_TYPE¶

Filter elems based on the element type, e.g.

withdrawals, announcements

BGPSTREAM_FILTER_TYPE_RESOURCE_TYPE¶

Filter records based on resource type (i.e., ‘stream’, or ‘batch’)

enum bgpstream_data_interface_id_t¶

Data Interface IDs.

Values:

_BGPSTREAM_DATA_INTERFACE_INVALID¶

Special “invalid” data interface ID.

BGPSTREAM_DATA_INTERFACE_BROKER¶

Broker data interface.

BGPSTREAM_DATA_INTERFACE_SINGLEFILE¶

Single-file interface.

BGPSTREAM_DATA_INTERFACE_KAFKA¶

Kafka interface.

BGPSTREAM_DATA_INTERFACE_CSVFILE¶

CSV file interface.

BGPSTREAM_DATA_INTERFACE_SQLITE¶

SQLITE file interface.

_BGPSTREAM_DATA_INTERFACE_CNT¶

The number of data interfaces.

Public Data Structures

typedef struct bgpstream_data_interface_info bgpstream_data_interface_info_t¶

Structure that contains information about a BGP Stream Data Interface.

typedef struct struct_bgpstream_data_interface_option bgpstream_data_interface_option_t¶

Structure that represents BGP Stream Data Interface Option.

Public API Functions

bgpstream_t *bgpstream_create(void)¶

Create a new BGP Stream instance.

Return

a pointer to a BGP Stream instance if successful, NULL otherwise

int bgpstream_add_filter(bgpstream_t *bs, bgpstream_filter_type_t filter_type, const char *filter_value)¶

Add a filter in order to select a subset of the bgp data available.

Return

1 if the filter was added successfully, 0 if not.

Parameters

• bs: pointer to a BGP Stream instance to filter
• filter_type: the type of the filter to apply
• filter_value: the value to set the filter to

int bgpstream_parse_filter_string(bgpstream_t *bs, const char *fstring)¶

Parse a filter string and create appropriate filters to select a subset of the BGP data.

Return

1 if the string was parsed successfully, 0 if not.

Parameters

• bs: pointer to a BGP Stream instance to filter
• fstring: the filter string to be parsed.

int bgpstream_add_rib_period_filter(bgpstream_t *bs, uint32_t period)¶

Add a filter to configure the minimum bgp time interval between RIB files that belong to the same collector.

This information can be changed at run time.

Return

1 if the filter was added successfully, 0 if not.

Parameters

• bs: pointer to a BGP Stream instance to filter
• period: time period (if zero, all available RIBs are processed)

int bgpstream_add_recent_interval_filter(bgpstream_t *bs, const char *interval, int islive)¶

Add a filter to select a specific time range starting from now and going back a certain number of seconds, minutes, hours or days.

Intervals may be specified using the format ‘num unit’. The unit can be one of ‘s’, ‘m’, ‘h’ or ‘d’, representing seconds, minutes, hours and days respectively.

For example, an interval of “3 h” will go back three hours and an interval of “45 s” will go back 45 seconds.

Return

1 if the filter was added successfully, 0 if not.

Parameters

• bs: pointer to a BGP Stream instance to filter
• interval: string describing the interval to go back
• islive: if not zero, live data will be provided once all historic data has been fetched.

int bgpstream_add_interval_filter(bgpstream_t *bs, uint32_t begin_time, uint32_t end_time)¶

Add a filter to select a specific time range from the BGP data available.

If end_time is set to BGPSTREAM_FOREVER (0), the stream will be set to live mode, and will process data forever. If no intervals are added, then BGPStream will default to processing every available record, however, this will trigger a run-time error if using the Broker data interface.

Return

1 if the filter was added successfully, 0 if not.

Parameters

• bs: pointer to a BGP Stream instance to filter
• begin_time: the first time that will match the filter (inclusive)
• end_time: the last time that will match the filter (inclusive)

int bgpstream_get_data_interfaces(bgpstream_t *bs, bgpstream_data_interface_id_t **if_ids)¶

Get a list of data interfaces that are currently supported.

Return

the number of elements the the if_ids array

Note

the returned array belongs to BGP Stream. It must not be freed by the user.

Parameters

• bs: pointer to the BGP Stream instance in the returned array
• if_ids: set to a borrowed pointer to an array of bgpstream_data_interface_type_t values

bgpstream_data_interface_id_t bgpstream_get_data_interface_id_by_name(bgpstream_t *bs, const char *name)¶

Get the ID of the data interface with the given name.

Return

the ID of the data interface with the given name, 0 if no matching interface was found

Parameters

• bs: pointer to a BGPStream instance
• name: name of the data interface to retrieve the ID for

bgpstream_data_interface_info_t *bgpstream_get_data_interface_info(bgpstream_t *bs, bgpstream_data_interface_id_t if_id)¶

Get information for the given data interface.

Return

borrowed pointer to an interface info structure

Parameters

• bs: pointer to a BGP Stream instance
• if_id: ID of the interface to get the name for

int bgpstream_get_data_interface_options(bgpstream_t *bs, bgpstream_data_interface_id_t if_id, bgpstream_data_interface_option_t **opts)¶

Get a list of valid option types for the given data interface.

Return

the number of elements in the opts array

Note

the returned array belongs to BGP Stream. It must not be freed by the user.

Parameters

• bs: pointer to a BGP Stream instance
• if_id: ID of the interface to get option names for in the returned array
• opts: set to a borrowed pointer to an array of options

bgpstream_data_interface_option_t *bgpstream_get_data_interface_option_by_name(bgpstream_t *bs, bgpstream_data_interface_id_t if_id, const char *name)¶

Get the data interface option for the given data interface and option name.

Return

pointer to the option information with the given name, NULL if either the interface ID is not valid, or the name does not match any options

Parameters

• bs: pointer to a BGP Stream instance
• if_id: ID of the interface to get option info for
• name: name of the option to retrieve

int bgpstream_set_data_interface_option(bgpstream_t *bs, bgpstream_data_interface_option_t *option_type, const char *option_value)¶

Set a data interface option.

Use the bgpstream_get_data_interface_options function to discover the set of options for an interface.

Return

0 if the option was set successfully, -1 otherwise

Parameters

• bs: pointer to a BGP Stream instance to configure
• option_type: pointer to the option to set
• option_value: value to set the option to

bgpstream_data_interface_id_t bgpstream_get_data_interface_id(bgpstream_t *bs)¶

Get the ID of the currently active data interface.

If no data interface has been explicitly set, this function will return the ID of the default data interface.

Return

the ID of the currently active data interface

Parameters

• bs: pointer to a BGP Stream instance

void bgpstream_set_data_interface(bgpstream_t *bs, bgpstream_data_interface_id_t if_id)¶

Set the data interface that BGP Stream uses to find BGP data.

Parameters

• bs: pointer to a BGP Stream instance to configure
• if_id: ID of the data interface to use

void bgpstream_set_live_mode(bgpstream_t *bs)¶

Configure the interface to block waiting for new data instead of returning end-of-stream if no more data is available.

Live mode is implicitly enabled when an interval end is set to BGPSTREAM_FOREVER.

Parameters

• bs: pointer to a BGP Stream instance to put into live mode

int bgpstream_start(bgpstream_t *bs)¶

Start the given BGP Stream instance.

This function must be called after all configuration functions, and before the first call to bgpstream_get_next_record.

Return

0 if the stream was started successfully, -1 otherwise

Parameters

• bs: pointer to a BGP Stream instance to start

int bgpstream_get_next_record(bgpstream_t *bs, bgpstream_record_t **record)¶

Retrieve from the stream,the next record that matches configured filters.

The record passed to this function may be reused for subsequent calls if state for previous records is not needed (i.e. the records are processed independently of each other). If records are not processed independently, then a new record must be created for each call to this function.

Return

>0 if a record was read successfully, 0 if end-of-stream has been reached, <0 if an error occurred.

Parameters

• bs: pointer to a BGP Stream instance to get record from
• record: set to a borrowed pointer to a record if the return code is >0.

void bgpstream_destroy(bgpstream_t *bs)¶

Destroy the given BGP Stream instance.

Parameters

• bs: pointer to a BGP Stream instance to destroy