
[[telemetryd-bmp-persisting-adapter]]
= BMP Persisting Adapter
:description: Learn about the BMP Persisting adapter in OpenNMS {page-component-title} that persists OpenBMP messages received without the need for additional OpenBMP components.

The BMP persisting adapter persists OpenBMP messages received without the need for any additional OpenBMP components.
It handles BMP messages the xref:telemetryd/protocols/bmp/parser.adoc[BMP parser] receives and parses, and creates OpenBMP-compatible messages, which are then
persisted in the OpenNMS PostgreSQL DB.

NOTE: The BMP persisting adapter can produce huge volumes of data.
You must have the proper setup for PostgreSQL with TimeScale, and for more throughput, you should use Sentinels.
Failure to do so can cause issues with other {page-component-title} functionality.

== Facts

[options="autowidth"]
|===
| Class Name          | `org.opennms.netmgt.telemetry.protocols.bmp.adapter.BmpPersistingAdapter`
|===

Stats and retrieving data from external data for rpki/routeinfo/asinfo are handled only on the {page-component-title} core.
This requires you to install the `opennms-telemetry-bmp-stats` feature on {page-component-title}.
Sentinel does not require the `opennms-telemetry-bmp-stats` feature.

BMP stats are stored as time series data in PostgreSQL with the TimescaleDB extension (link:https://docs.timescale.com/latest/getting-started/installation[installation instructions]).
For `opennms` schema, TimescaleDB extension can be added with `-t` option on install DB script (for example, `$\{OPENNMS_HOME}/bin/install -dist`).
If the TimescaleDB extension is not installed, stat tables will not be converted to hypertables.

To load the adapter while {page-component-title} is running, use the following command in the Karaf shell.

[source, karaf]
----
feature:install opennms-telemetry-bmp-stats
----

To ensure that the feature continues to be installed on subsequent restarts, add `opennms-telemetry-bmp-stats` to a file in `featuresBoot.d`:
[source, console]
----
echo "opennms-telemetry-bmp-stats" | sudo tee ${OPENNMS_HOME}/etc/featuresBoot.d/telemetry-bmp.boot
----

== Configure BMP persistence for external sources

You can configure the following parameters when connecting to external sources like RPKI or RouteInfo DB tables.

[options="header", cols="1,3,2"]
|===
| Name
| Description
| Default

| rpkiUrl
| Rest API URL to retrieve RPKI ROAs.
| \http://localhost:8080/api/export.json

| rpkiUsername
| Username for RPKI Rest API.
|

| rpkiPassword
| Password for RPKI Rest API.
|

| routeInfoDbPath
| Path for RouteInfo DB tables.
| ${karaf.etc}/routeinfo
|===

Configure the above parameters as follows on the core via Karaf:

[source, karaf]
----
config:edit org.opennms.features.telemetry.protocols.bmp.adapter.persist
config:property-set rpkiUrl http://localhost:8080/api/export.json
config:update
----

[[run-bmp-sentinel]]
== Run BMP adapter on Sentinel

The BMP persisting adapter can also run on Sentinel.
Sentinel must start the appropriate BMP adapter.
In Sentinel, adapters are configured either by placing a .cfg file in `$\{SENTINEL_HOME}/etc` or via a `config:edit` statement.

The following example configures the consumption of `BMP` messages and saves the configuration in `$\{SENTINEL_HOME}/etc/org.opennms.features.telemetry.adapters-bmp.cfg`.

First, log in to the Karaf Shell.

[source, console]
----
$ ssh -p 8301 admin@localhost
----

[source, karaf]
----
config:edit --alias BMP --factory org.opennms.features.telemetry.adapters
config:property-set name BMP
config:property-set adapters.0.name BMP-Persisting-Adapter
config:property-set adapters.0.class-name org.opennms.netmgt.telemetry.protocols.bmp.adapter.BmpPersistingAdapter
config:update
----

You can immediately activate following features via Karaf shell to start processing BMP messages on Sentinel.

[source, karaf]
----
feature:install sentinel-core
feature:install sentinel-persistence <1>
feature:install sentinel-jms <2>
feature:install sentinel-blobstore-noop
feature:install sentinel-jsonstore-postgres
feature:install sentinel-telemetry-bmp-persist
----

<1> Needs datasource configuration setup per xref:operation:deep-dive/flows/sentinel/sentinel.adoc#flows-scaling[Sentinel Flow Processing].
<2> Can alternatively be set to `sentinel-kafka` based on your selected message broker.
Refer to xref:reference:configuration/sentinel-features.adoc#ga-kafka-configuration[Sentinel Kafka Configuration].

To automatically start the adapter each time the Sentinel restarts, add the following to `$\{SENTINEL_HOME}/etc/featuresBoot.d/bmp-adapter.boot`.

[source]
----
sentinel-core
sentinel-persistence
sentinel-jms
sentinel-blobstore-noop
sentinel-jsonstore-postgres
sentinel-telemetry-bmp-persist
----

NOTE: When running Kafka as the broker, the consumer config needs to have the `auto.offset.reset=earliest` setting, otherwise
the BMP Adapter may miss some of the early messages, like the PeerUp notification, which are essential for proper BMP state.

NOTE: When running on Sentinel, it is still necessary to have the `opennms-telemetry-bmp-stats` feature running on the core.
