
= BgpSessionMonitor
:description: Learn how to configure the BgpSessionMonitor in OpenNMS {page-component-title} to check if a BGP session to a peering partner (peer-ip) is functional.

This monitor checks if a BGP session to a peering partner (peer-ip) is functional.
The monitor uses the link:https://datatracker.ietf.org/doc/html/rfc1269[RFC1269 SNMP MIB] to monitor the BGP-Session, and uses the following OIDs to test the session status:

[source, properties]
----
BGP_PEER_STATE_OID = .1.3.6.1.2.1.15.3.1.2.<peer-ip>
BGP_PEER_ADMIN_STATE_OID = .1.3.6.1.2.1.15.3.1.3.<peer-ip>
BGP_PEER_REMOTEAS_OID = .1.3.6.1.2.1.15.3.1.9.<peer-ip>
BGP_PEER_LAST_ERROR_OID = .1.3.6.1.2.1.15.3.1.14.<peer-ip>
BGP_PEER_FSM_EST_TIME_OID = .1.3.6.1.2.1.15.3.1.16.<peer-ip>
----

The `<peer-ip>` is the far end IP address of the BGP session end point.

An SNMP GET request for `BGP_PEER_STATE_OID` returns a result between 1 and 6.
The service states for {page-component-title} are mapped as follows:

[options="header"]
[cols="1,3,2"]
|===
| Result
| State description
| Monitor state in {page-component-title}

| 1
| Idle
| DOWN

| 2
| Connect
| DOWN

| 3
| Active
| DOWN

| 4
| OpenSent
| DOWN

| 5
| OpenConfirm
| DOWN

| 6
| Established
| UP
|===

== Monitor facts

[cols="1,7"]
|===
| Class Name
| `org.opennms.netmgt.poller.monitors.BgpSessionMonitor`
|===

See http://www.freesoft.org/CIE/RFC/1771/31.htm[RFC1771 BGP Finite State Machine] for more information on how we defined the mapping.

== Configuration and use

.Required monitor-specific parameter for the BgpSessionMonitor

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

| bgpPeerIp
| IP address of the far end BGP peer session
| n/a

| bgpBaseOid
| Default base OID for the table that represents the BGP sessions.

| .1.3.6.1.2.1.15

| bgpPeerStateOid
| OID suffix for the table that represents the BGP-peer states.

| bgpBaseOid.3.1.2

| bgpPeerAdminStateOid
| OID suffix for the table that represents the BGP-peer admin states.

| bgpBaseOid.3.1.3

| bgpPeerRemoteAsOid
| OID suffix for the table that represents the BGP-peer remote AS number.

| bgpBaseOid.3.1.9

| bgpPeerLastErrorOid
| OID suffix for the table that represents the BGP-peer last error code.

| bgpBaseOid.3.1.14

| bgpPeerFsmEstTimeOid
| OID suffix for the table that represents the BGP-peer established time.

| bgpBaseOid.3.1.16
|===

This monitor implements the <<reference:service-assurance/introduction.adoc#ref-service-assurance-monitors-common-parameters, Common Configuration Parameters>>.

== Examples

To monitor the session state `Established`, add a service to your poller configuration in `$\{OPENNMS_HOME}/etc/poller-configuration.xml`.


Note that you must include the `monitor` section for each service in your definition.

For example:

[source, xml]
----
<!-- Example configuration poller-configuration.xml -->
<service name="BGP-Peer-99.99.99.99-AS65423" interval="300000"
         user-defined="false" status="on">
    <parameter key="retry" value="2" />
    <parameter key="timeout" value="3000" />
    <parameter key="port" value="161" />
    <parameter key="bgpPeerIp" value="99.99.99.99" />
</service>

<monitor service="BGP-Peer-99.99.99.99-AS65423" class-name="org.opennms.netmgt.poller.monitors.BgpSessionMonitor" />
----

== Error code mapping

The BGP_PEER_LAST_ERROR_OID gives an error in hex code.
The error codes returned are listed in the table below.

[options="header, autowidth"]
[cols="1,4"]
|===
| Error code
| Error Message

| 0100
| Message Header Error

| 0101
| Message Header Error - Connection Not Synchronized

| 0102
| Message Header Error - Bad Message Length

| 0103
| Message Header Error - Bad Message Type

| 0200
| OPEN Message Error

| 0201
| OPEN Message Error - Unsupported Version Number

| 0202
| OPEN Message Error - Bad Peer AS

| 0203
| OPEN Message Error - Bad BGP Identifier

| 0204
| OPEN Message Error - Unsupported Optional Parameter

| 0205
| OPEN Message Error (deprecated)

| 0206
| OPEN Message Error - Unacceptable Hold Time

| 0300
| UPDATE Message Error

| 0301
| UPDATE Message Error - Malformed Attribute List

| 0302
| UPDATE Message Error - Unrecognized Well-known Attribute

| 0303
| UPDATE Message Error - Missing Well-known Attribute

| 0304
| UPDATE Message Error - Attribute Flags Error

| 0305
| UPDATE Message Error - Attribute Length Error

| 0306
| UPDATE Message Error - Invalid ORIGIN Attribute

| 0307
| UPDATE Message Error (deprecated)

| 0308
| UPDATE Message Error - Invalid NEXT_HOP Attribute

| 0309
| UPDATE Message Error - Optional Attribute Error

| 030A
| UPDATE Message Error - Invalid Network Field

| 030B
| UPDATE Message Error - Malformed AS_PATH

| 0400
| Hold Timer Expired

| 0500
| Finite State Machine Error

| 0600
| Cease

| 0601
| Cease - Maximum Number of Prefixes Reached

| 0602
| Cease - Administrative Shutdown

| 0603
| Cease - Peer De-configured

| 0604
| Cease - Administrative Reset

| 0605
| Cease - Connection Rejected

| 0606
| Cease - Other Configuration Change

| 0607
| Cease - Connection Collision Resolution

| 0608
| Cease - Out of Resources
|===

The error message text will be displayed in the service down log message.
The log message also provides the following additional information:

[source, log]
----
BGP-Peer Adminstate
BGP-Peer Remote AS
BGP-Peer established time in seconds
----

== Debugging

If you cannot detect or monitor the BGP session, use the following command to check that the device is providing BGP data via SNMP.

[source, console]
----
snmpwalk -v 2c -c <myCommunity> <myRouter2Monitor> .1.3.6.1.2.1.15.3.1.2.99.99.99.99
----

Replace `99.99.99.99` with your BGP-Peer IP.
The result should be an integer between 1 and 6.
