Connectors

Connectors are units that allow data to flow into a Rotonda application. Currently Rotonda supports three different types of connectors. Connectors can start and maintain sessions with other systems. Connectors therefore can keep state.

bmp-tcp-in

This unit implements an RFC 7854 “BGP Monitoring Protocol (BMP)” “monitoring station” [1] by listening on a specified TCP/IP address and port number for incoming connections from zero or more BMP capable routers. This unit processes the incoming raw BMP messages through a BMP state machine in order to extract, store and propagate downstream the route announcements and withdrawals.

This unit extends the HTTP API with endpoints that output HTML and text formatted information about the monitored routers currently streaming data into Rotonda. These endpoints are intended for operators as a diagnostic aid and not for automation purposes. The output format is not intended to be machine readable and may change without warning.

Pipeline Interaction

The bmp-tcp-in component ingests BMP Messages from a source over a configured TCP session, optionally filters them, and explodes the NLRI into separate (Prefix, Route, RouteContext) tuples, that are sent into the pipeline.

Rotonda will assign one unique ingress_id per router present in the stream produced by a bmp-tcp-in connector. Closing and opening the session may lead to different ids per router.

                       HTTP API
                         │ ▲
                         │ │
          ┌──────────────▼─┴───────────────┐
TCP/IP ───▶BmpMessage──▶filter──▶BmpMessage├──▶N * (Prefix,Route,RouteContext)
          └───────────────┬────────────────┘
                          │
              ┌───────────▼──────────────┐
              │0..M values of Log output │
              └──────────────────────────┘

Filtering

The bmp-tcp-in connector has a programmable Roto filter built-in with a hard-coded name bmp_in, and it should be included in the Roto filter file specified in the Rotonda configuration. The type of this Roto filter is:

filter bmp_in(Log, BmpMsg, Provenance) -> Verdict

Argument Types

Log

Handle to emit log entries to a configured output, such as mqtt-out.

BmpMsg

The BMP Message that is flowing through this filter. It can be inspected, and will be sent out unmodified. Note that the individual parts of the NLRI of the message cannot be inspected. If you wish to do this, you should do this further in the pipeline, e.g. on the filter in a RIB.

Provenance

Contextual data about the session.

Return Value

Verdict

The resulting value of this filter, either accept or reject.

Configuration Options

The bmp-tcp-in component can be defined in the Rotonda configuration file, like this:

[units.<NAME>]
type = "bmp-tcp-in"
..

where <NAME> is the name of the component, to be referenced in the value of the sources field in a receiving component.

type (mandatory)

This must be set to bmp-tcp-in for this type of connector.

listen (mandatory)

The IP address and the port to listen on for incoming BMP connections from routers, in the form of: “ip_address:port”.

Example: listen = "0.0.0.0:11019".

http_api_path (optional)

The relative URL prefix for HTTP REST API calls responded to by this instance of this unit.

Defaults to /bmp-routers/.

bgp-tcp-in

This unit listens on a specified TCP/IP address and port number for incoming connections from zero or more RFC 4271 [1] BGP speakers. Currently supported AFI/SAFI combinations are IPv4/Unicast, IPv6/Unicast, IPv4/Multicast and IPv6/Multicast.

Pipeline Interaction

The bgp-tcp-in component ingests BGP UPDATE Messages from a source, optionally filters them, and explodes the NLRI into separate (Prefix, Route, RouteContext) tuples, that are sent out into the pipeline.

Rotonda will create one unique ingress_id per session per bgp-tcp-in connector.

          ┌──────────────────────────────────┐
TCP/IP ───▶ BgpMessage──▶filter──▶BgpMessage ├──▶ N * (Prefix,Route,RouteContext)
          └──────────────────────────────────┘

Filtering

The bgp-tcp-in connector has a programmable Roto filter built-in with a hard-coded name bgp_in, and it should be included in the Roto filter file specified in the Rotonda configuration. The type of this Roto filter is:

filter bgp_in(Log, BgpMsg, Provenance) -> Verdict

Argument Types

Log

Handle to emit log entries to a configured output, such as mqtt-out.

BgpMsg (read-only)

The BGP UPDATE Message that is flowing through this filter. It can be inspected, and will be sent out unmodified.

Provenance (read-only)

Contextual data about the session.

Return Value

Verdict

The resulting value of this filter, either accept or reject.

Configuration Options

The bgp-tcp-in component can be defined in the Rotonda configuration file, like this:

[units.<NAME>]
type = "bgp-tcp-in"
..

where <NAME> is the name of the component, to be referenced in the value of the sources field in a receiving component.

type (mandatory): This must be set to bgp-tcp-in for this type of connector.

listen (mandatory)

The IP address and the port to listen on for incoming BGP connections from BGP speakers, in the form of: “ip_address:port”.

Example: listen = "10.1.0.254:179"

my_asn (mandatory): The positive number of the Autonomous System in which this instance of Rotonda is operating and which will be sent by this BGP speaker in its RFC 4271 BGP OPEN message in the “My Autonomous Number” field [3].

my_bgp_id (mandatory): An array of four positive integer numbers, e.g. [1, 2, 3, 4], which together define per RFC 4271 “A 4-octet unsigned integer that indicates the BGP Identifier of the sender of BGP messages” which is “determined up startup and is the same for every local interface and BGP peer” [2].

peers."<ADDRESS>" (optional)

This setting defines the set of peers from which incoming connections will be accepted. By default no such peers are defined and thus all incoming connections are rejected.

The double-quoted address value must be an IPv4 or IPv6 address or a prefix, e.g. “1.2.3.4” or “1.2.3.0/24.

The value of this setting is a TOML table which may be specified inline or as a separate section in the config file, e.g.:

[units.my-bgp-in.peers.".."]
name = ..
remote_asn = ..

Or:

[units.my-bgp-in]
peers.".." = { name = .., remote_asn = .. }

These sections have the following fields:

name

A name identifying the remote peer intended to make it easier for the operator to know which BGP speaker these settings refer to.

remote_asn

The expected Autonomous System Number for the remote BGP speaker that connects to this unit (i.e. the “My Autonomous Number” field of the RFC 4271 BGP OPEN message [3]). Can be specified as either a single ASN:

remote_asn = 65001

Or a list of multiple ASNs, where the empty list means ‘accept everything’:

remote_asn = [] # accept any ASN sent by the peer
remote_asn = [65001, 65002, 65003] # accept any of these ASNs

protocols

The list of address families (AFI/SAFI) that is accepted from this peer. These are announced in the BGP OPEN as MultiProtocol Capabilities (RFC 4760). In order to receive ‘as much as possible’, list all options. If this setting is omitted or set to the empty list, the session will only carry conventional IPv4 Unicast information.

Currently supported are: ["Ipv4Unicast", "Ipv6Unicast", "Ipv4Multicast", "Ipv6Multicast"]

mrt-file-in (experimental)

This unit can take one or several mrt files (RFC 6396) and ingest the contents of the table dumps in it.

It will load all the RIB entries and load them into a Rotonda RIB. Routes will be stored per peer.

Currently, the mrt-file-in connector does not offer any programmable filtering. You can, however, filter further on in the pipeline, e.g. in the filter of a receiving RIB.

Pipeline Interaction

The mrt-file-in component ingests MRT messages from a file, extracts all the peers mentioned in the PEER_INDEX_TABLE in the TableDump, and all the BGP messages encapsulated in it. It then explodes all the BGP messages into (prefix, Route, RouteContext) tuples. It keeps a session open for the file for the duration of the lifetime of the component.

Rotonda will assign one ingress_id per peer found in the TableDump table.

        ┌──────────────────────────┐
file ───▶ MrtMessage─┬▶BgpMessage  │
        │            │             ├──▶ N * (Prefix,Route,RouteContext)
        │            └▶RibTableDump│
        └──────────────────────────┘

Configuration Options

The mrt-file-in component can be defined in the Rotonda configuration file, like this:

[units.<NAME>]
type = "mrt-file-in"
filename = ["dump.mrt", "updates1.mrt", "updates2.mrt"]
update_path = "path/to/updates"

where <NAME> is the name of the component, to be referenced in the value of the sources field in a receiving component.

type (mandatory): This must be set to mrt-file-in for this type of connector.

filename (mandatory): The path to the one or multiple mrt files, either ‘RIB dumps’ containing complete tables, or ‘updates’ containing BGP messages.

update_path (optional): The path on the filesystem from where files can be queued for processing. When set, an API endpoint on /mrt/<NAME>?queue=<FILENAME> is enabled. If <FILENAME> is not under the configured update_path, it will not be processed.

rtr-tcp-in

This unit connects to Relying Party software or cache, obtaining RPKI information via the RTR protocol. It is able to retrieve VRPs (from ROAs), enabling Route Origin Validation (ROV) from roto filter scripts.

NB: The RIB unit should include the RTR unit in its sources in rotonda.conf.

Newly incoming RTR information will trigger reevaluation (i.e., ROV) of routes already stored in Rotonda. For newly incoming routes, the check_rov method to perform ROV from a roto script is available in the rib_in_pre filter.

Filtering

The rtr-tcp-in component has a programmable Roto filter built-in with the hardcoded name vrp_update. This filter is called from Rotonda whenever new VRP information as response to a Serial Query comes in via the RTR connection (so not for information coming in during a full Cache Reset, e.g. the initial synchronisation). It is not triggered for BGPsec routerkey or ASPA related updates.

Note that in almost all cases, one would not want to actually filter out any VRP updates, and thus one should almost always return accept. This filter is merely available for logging and monitoring purposes.

For changes to the ROV status of stored routes in the RIB, see the rib_in_rov_status_update function.

filter vrp_update(vrp_update: VrpUpdate) -> Verdict

Argument Types

VrpUpdate

The VRP update containing the prefix and asn from the updated ROA. See VrpUpdate for the available roto methods.

Return Value

Verdict

The resulting value of this filter, accept or reject, affects whether or not this VRP update will be applied to the cache maintained in Rotonda. If this filter definition is omitted from the roto scripts, Rotonda defaults to accept.

Configuration Options

[units.<NAME>]
type = "rtr-tcp-in"
remote = "[::1]:3323"
retry = 60

where <NAME> is the name of the component, to be referenced in the value of the sources field in a receiving component.

type (mandatory): This must be set to rtr-tcp-in for this type of connector.

remote (mandatory): The remote IP address and port of the RTR server/cache to connect to.

retry (optional): The delay before trying to reconnect to the RTR server, in seconds. Default 60.