docs/user-guide/bgp-monitoring-protocol-user-guide.rst

   1 .. _bgp-monitoring-protocol-user-guide:
   2 BGP Monitoring Protocol User Guide
   3 ==================================
   4 This guide contains information on how to use the OpenDaylight BGP Monitoring Protocol (BMP) plugin.
   5 It covers BMP basic concepts, supported capabilities, configuration and operations.
   6
   7 .. contents:: Contents
   8    :depth: 1
   9    :local:
  10
  11 Overview
  12 --------
  13 This section provides high-level overview of the BMP plugin, OpenDaylight implementation and BMP usage for SDN.
  14
  15 .. contents:: Contents
  16    :depth: 2
  17    :local:
  18
  19 BGP Monitoring Protocol
  20 ^^^^^^^^^^^^^^^^^^^^^^^
  21 The BGP Monitoring Protocol (BMP) serves to monitor BGP sessions.
  22 The BMP can be used to obtain route view instead of screen scraping.
  23 The BMP provides access to unprocessed routing information (Adj-RIB-In) and processed routes (applied inbound policy) of monitored router's peer.
  24 In addition, monitored router can provide periodic dump of statistics.
  25
  26 The BMP runs over TCP.
  27 Both monitored router and monitoring station can be configured as active or passive party of the connection.
  28 The passive party listens at particular port.
  29 The router can be monitored by multiple monitoring stations.
  30 BMP messages are sent by monitored router only, monitoring station supposed to collect and process data received over BMP.
  31
  32 .. figure:: ./images/bgpcep/bmp.png
  33    :align: center
  34    :alt: BMP
  35
  36    The BMP overview - Monitoring Station, Monitored Router and Monitored Peers.
  37
  38
  39 BMP in SDN
  40 ^^^^^^^^^^
  41 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.
  42
  43 Moreover, BMP provides provides peer RIBs visibility, without need to establish BGP sessions.
  44 Unprocessed routes may serve as a source of information for software-driven routing optimization.
  45 In this case, SDN controller, a BMP monitoring station, collects routing information from monitored routers.
  46 The routes are used in subsequent optimization procedures.
  47
  48
  49 OpenDaylight BMP plugin
  50 ^^^^^^^^^^^^^^^^^^^^^^^
  51 The OpenDaylight BMP plugin provides monitoring station implementation.
  52 The plugin can establish BMP session with one or more monitored routers in order to collect routing and statistical information.
  53
  54 * Runtime configurable monitoring station
  55 * Read-only routes and statistics view
  56 * Supports various routing information types
  57
  58 .. figure:: ./images/bgpcep/bmp-plugin.png
  59    :align: center
  60    :alt: BMP plugin
  61
  62    OpenDaylight BMP plugin overview.
  63
  64 .. important:: The BMP plugin is not storing historical data, it provides current snapshot only.
  65
  66 List of supported capabilities
  67 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  68 The BMP plugin implementation is based on Internet standards:
  69
  70 * `RFC7854 <https://tools.ietf.org/html/rfc7854>`_ - BGP Monitoring Protocol (BMP)
  71
  72 .. note:: The BMP plugin is capable to process various types of routing information (IP Unicast, EVPN, L3VPN, Link-State,...).
  73    Please, see complete list in BGP user guide.
  74
  75 Running BMP
  76 -----------
  77 This section explains how to install BMP plugin.
  78
  79 1. Install BMP feature - ``odl-bgpcep-bmp``.
  80    Also, for sake of this sample, it is required to install RESTCONF.
  81    In the Karaf console, type command:
  82
  83    .. code-block:: console
  84
  85       feature:install odl-restconf odl-bgpcep-bmp
  86
  87 2. The BMP plugin contains a default configuration, which is applied after the feature starts up.
  88    One instance of BMP monitoring station is created (named *example-bmp-monitor*), and its presence can be verified via REST:
  89
  90    **URL:** ``/restconf/config/odl-bmp-monitor-config:odl-bmp-monitors/bmp-monitor-config/example-bmp-monitor``
  91
  92    **Method:** ``GET``
  93
  94    **Response Body:**
  95
  96    .. code-block:: xml
  97
  98       <bmp-monitor-config xmlns="urn:opendaylight:params:xml:ns:yang:bmp-monitor-config">
  99          <monitor-id>example-bmp-monitor</monitor-id>
 100          <server>
 101             <binding-port>12345</binding-port>
 102             <binding-address>0.0.0.0</binding-address>
 103          </server>
 104       </bmp-monitor-config>
 105
 106 BMP Monitoring Station
 107 ----------------------
 108 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.
 109
 110 The monitoring station is responsible for received BMP PDUs processing and storage.
 111 The default BMP server is listening at port *12345*.
 112
 113 .. contents:: Contents
 114    :depth: 2
 115    :local:
 116
 117 Configuration
 118 ^^^^^^^^^^^^^
 119 This section shows the way to configure the BMP monitoring station via REST API.
 120
 121 Monitoring station configuration
 122 ''''''''''''''''''''''''''''''''
 123 In order to change default's BMP monitoring station configuration, use following request.
 124
 125 **URL:** ``/restconf/config/odl-bmp-monitor-config:odl-bmp-monitors/bmp-monitor-config/example-bmp-monitor``
 126
 127 **Method:** ``PUT``
 128
 129 **Content-Type:** ``application/xml``
 130
 131 **Request Body:**
 132
 133 .. code-block:: xml
 134    :linenos:
 135    :emphasize-lines: 4,5
 136
 137    <bmp-monitor-config xmlns="urn:opendaylight:params:xml:ns:yang:bmp-monitor-config">
 138       <monitor-id>example-bmp-monitor</monitor-id>
 139       <server>
 140          <binding-port>12345</binding-port>
 141          <binding-address>0.0.0.0</binding-address>
 142       </server>
 143    </bmp-monitor-config>
 144
 145 @line 4: **binding-port** - The BMP server listening port.
 146
 147 @line 5: **binding-address** - The BMP server biding address.
 148
 149 .. note:: User may create multiple BMP monitoring station instances at runtime.
 150
 151 Active mode configuration
 152 '''''''''''''''''''''''''
 153 In order to enable active connection, use following request.
 154
 155 **URL:** ``/restconf/config/odl-bmp-monitor-config:odl-bmp-monitors/bmp-monitor-config/example-bmp-monitor``
 156
 157 **Method:** ``PUT``
 158
 159 **Content-Type:** ``application/xml``
 160
 161 **Request Body:**
 162
 163 .. code-block:: xml
 164    :linenos:
 165    :emphasize-lines: 8,9,10
 166
 167    <bmp-monitor-config xmlns="urn:opendaylight:params:xml:ns:yang:bmp-monitor-config">
 168       <monitor-id>example-bmp-monitor</monitor-id>
 169       <server>
 170          <binding-port>12345</binding-port>
 171          <binding-address>0.0.0.0</binding-address>
 172       </server>
 173       <monitored-router>
 174          <address>192.0.2.2</address>
 175          <port>1234</port>
 176          <active>true</active>
 177       </monitored-router>
 178    </bmp-monitor-config>
 179
 180 @line 8: **address** - The monitored router's IP address.
 181
 182 @line 9: **port** - The monitored router's port.
 183
 184 @line 10: **active** - Active mode set.
 185
 186 .. note:: User may configure active session establishment for multiple monitored routers.
 187
 188 MD5 authentication configuration
 189 ''''''''''''''''''''''''''''''''
 190 In order to enable active connection, use following request.
 191
 192 **URL:** ``/restconf/config/odl-bmp-monitor-config:odl-bmp-monitors/bmp-monitor-config/example-bmp-monitor``
 193
 194 **Method:** ``PUT``
 195
 196 **Content-Type:** ``application/xml``
 197
 198 **Request Body:**
 199
 200 .. code-block:: xml
 201    :linenos:
 202    :emphasize-lines: 8,9
 203
 204    <bmp-monitor-config xmlns="urn:opendaylight:params:xml:ns:yang:bmp-monitor-config">
 205       <monitor-id>example-bmp-monitor</monitor-id>
 206       <server>
 207          <binding-port>12345</binding-port>
 208          <binding-address>0.0.0.0</binding-address>
 209       </server>
 210       <monitored-router>
 211          <address>192.0.2.2</address>
 212          <password>changeme</password>
 213       </monitored-router>
 214    </bmp-monitor-config>
 215
 216 @line 8: **address** - The monitored router's IP address.
 217
 218 @line 9: **password** - The TCP MD5 signature.
 219
 220 Collector DB Tree
 221 ^^^^^^^^^^^^^^^^^
 222
 223 .. code-block:: console
 224
 225    module: bmp-monitor
 226       +--rw bmp-monitor
 227          +--ro monitor* [monitor-id]
 228             +--ro monitor-id    monitor-id
 229             +--ro router* [router-id]
 230                +--ro name?          string
 231                +--ro description?   string
 232                +--ro info?          string
 233                +--ro router-id      router-id
 234                +--ro status?        status
 235                +--ro peer* [peer-id]
 236                   +--ro peer-id                 rib:peer-id
 237                   +--ro type                    peer-type
 238                   x--ro distinguisher
 239                   |  +--ro distinguisher-type?   distinguisher-type
 240                   |  +--ro distinguisher?        string
 241                   +--ro peer-distinguisher?     union
 242                   +--ro address                 inet:ip-address
 243                   +--ro as                      inet:as-number
 244                   +--ro bgp-id                  inet:ipv4-address
 245                   +--ro router-distinguisher?   string
 246                   +--ro peer-session
 247                   |  +--ro local-address      inet:ip-address
 248                   |  +--ro local-port         inet:port-number
 249                   |  +--ro remote-port        inet:port-number
 250                   |  +--ro sent-open
 251                   |  |  +--ro version?          protocol-version
 252                   |  |  +--ro my-as-number?     uint16
 253                   |  |  +--ro hold-timer        uint16
 254                   |  |  +--ro bgp-identifier    inet:ipv4-address
 255                   |  |  +--ro bgp-parameters*
 256                   |  |     +--ro optional-capabilities*
 257                   |  |        +--ro c-parameters
 258                   |  |           +--ro as4-bytes-capability
 259                   |  |           |  +--ro as-number?   inet:as-number
 260                   |  |           +--ro bgp-extended-message-capability!
 261                   |  |           +--ro multiprotocol-capability
 262                   |  |           |  +--ro afi?    identityref
 263                   |  |           |  +--ro safi?   identityref
 264                   |  |           +--ro graceful-restart-capability
 265                   |  |           |  +--ro restart-flags    bits
 266                   |  |           |  +--ro restart-time     uint16
 267                   |  |           |  +--ro tables* [afi safi]
 268                   |  |           |     +--ro afi          identityref
 269                   |  |           |     +--ro safi         identityref
 270                   |  |           |     +--ro afi-flags    bits
 271                   |  |           +--ro add-path-capability
 272                   |  |           |  +--ro address-families*
 273                   |  |           |     +--ro afi?            identityref
 274                   |  |           |     +--ro safi?           identityref
 275                   |  |           |     +--ro send-receive?   send-receive
 276                   |  |           +--ro route-refresh-capability!
 277                   |  +--ro received-open
 278                   |  |  +--ro version?          protocol-version
 279                   |  |  +--ro my-as-number?     uint16
 280                   |  |  +--ro hold-timer        uint16
 281                   |  |  +--ro bgp-identifier    inet:ipv4-address
 282                   |  |  +--ro bgp-parameters*
 283                   |  |     +--ro optional-capabilities*
 284                   |  |        +--ro c-parameters
 285                   |  |           +--ro as4-bytes-capability
 286                   |  |           |  +--ro as-number?   inet:as-number
 287                   |  |           +--ro bgp-extended-message-capability!
 288                   |  |           +--ro multiprotocol-capability
 289                   |  |           |  +--ro afi?    identityref
 290                   |  |           |  +--ro safi?   identityref
 291                   |  |           +--ro graceful-restart-capability
 292                   |  |           |  +--ro restart-flags    bits
 293                   |  |           |  +--ro restart-time     uint16
 294                   |  |           |  +--ro tables* [afi safi]
 295                   |  |           |     +--ro afi          identityref
 296                   |  |           |     +--ro safi         identityref
 297                   |  |           |     +--ro afi-flags    bits
 298                   |  |           +--ro add-path-capability
 299                   |  |           |  +--ro address-families*
 300                   |  |           |     +--ro afi?            identityref
 301                   |  |           |     +--ro safi?           identityref
 302                   |  |           |     +--ro send-receive?   send-receive
 303                   |  |           +--ro route-refresh-capability!
 304                   |  +--ro information
 305                   |  |  +--ro string-information*
 306                   |  |     +--ro string-tlv
 307                   |  |        +--ro string-info?   string
 308                   |  +--ro status?            status
 309                   |  +--ro timestamp-sec?     yang:timestamp
 310                   |  +--ro timestamp-micro?   yang:timestamp
 311                   +--ro stats
 312                   |  +--ro rejected-prefixes?                 yang:counter32
 313                   |  +--ro duplicate-prefix-advertisements?   yang:counter32
 314                   |  +--ro duplicate-withdraws?               yang:counter32
 315                   |  +--ro invalidated-cluster-list-loop?     yang:counter32
 316                   |  +--ro invalidated-as-path-loop?          yang:counter32
 317                   |  +--ro invalidated-originator-id?         yang:counter32
 318                   |  +--ro invalidated-as-confed-loop?        yang:counter32
 319                   |  +--ro adj-ribs-in-routes?                yang:gauge64
 320                   |  +--ro loc-rib-routes?                    yang:gauge64
 321                   |  +--ro per-afi-safi-adj-rib-in-routes
 322                   |  |  +--ro afi-safi* [afi safi]
 323                   |  |     +--ro afi      identityref
 324                   |  |     +--ro safi     identityref
 325                   |  |     +--ro count?   yang:gauge64
 326                   |  +--ro per-afi-safi-loc-rib-routes
 327                   |  |  +--ro afi-safi* [afi safi]
 328                   |  |     +--ro afi      identityref
 329                   |  |     +--ro safi     identityref
 330                   |  |     +--ro count?   yang:gauge64
 331                   |  +--ro updates-treated-as-withdraw?       yang:counter32
 332                   |  +--ro prefixes-treated-as-withdraw?      yang:counter32
 333                   |  +--ro duplicate-updates?                 yang:counter32
 334                   |  +--ro timestamp-sec?                     yang:timestamp
 335                   |  +--ro timestamp-micro?                   yang:timestamp
 336                   +--ro pre-policy-rib
 337                   |  +--ro tables* [afi safi]
 338                   |     +--ro afi           identityref
 339                   |     +--ro safi          identityref
 340                   |     +--ro attributes
 341                   |     |  +--ro uptodate?   boolean
 342                   |     +--ro (routes)?
 343                   +--ro post-policy-rib
 344                   |  +--ro tables* [afi safi]
 345                   |     +--ro afi           identityref
 346                   |     +--ro safi          identityref
 347                   |     +--ro attributes
 348                   |     |  +--ro uptodate?   boolean
 349                   |     +--ro (routes)?
 350                   +--ro mirrors
 351                      +--ro information?       bmp-msg:mirror-information-code
 352                      +--ro timestamp-sec?     yang:timestamp
 353                      +--ro timestamp-micro?   yang:timestamp
 354
 355
 356 Operations
 357 ^^^^^^^^^^
 358 The BMP plugin offers view of collected routes and statistical information from monitored peers.
 359 To get top-level view of monitoring station:
 360
 361 **URL:** ``/restconf/operational/bmp-monitor:bmp-monitor/monitor/example-bmp-monitor``
 362
 363 **Method:** ``GET``
 364
 365 **Response Body:**
 366
 367 .. code-block:: xml
 368    :linenos:
 369    :emphasize-lines: 3,5,11,12,13,14,15,17,20,21,22,27,33,50,53
 370
 371    <bmp-monitor xmlns="urn:opendaylight:params:xml:ns:yang:bmp-monitor">
 372       <monitor>
 373          <monitor-id>example-bmp-monitor</monitor-id>
 374             <router>
 375                <router-id>10.10.10.10</router-id>
 376                <name>name</name>
 377                <description>monitored-router</description>
 378                <info>monitored router;</info>
 379                <status>up</status>
 380                <peer>
 381                    <peer-id>20.20.20.20</peer-id>
 382                    <address>20.20.20.20</address>
 383                    <bgp-id>20.20.20.20</bgp-id>
 384                    <as>65000</as>
 385                    <type>global</type>
 386                    <peer-session>
 387                      <remote-port>1790</remote-port>
 388                      <timestamp-sec>0</timestamp-sec>
 389                      <status>up</status>
 390                      <local-address>10.10.10.10</local-address>
 391                      <local-port>2200</local-port>
 392                      <received-open>
 393                         <hold-timer>180</hold-timer>
 394                         <my-as-number>65000</my-as-number>
 395                         <bgp-identifier>20.20.20.20</bgp-identifier>
 396                      </received-open>
 397                      <sent-open>
 398                         <hold-timer>180</hold-timer>
 399                         <my-as-number>65000</my-as-number>
 400                         <bgp-identifier>65000</bgp-identifier>
 401                      </sent-open>
 402                    </peer-session>
 403                    <pre-policy-rib>
 404                      <tables>
 405                         <afi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:ipv4-address-family</afi>
 406                         <safi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:unicast-subsequent-address-family</safi>
 407                         <ipv4-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
 408                            <ipv4-route>
 409                               <prefix>10.10.10.0/24</prefix>
 410                               <attributes>
 411                               ...
 412                               </attributes>
 413                            </ipv4-route>
 414                         </ipv4-routes>
 415                         <attributes>
 416                            <uptodate>true</uptodate>
 417                         </attributes>
 418                      </tables>
 419                    </pre-policy-rib>
 420                    <post-policy-rib>
 421                      ...
 422                    </post-policy-rib>
 423                    <stats>
 424                      <timestamp-sec>0</timestamp-sec>
 425                      <invalidated-cluster-list-loop>0</invalidated-cluster-list-loop>
 426                      <duplicate-prefix-advertisements>0</duplicate-prefix-advertisements>
 427                      <loc-rib-routes>100</loc-rib-routes>
 428                      <duplicate-withdraws>0</duplicate-withdraws>
 429                      <invalidated-as-confed-loop>0</invalidated-as-confed-loop>
 430                      <adj-ribs-in-routes>10</adj-ribs-in-routes>
 431                      <invalidated-as-path-loop>0</invalidated-as-path-loop>
 432                      <invalidated-originator-id>0</invalidated-originator-id>
 433                      <rejected-prefixes>8</rejected-prefixes>
 434                   </stats>
 435                </peer>
 436          </router>
 437       </monitor>
 438    </bmp-monitor>
 439
 440 @line 3: **monitor-id** - The BMP monitoring station instance identifier.
 441
 442 @line 5: **router-id** - The monitored router IP address, serves as an identifier.
 443
 444 @line 11: **peer-id** - The monitored peer's BGP identifier, serves a an identifier.
 445
 446 @line 12: **address** - The IP address of the peer, associated with the TCP session.
 447
 448 @line 13: **bgp-id** - The BGP Identifier of the peer.
 449
 450 @line 14: **as** - The Autonomous System number of the peer.
 451
 452 @line 15: **type** - Identifies type of the peer - *Global Instance*, *RD Instance* or *Local Instance*
 453
 454 @line 17: **remote-port** - The peer's port number associated with TCP session.
 455
 456 @line 20: **local-address** - The IP address of the monitored router associated with the peering TCP session.
 457
 458 @line 21: **local-port** - The port number of the monitored router associated with the peering TCP session.
 459
 460 @line 22: **received-open** - The full OPEN message received by monitored router from the peer.
 461
 462 @line 27: **sent-open** - The full OPEN message send by monitored router to the peer.
 463
 464 @line 33: **pre-policy-rib** - The Adj-RIB-In that contains unprocessed routing information.
 465
 466 @line 50: **post-policy-rib** - The Post-Policy Ad-RIB-In that contains routes filtered by inbound policy.
 467
 468 @line 53: **stats** - Contains various statistics, periodically updated by the router.
 469
 470 -----
 471
 472 * To view collected information from particular monitored router:
 473       **URL:** ``/restconf/operational/bmp-monitor:bmp-monitor/monitor/example-bmp-monitor/router/10.10.10.10``
 474
 475 * To view collected information from particular monitored peer:
 476       **URL:** ``/restconf/operational/bmp-monitor:bmp-monitor/monitor/example-bmp-monitor/router/10.10.10.10/peer/20.20.20.20``
 477
 478 Test tools
 479 ----------
 480 BMP test tool serves to test basic BMP functionality, scalability and performance.
 481
 482 BMP mock
 483 ^^^^^^^^
 484 The BMP mock is a stand-alone Java application purposed to simulate a BMP-enabled router(s) and peers.
 485 The simulator is capable to report dummy routes and statistics.
 486 This application is not part of the OpenDaylight Karaf distribution, however it can be downloaded from OpenDaylight's Nexus (use latest release version):
 487
 488 ``https://nexus.opendaylight.org/content/repositories/opendaylight.release/org/opendaylight/bgpcep/bgp-bmp-mock``
 489
 490 Usage
 491 '''''
 492 The application can be run from command line:
 493
 494 .. code-block:: console
 495
 496    java -jar bgp-bmp-mock-*-executable.jar
 497
 498
 499 with optional input parameters:
 500
 501 .. code-block:: console
 502
 503    --local_address <address> (optional, default 127.0.0.1)
 504       The IPv4 address where BMP mock is bind to.
 505
 506    --remote_address <address:port> (optional, default 127.0.0.1:12345)
 507       The remote IPv4 Address and port number of BMP monitoring station.
 508
 509    --passive (optional, not present by default)
 510       This flags enables passive mode for simulated routers.
 511
 512    --routers_count <0..N> (optional, default 1)
 513        An amount of BMP routers to be connected to the BMP monitoring station.
 514
 515    --peers_count <0..N> (optional, default 0)
 516       An amount of peers reported by each BMP router.
 517
 518    --pre_policy_routes <0..N> (optional, default 0)
 519       An amount of "pre-policy" simple IPv4 routes reported by each peer.
 520
 521    --post_policy_routes <0..N> (optional, default 0)
 522       An amount of "post-policy" simple IPv4 routes reported by each peer.
 523
 524    --log_level <FATAL|ERROR|INFO|DEBUG|TRACE> (optional, default INFO)
 525       Set logging level for BMP mock.
 526
 527 Troubleshooting
 528 ---------------
 529 This section offers advices in a case OpenDaylight BMP plugin is not working as expected.
 530
 531 .. contents:: Contents
 532    :depth: 2
 533    :local:
 534
 535 BMP is not working...
 536 ^^^^^^^^^^^^^^^^^^^^^
 537 * First of all, ensure that all required features are installed, local monitoring station and monitored router/peers configuration is correct.
 538
 539   To list all installed features in OpenDaylight use the following command at the Karaf console:
 540
 541   .. code-block:: console
 542
 543      feature:list -i
 544
 545 * Check OpenDaylight Karaf logs:
 546
 547   From Karaf console:
 548
 549   .. code-block:: console
 550
 551      log:tail
 552
 553   or open log file: ``data/log/karaf.log``
 554
 555   Possibly, a reason/hint for a cause of the problem can be found there.
 556
 557 * Try to minimize effect of other OpenDaylight features, when searching for a reason of the problem.
 558
 559 * Try to set DEBUG severity level for BMP logger via Karaf console commands, in order to collect more information:
 560
 561   .. code-block:: console
 562
 563      log:set DEBUG org.opendaylight.protocol.bmp
 564
 565 Bug reporting
 566 ^^^^^^^^^^^^^
 567 Before you report a bug, check `BGPCEP Bugzilla <https://bugs.opendaylight.org/buglist.cgi?list_id=65849&product=bgpcep&resolution=--->`_ to ensure same/similar bug is not already filed there.
 568
 569 Write an e-mail to bgpcep-users@lists.opendaylight.org and provide following information:
 570
 571 #. State OpenDaylight version
 572
 573 #. Describe your use-case and provide as much details related to BMP as possible
 574
 575 #. Steps to reproduce
 576
 577 #. Attach Karaf log files, optionally packet captures, REST input/output