X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fuser-guide%2Fbgp-monitoring-protocol-user-guide.rst;h=c01b43a47bb348ad04810a45a2c4f400d6f210d8;hb=65a2e18246a32cc50fac93d6860eaa27d0d2bbf1;hp=5ea5833d73e3b24770c8760a80ff98e5dd8a6573;hpb=237c563017ec1bae803392ad59449856c3258dd9;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..c01b43a47 100644 --- a/docs/user-guide/bgp-monitoring-protocol-user-guide.rst +++ b/docs/user-guide/bgp-monitoring-protocol-user-guide.rst @@ -1,153 +1,610 @@ +.. _bgp-monitoring-protocol-user-guide: 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 + + The BMP overview - Monitoring Station, Monitored Router and Monitored Peers. + + +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. + +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. + +Running BMP +----------- +This section explains how to install BMP plugin. + +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: + + .. code-block:: console + + feature:install odl-restconf odl-bgpcep-bmp + +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: + + **URL:** ``/restconf/config/odl-bmp-monitor-config:odl-bmp-monitors/bmp-monitor-config/example-bmp-monitor`` + + **Method:** ``GET`` + + **Response Body:** + + .. code-block:: xml + + + example-bmp-monitor + + 12345 + 0.0.0.0 + + + +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. + +The monitoring station is responsible for received BMP PDUs processing and storage. +The default BMP server is listening at port *12345*. + +.. contents:: Contents + :depth: 2 + :local: + +Configuration +^^^^^^^^^^^^^ +This section shows the way to configure the BMP monitoring station via REST API. + +Monitoring station configuration +'''''''''''''''''''''''''''''''' +In order to change default's BMP monitoring station configuration, use following request. + +**URL:** ``/restconf/config/odl-bmp-monitor-config:odl-bmp-monitors/bmp-monitor-config/example-bmp-monitor`` + +**Method:** ``PUT`` + +**Content-Type:** ``application/xml`` + +**Request Body:** + +.. code-block:: xml + :linenos: + :emphasize-lines: 4,5 + + + example-bmp-monitor + + 12345 + 0.0.0.0 + + + +@line 4: **binding-port** - The BMP server listening port. + +@line 5: **binding-address** - The BMP server biding address. + +.. note:: User may create multiple BMP monitoring station instances at runtime. + +Active mode configuration +''''''''''''''''''''''''' +In order to enable active connection, use following request. + +**URL:** ``/restconf/config/odl-bmp-monitor-config:odl-bmp-monitors/bmp-monitor-config/example-bmp-monitor`` + +**Method:** ``PUT`` + +**Content-Type:** ``application/xml`` + +**Request Body:** -Server Binding -~~~~~~~~~~~~~~ +.. code-block:: xml + :linenos: + :emphasize-lines: 8,9,10 -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**: + + example-bmp-monitor + + 12345 + 0.0.0.0 + + +
192.0.2.2
+ 1234 + true + + + +@line 8: **address** - The monitored router's IP address. + +@line 9: **port** - The monitored router's port. + +@line 10: **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. -.. code:: xml +**URL:** ``/restconf/config/odl-bmp-monitor-config:odl-bmp-monitors/bmp-monitor-config/example-bmp-monitor`` - - prefix:bmp-monitor-impl - example-bmp-monitor - - 12345 - ... - +**Method:** ``PUT`` -- **binding-address** - adress on which BMP will be started and listen; - to change value, uncomment then line first +**Content-Type:** ``application/xml`` -- **binding-port** - port on which the address will be started and - listen +**Request Body:** -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:: xml + :linenos: + :emphasize-lines: 8,9 -Active mode -~~~~~~~~~~~ - -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: - -- address (must be unique for each configured "monitored-router"), - -- port, - -- active. - -See following example from 42-bmp-example.xml: - -.. code:: xml - - -
192.0.2.2
- 1234 - true - - -Configuration through RESTCONF ------------------------------- - -Server Binding -~~~~~~~~~~~~~~ - -**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>`__* - -**Content-Type:** application/xml - -**Method:** PUT - -**Body:** - -.. code:: xml - - - 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 - - -- change values for **binding-address** and/or **binding-port** - -Active mode -~~~~~~~~~~~ - -**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>`__* - -**Content-Type:** application/xml - -**Method:** PUT - -**Body:** - -.. code:: xml - - - 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 - -
127.0.0.1
- 1234 - true + + example-bmp-monitor + + 12345 + 0.0.0.0 + + +
192.0.2.2
+ changeme - + + +@line 8: **address** - The monitored router's IP address. + +@line 9: **password** - The TCP MD5 signature. + +BMP Monitors Configuration Loader +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +BMP Monitors Configuration Loader allows user to define static initial configuration for a BMP protocol instance. +This service will detect the creation of new configuration files following the pattern "odl-bmp-monitors-*.xml" under the path "etc/opendaylight/bgpcep". +Once the file is processed, the defined configuration will be available from the configuration Data Store. + +.. note:: If the BMP Monitor instance is already present, no update or configuration will be applied. + +**PATH:** ``etc/opendaylight/bgpcep/odl-bmp-monitors-config.xml`` + +.. code-block:: xml + + + + example-bmp-monitor + + 12345 + 0.0.0.0 + + + + +BMP Monitor Configuration Example +''''''''''''''''''''''''''''''''' + +BGP provides a feature providing a BMP Monitor configuration file example. +Once feature is installed defined configuration will be loaded and setup. + +.. code-block:: console + + feature:install odl-bgpcep-bmp-config-example + +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. + + -ra , --remote_address + A list of IP addresses of BMP monitoring station, by default 127.0.0.1:12345. + + --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 -- change values for **address** and **port** +#. Steps to reproduce +#. Attach Karaf log files, optionally packet captures, REST input/output