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
orreject
.
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
orreject
.
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 configuredupdate_path
, it will not be processed.