X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fuser-guide%2Fbgp-monitoring-protocol-user-guide.rst;h=581607dcac271ffde9b80e5c1abdd85e34021be4;hb=9a9b923cfbee16adc5085f5d64b2ef1db0328cb0;hp=5ea5833d73e3b24770c8760a80ff98e5dd8a6573;hpb=581dd9938c73e6e25d6e70ce5a014349a2d774af;p=docs.git
diff --git a/docs/user-guide/bgp-monitoring-protocol-user-guide.rst b/docs/user-guide/bgp-monitoring-protocol-user-guide.rst
index 5ea5833d7..581607dca 100644
--- a/docs/user-guide/bgp-monitoring-protocol-user-guide.rst
+++ b/docs/user-guide/bgp-monitoring-protocol-user-guide.rst
@@ -1,90 +1,143 @@
BGP Monitoring Protocol User Guide
==================================
+This guide contains information on how to use the OpenDaylight BGP Monitoring Protocol (BMP) plugin.
+It covers BMP basic concepts, supported capabilities, configuration and operations.
+
+.. contents:: Contents
+ :depth: 1
+ :local:
Overview
--------
+This section provides high-level overview of the BMP plugin, OpenDaylight implementation and BMP usage for SDN.
-The OpenDaylight Karaf distribution comes preconfigured with baseline
-BMP configuration.
+.. contents:: Contents
+ :depth: 2
+ :local:
-- **32-bmp.xml** (initial configuration for BMP messages handler
- service provider and BMP client/server dispatcher settings)
+BGP Monitoring Protocol
+^^^^^^^^^^^^^^^^^^^^^^^
+The BGP Monitoring Protocol (BMP) serves to monitor BGP sessions.
+The BMP can be used to obtain route view instead of screen scraping.
+The BMP provides access to unprocessed routing information (Adj-RIB-In) and processed routes (applied inbound policy) of monitored router's peer.
+In addition, monitored router can provide periodic dump of statistics.
-- **42-bmp-example.xml** (sample initial configuration for the BMP
- Monitoring Station application)
+The BMP runs over TCP.
+Both monitored router and monitoring station can be configured as active or passive party of the connection.
+The passive party listens at particular port.
+The router can be monitored by multiple monitoring stations.
+BMP messages are sent by monitored router only, monitoring station supposed to collect and process data received over BMP.
-Configuring BMP
----------------
+.. figure:: ./images/bgpcep/bmp.png
+ :align: center
+ :alt: BMP
-Server Binding
-~~~~~~~~~~~~~~
+ The BMP overview - Monitoring Station, Monitored Router and Monitored Peers.
-The default shipped configuration will start a BMP server on
-0.0.0.0:12345.You can change this behavior in **42-bmp-example.xml**:
-.. code:: xml
+BMP in SDN
+^^^^^^^^^^
+The main concept of BMP is to monitor BGP sessions - monitoring station is aware of monitored peer's status, collects statistics and analyzes them in order to provide valuable information for network operators.
-
- prefix:bmp-monitor-impl
- example-bmp-monitor
-
- 12345
- ...
-
+Moreover, BMP provides provides peer RIBs visibility, without need to establish BGP sessions.
+Unprocessed routes may serve as a source of information for software-driven routing optimization.
+In this case, SDN controller, a BMP monitoring station, collects routing information from monitored routers.
+The routes are used in subsequent optimization procedures.
+
+
+OpenDaylight BMP plugin
+^^^^^^^^^^^^^^^^^^^^^^^
+The OpenDaylight BMP plugin provides monitoring station implementation.
+The plugin can establish BMP session with one or more monitored routers in order to collect routing and statistical information.
+
+* Runtime configurable monitoring station
+* Read-only routes and statistics view
+* Supports various routing information types
+
+.. figure:: ./images/bgpcep/bmp-plugin.png
+ :align: center
+ :alt: BMP plugin
+
+ OpenDaylight BMP plugin overview.
+
+.. important:: The BMP plugin is not storing historical data, it provides current snapshot only.
+
+List of supported capabilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The BMP plugin implementation is based on Internet standards:
+
+* `RFC7854 `_ - BGP Monitoring Protocol (BMP)
+
+.. note:: The BMP plugin is capable to process various types of routing information (IP Unicast, EVPN, L3VPN, Link-State,...).
+ Please, see complete list in BGP user guide.
-- **binding-address** - adress on which BMP will be started and listen;
- to change value, uncomment then line first
+Running BMP
+-----------
+This section explains how to install BMP plugin.
-- **binding-port** - port on which the address will be started and
- listen
+1. Install BMP feature - ``odl-bgpcep-bmp``.
+ Also, for sake of this sample, it is required to install RESTCONF.
+ In the Karaf console, type command:
-Multiple instances of the BMP monitoring station (**bmp-monitor-impl**
-module) can be created. However, each instance must have a unique pair
-of **binding-address** and **binding-port**
+ .. code-block:: console
-Active mode
-~~~~~~~~~~~
+ feature:install odl-restconf odl-bgpcep-bmp
-OpenDaylightâs BMP might be configured to act as an active party of the
-connection (ODL BMP < = > Monitored router). To enable this
-functionality, configure monitored-router with mandatory parameters:
+2. The BMP plugin contains a default configuration, which is applied after the feature starts up.
+ One instance of BMP monitoring station is created (named *example-bmp-monitor*), and its presence can be verified via REST:
-- address (must be unique for each configured "monitored-router"),
+ **URL:** ``/restconf/operational/bmp-monitor:bmp-monitor/monitor/example-bmp-monitor``
-- port,
+ **Method:** ``GET``
-- active.
+ **Response Body:**
-See following example from 42-bmp-example.xml:
+ .. code-block:: xml
-.. code:: xml
+
+ example-bmp-monitor
+
-
- 192.0.2.2
- 1234
- true
-
+BMP Monitoring Station
+----------------------
+The following section shows how to configure BMP basics, how to verify functionality and presents essential components of the plugin. Next samples demonstrate the pluginâs runtime configuration capability.
-Configuration through RESTCONF
-------------------------------
+The monitoring station is responsible for received BMP PDUs processing and storage.
+The default BMP server is listening at port *12345*.
-Server Binding
-~~~~~~~~~~~~~~
+.. contents:: Contents
+ :depth: 2
+ :local:
-**URL:**
-*`http://:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/config:module/odl-bmp-impl-cfg:bmp-monitor-impl/example-bmp-monitor :8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/config:module/odl-bmp-impl-cfg:bmp-monitor-impl/example-bmp-monitor>`__*
+Configuration
+^^^^^^^^^^^^^
+This section shows the way to configure the BMP monitoring station via REST API.
-**Content-Type:** application/xml
+.. warning:: The BMP monitoring station configuration is going to be changed in Carbon.
+ This user-guide will be updated accordingly.
-**Method:** PUT
+Monitoring station configuration
+''''''''''''''''''''''''''''''''
+In order to change default's BMP monitoring station configuration, use following request.
+It is required to install ``odl-netconf-connector-ssh`` feature first.
-**Body:**
+**URL:** ``/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/config:module/odl-bmp-impl-cfg:bmp-monitor-impl/example-bmp-monitor``
-.. code:: xml
+**Method:** ``PUT``
+
+**Content-Type:** ``application/xml``
+
+**Request Body:**
+
+.. code-block:: xml
+ :linenos:
+ :emphasize-lines: 4,5
example-bmp-monitor
x:bmp-monitor-impl
+ 12355
+ 0.0.0.0
bmp-dispatcher
global-bmp-dispatcher
@@ -97,29 +150,34 @@ Server Binding
x:extensions
global-rib-extensions
- 0.0.0.0
x:dom-async-data-broker
pingpong-broker
- 12345
-- change values for **binding-address** and/or **binding-port**
+@line 4: **binding-port** - The BMP server listening port.
-Active mode
-~~~~~~~~~~~
+@line 5: **binding-address** - The BMP server biding address.
-**URL:**
-*`http://:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/config:module/odl-bmp-impl-cfg:bmp-monitor-impl/example-bmp-monitor :8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/config:module/odl-bmp-impl-cfg:bmp-monitor-impl/example-bmp-monitor>`__*
+.. note:: User may create multiple BMP monitoring station instances at runtime.
-**Content-Type:** application/xml
+Active mode configuration
+'''''''''''''''''''''''''
+In order to enable active connection, use following request.
+It is required to install ``odl-netconf-connector-ssh`` feature first.
-**Method:** PUT
+**URL:** ``/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/config:module/odl-bmp-impl-cfg:bmp-monitor-impl/example-bmp-monitor``
-**Body:**
+**Method:** ``PUT``
-.. code:: xml
+**Content-Type:** ``application/xml``
+
+**Request Body:**
+
+.. code-block:: xml
+ :linenos:
+ :emphasize-lines: 23,24,25
example-bmp-monitor
@@ -143,11 +201,423 @@ Active mode
12345
- 127.0.0.1
+ 10.10.10.10
1234
true
-- change values for **address** and **port**
+@line 23: **address** - The monitored router's IP address.
+
+@line 24: **port** - The monitored router's port.
+
+@line 25: **active** - Active mode set.
+
+.. note:: User may configure active session establishment for multiple monitored routers.
+
+MD5 authentication configuration
+''''''''''''''''''''''''''''''''
+In order to enable active connection, use following request.
+It is required to install ``odl-netconf-connector-ssh`` feature first.
+
+**URL:** ``/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/config:module/odl-bmp-impl-cfg:bmp-monitor-impl/example-bmp-monitor``
+
+**Method:** ``PUT``
+
+**Content-Type:** ``application/xml``
+
+**Request Body:**
+
+.. code-block:: xml
+ :linenos:
+ :emphasize-lines: 23,24
+
+
+ example-bmp-monitor
+ x:bmp-monitor-impl
+
+ bmp-dispatcher
+ global-bmp-dispatcher
+
+
+ x:binding-codec-tree-factory
+ runtime-mapping-singleton
+
+
+ x:extensions
+ global-rib-extensions
+
+ 0.0.0.0
+
+ x:dom-async-data-broker
+ pingpong-broker
+
+ 12345
+
+ 11.11.11.11
+ topsecret
+
+
+
+@line 23: **address** - The monitored router's IP address.
+
+@line 24: **password** - The TCP MD5 signature.
+
+Collector DB Tree
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ module: bmp-monitor
+ +--rw bmp-monitor
+ +--ro monitor* [monitor-id]
+ +--ro monitor-id monitor-id
+ +--ro router* [router-id]
+ +--ro name? string
+ +--ro description? string
+ +--ro info? string
+ +--ro router-id router-id
+ +--ro status? status
+ +--ro peer* [peer-id]
+ +--ro peer-id rib:peer-id
+ +--ro type peer-type
+ x--ro distinguisher
+ | +--ro distinguisher-type? distinguisher-type
+ | +--ro distinguisher? string
+ +--ro peer-distinguisher? union
+ +--ro address inet:ip-address
+ +--ro as inet:as-number
+ +--ro bgp-id inet:ipv4-address
+ +--ro router-distinguisher? string
+ +--ro peer-session
+ | +--ro local-address inet:ip-address
+ | +--ro local-port inet:port-number
+ | +--ro remote-port inet:port-number
+ | +--ro sent-open
+ | | +--ro version? protocol-version
+ | | +--ro my-as-number? uint16
+ | | +--ro hold-timer uint16
+ | | +--ro bgp-identifier inet:ipv4-address
+ | | +--ro bgp-parameters*
+ | | +--ro optional-capabilities*
+ | | +--ro c-parameters
+ | | +--ro as4-bytes-capability
+ | | | +--ro as-number? inet:as-number
+ | | +--ro bgp-extended-message-capability!
+ | | +--ro multiprotocol-capability
+ | | | +--ro afi? identityref
+ | | | +--ro safi? identityref
+ | | +--ro graceful-restart-capability
+ | | | +--ro restart-flags bits
+ | | | +--ro restart-time uint16
+ | | | +--ro tables* [afi safi]
+ | | | +--ro afi identityref
+ | | | +--ro safi identityref
+ | | | +--ro afi-flags bits
+ | | +--ro add-path-capability
+ | | | +--ro address-families*
+ | | | +--ro afi? identityref
+ | | | +--ro safi? identityref
+ | | | +--ro send-receive? send-receive
+ | | +--ro route-refresh-capability!
+ | +--ro received-open
+ | | +--ro version? protocol-version
+ | | +--ro my-as-number? uint16
+ | | +--ro hold-timer uint16
+ | | +--ro bgp-identifier inet:ipv4-address
+ | | +--ro bgp-parameters*
+ | | +--ro optional-capabilities*
+ | | +--ro c-parameters
+ | | +--ro as4-bytes-capability
+ | | | +--ro as-number? inet:as-number
+ | | +--ro bgp-extended-message-capability!
+ | | +--ro multiprotocol-capability
+ | | | +--ro afi? identityref
+ | | | +--ro safi? identityref
+ | | +--ro graceful-restart-capability
+ | | | +--ro restart-flags bits
+ | | | +--ro restart-time uint16
+ | | | +--ro tables* [afi safi]
+ | | | +--ro afi identityref
+ | | | +--ro safi identityref
+ | | | +--ro afi-flags bits
+ | | +--ro add-path-capability
+ | | | +--ro address-families*
+ | | | +--ro afi? identityref
+ | | | +--ro safi? identityref
+ | | | +--ro send-receive? send-receive
+ | | +--ro route-refresh-capability!
+ | +--ro information
+ | | +--ro string-information*
+ | | +--ro string-tlv
+ | | +--ro string-info? string
+ | +--ro status? status
+ | +--ro timestamp-sec? yang:timestamp
+ | +--ro timestamp-micro? yang:timestamp
+ +--ro stats
+ | +--ro rejected-prefixes? yang:counter32
+ | +--ro duplicate-prefix-advertisements? yang:counter32
+ | +--ro duplicate-withdraws? yang:counter32
+ | +--ro invalidated-cluster-list-loop? yang:counter32
+ | +--ro invalidated-as-path-loop? yang:counter32
+ | +--ro invalidated-originator-id? yang:counter32
+ | +--ro invalidated-as-confed-loop? yang:counter32
+ | +--ro adj-ribs-in-routes? yang:gauge64
+ | +--ro loc-rib-routes? yang:gauge64
+ | +--ro per-afi-safi-adj-rib-in-routes
+ | | +--ro afi-safi* [afi safi]
+ | | +--ro afi identityref
+ | | +--ro safi identityref
+ | | +--ro count? yang:gauge64
+ | +--ro per-afi-safi-loc-rib-routes
+ | | +--ro afi-safi* [afi safi]
+ | | +--ro afi identityref
+ | | +--ro safi identityref
+ | | +--ro count? yang:gauge64
+ | +--ro updates-treated-as-withdraw? yang:counter32
+ | +--ro prefixes-treated-as-withdraw? yang:counter32
+ | +--ro duplicate-updates? yang:counter32
+ | +--ro timestamp-sec? yang:timestamp
+ | +--ro timestamp-micro? yang:timestamp
+ +--ro pre-policy-rib
+ | +--ro tables* [afi safi]
+ | +--ro afi identityref
+ | +--ro safi identityref
+ | +--ro attributes
+ | | +--ro uptodate? boolean
+ | +--ro (routes)?
+ +--ro post-policy-rib
+ | +--ro tables* [afi safi]
+ | +--ro afi identityref
+ | +--ro safi identityref
+ | +--ro attributes
+ | | +--ro uptodate? boolean
+ | +--ro (routes)?
+ +--ro mirrors
+ +--ro information? bmp-msg:mirror-information-code
+ +--ro timestamp-sec? yang:timestamp
+ +--ro timestamp-micro? yang:timestamp
+
+
+Operations
+^^^^^^^^^^
+The BMP plugin offers view of collected routes and statistical information from monitored peers.
+To get top-level view of monitoring station:
+
+**URL:** ``/restconf/operational/bmp-monitor:bmp-monitor/monitor/example-bmp-monitor``
+
+**Method:** ``GET``
+
+**Response Body:**
+
+.. code-block:: xml
+ :linenos:
+ :emphasize-lines: 3,5,11,12,13,14,15,17,20,21,22,27,33,50,53
+
+
+
+ example-bmp-monitor
+
+ 10.10.10.10
+ name
+ monitored-router
+ monitored router;
+ up
+
+ 20.20.20.20
+ 20.20.20.20
+ 20.20.20.20
+ 65000
+ global
+
+ 1790
+ 0
+ up
+ 10.10.10.10
+ 2200
+
+ 180
+ 65000
+ 20.20.20.20
+
+
+ 180
+ 65000
+ 65000
+
+
+
+
+ x:ipv4-address-family
+ x:unicast-subsequent-address-family
+
+
+ 10.10.10.0/24
+
+ ...
+
+
+
+
+ true
+
+
+
+
+ ...
+
+
+ 0
+ 0
+ 0
+ 100
+ 0
+ 0
+ 10
+ 0
+ 0
+ 8
+
+
+
+
+
+
+@line 3: **monitor-id** - The BMP monitoring station instance identifier.
+
+@line 5: **router-id** - The monitored router IP address, serves as an identifier.
+
+@line 11: **peer-id** - The monitored peer's BGP identifier, serves a an identifier.
+
+@line 12: **address** - The IP address of the peer, associated with the TCP session.
+
+@line 13: **bgp-id** - The BGP Identifier of the peer.
+
+@line 14: **as** - The Autonomous System number of the peer.
+
+@line 15: **type** - Identifies type of the peer - *Global Instance*, *RD Instance* or *Local Instance*
+
+@line 17: **remote-port** - The peer's port number associated with TCP session.
+
+@line 20: **local-address** - The IP address of the monitored router associated with the peering TCP session.
+
+@line 21: **local-port** - The port number of the monitored router associated with the peering TCP session.
+
+@line 22: **received-open** - The full OPEN message received by monitored router from the peer.
+
+@line 27: **sent-open** - The full OPEN message send by monitored router to the peer.
+
+@line 33: **pre-policy-rib** - The Adj-RIB-In that contains unprocessed routing information.
+
+@line 50: **post-policy-rib** - The Post-Policy Ad-RIB-In that contains routes filtered by inbound policy.
+
+@line 53: **stats** - Contains various statistics, periodically updated by the router.
+
+-----
+
+* To view collected information from particular monitored router:
+ **URL:** ``/restconf/operational/bmp-monitor:bmp-monitor/monitor/example-bmp-monitor/router/10.10.10.10``
+
+* To view collected information from particular monitored peer:
+ **URL:** ``/restconf/operational/bmp-monitor:bmp-monitor/monitor/example-bmp-monitor/router/10.10.10.10/peer/20.20.20.20``
+
+Test tools
+----------
+BMP test tool serves to test basic BMP functionality, scalability and performance.
+
+BMP mock
+^^^^^^^^
+The BMP mock is a stand-alone Java application purposed to simulate a BMP-enabled router(s) and peers.
+The simulator is capable to report dummy routes and statistics.
+This application is not part of the OpenDaylight Karaf distribution, however it can be downloaded from OpenDaylight's Nexus (use latest release version):
+
+``https://nexus.opendaylight.org/content/repositories/opendaylight.release/org/opendaylight/bgpcep/bgp-bmp-mock``
+
+Usage
+'''''
+The application can be run from command line:
+
+.. code-block:: console
+
+ java -jar bgp-bmp-mock-*-executable.jar
+
+
+with optional input parameters:
+
+.. code-block:: console
+
+ --local_address (optional, default 127.0.0.1)
+ The IPv4 address where BMP mock is bind to.
+
+ --remote_address (optional, default 127.0.0.1:12345)
+ The remote IPv4 Address and port number of BMP monitoring station.
+
+ --passive (optional, not present by default)
+ This flags enables passive mode for simulated routers.
+
+ --routers_count <0..N> (optional, default 1)
+ An amount of BMP routers to be connected to the BMP monitoring station.
+
+ --peers_count <0..N> (optional, default 0)
+ An amount of peers reported by each BMP router.
+
+ --pre_policy_routes <0..N> (optional, default 0)
+ An amount of "pre-policy" simple IPv4 routes reported by each peer.
+
+ --post_policy_routes <0..N> (optional, default 0)
+ An amount of "post-policy" simple IPv4 routes reported by each peer.
+
+ --log_level (optional, default INFO)
+ Set logging level for BMP mock.
+
+Troubleshooting
+---------------
+This section offers advices in a case OpenDaylight BMP plugin is not working as expected.
+
+.. contents:: Contents
+ :depth: 2
+ :local:
+
+BMP is not working...
+^^^^^^^^^^^^^^^^^^^^^
+* First of all, ensure that all required features are installed, local monitoring station and monitored router/peers configuration is correct.
+
+ To list all installed features in OpenDaylight use the following command at the Karaf console:
+
+ .. code-block:: console
+
+ feature:list -i
+
+* Check OpenDaylight Karaf logs:
+
+ From Karaf console:
+
+ .. code-block:: console
+
+ log:tail
+
+ or open log file: ``data/log/karaf.log``
+
+ Possibly, a reason/hint for a cause of the problem can be found there.
+
+* Try to minimize effect of other OpenDaylight features, when searching for a reason of the problem.
+
+* Try to set DEBUG severity level for BMP logger via Karaf console commands, in order to collect more information:
+
+ .. code-block:: console
+
+ log:set DEBUG org.opendaylight.protocol.bmp
+
+Bug reporting
+^^^^^^^^^^^^^
+Before you report a bug, check `BGPCEP Bugzilla `_ to ensure same/similar bug is not already filed there.
+
+Write an e-mail to bgpcep-users@lists.opendaylight.org and provide following information:
+
+#. State OpenDaylight version
+
+#. Describe your use-case and provide as much details related to BMP as possible
+
+#. Steps to reproduce
+#. Attach Karaf log files, optionally packet captures, REST input/output