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

   1 .. _bgp-monitoring-protocol-developer-guide:
   2
   3 BGP Monitoring Protocol Developer Guide
   4 =======================================
   5
   6 Overview
   7 --------
   8
   9 This section provides an overview of **feature odl-bgpcep-bmp**. This
  10 feature will install everything needed for BMP (BGP Monitoring Protocol)
  11 including establishing the connection, processing messages, storing
  12 information about monitored routers, peers and their Adj-RIB-In
  13 (unprocessed routing information) and Post-Policy Adj-RIB-In and
  14 displaying data in BGP RIBs overview. The OpenDaylight BMP plugin plays
  15 the role of a monitoring station.
  16
  17 Key APIs and Interfaces
  18 -----------------------
  19
  20 Session handling
  21 ~~~~~~~~~~~~~~~~
  22
  23 *32-bmp.xml* defines only bmp-dispatcher the parser should be using
  24 (global-bmp-extensions).
  25
  26 .. code:: xml
  27
  28      <module>
  29       <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">prefix:bmp-dispatcher-impl</type>
  30       <name>global-bmp-dispatcher</name>
  31        <bmp-extensions>
  32         <type xmlns:bmp-spi="urn:opendaylight:params:xml:ns:yang:controller:bmp:spi">bmp-spi:extensions</type>
  33         <name>global-bmp-extensions</name>
  34        </bmp-extensions>
  35        <boss-group>
  36         <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
  37         <name>global-boss-group</name>
  38        </boss-group>
  39        <worker-group>
  40         <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
  41         <name>global-worker-group</name>
  42       </worker-group>
  43      </module>
  44
  45 For user configuration of BMP, check User Guide.
  46
  47 Parser
  48 ~~~~~~
  49
  50 The base BMP parser includes messages and attributes from
  51 https://tools.ietf.org/html/draft-ietf-grow-bmp-15
  52
  53 Registration
  54 ~~~~~~~~~~~~
  55
  56 All parsers and serializers need to be registered into *Extension
  57 provider*. This *Extension provider* is configured in initial
  58 configuration of the parser (*32-bmp.xml*).
  59
  60 .. code:: xml
  61
  62      <module>
  63       <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bmp:spi">prefix:bmp-extensions-impl</type>
  64       <name>global-bmp-extensions</name>
  65       <extension>
  66        <type xmlns:bmp-spi="urn:opendaylight:params:xml:ns:yang:controller:bmp:spi">bmp-spi:extension</type>
  67        <name>bmp-parser-base</name>
  68       </extension>
  69      </module>
  70
  71 -  *bmp-parser-base* - will register parsers and serializers implemented
  72    in bmp-impl module
  73
  74 Parsing
  75 ~~~~~~~
  76
  77 Parsing of BMP elements is mostly done equally to BGP. Some of the BMP
  78 messages includes wrapped BGP messages.
  79
  80 BMP Monitoring Station
  81 ~~~~~~~~~~~~~~~~~~~~~~
  82
  83 The BMP application (Monitoring Station) serves as message processor
  84 incoming from monitored routers. The processed message is transformed
  85 and relevant information is stored. Route information is stored in a BGP
  86 RIB data structure.
  87
  88 BMP data is displayed only through one URL that is accessible from the
  89 base BMP URL:
  90
  91 *`http://<controllerIP>:8181/restconf/operational/bmp-monitor:bmp-monitor <http://<controllerIP>:8181/restconf/operational/bmp-monitor:bmp-monitor>`__*
  92
  93 Each Monitor station will be displayed and it may contains multiple
  94 monitored routers and peers within:
  95
  96 .. code:: xml
  97
  98     <bmp-monitor xmlns="urn:opendaylight:params:xml:ns:yang:bmp-monitor">
  99      <monitor>
 100      <monitor-id>example-bmp-monitor</monitor-id>
 101       <router>
 102       <router-id>127.0.0.11</router-id>
 103        <status>up</status>
 104        <peer>
 105         <peer-id>20.20.20.20</peer-id>
 106         <as>72</as>
 107         <type>global</type>
 108         <peer-session>
 109          <remote-port>5000</remote-port>
 110          <timestamp-sec>5</timestamp-sec>
 111          <status>up</status>
 112          <local-address>10.10.10.10</local-address>
 113          <local-port>220</local-port>
 114         </peer-session>
 115         <pre-policy-rib>
 116          <tables>
 117           <afi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:ipv4-address-family</afi>
 118           <safi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:unicast-subsequent-address-family</safi>
 119           <ipv4-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
 120            <ipv4-route>
 121             <prefix>10.10.10.0/24</prefix>
 122              <attributes>
 123               ...
 124              </attributes>
 125            </ipv4-route>
 126           </ipv4-routes>
 127           <attributes>
 128            <uptodate>true</uptodate>
 129           </attributes>
 130          </tables>
 131         </pre-policy-rib>
 132         <address>10.10.10.10</address>
 133         <post-policy-rib>
 134          ...
 135         </post-policy-rib>
 136         <bgp-id>20.20.20.20</bgp-id>
 137         <stats>
 138          <timestamp-sec>5</timestamp-sec>
 139          <invalidated-cluster-list-loop>53</invalidated-cluster-list-loop>
 140          <duplicate-prefix-advertisements>16</duplicate-prefix-advertisements>
 141          <loc-rib-routes>100</loc-rib-routes>
 142          <duplicate-withdraws>11</duplicate-withdraws>
 143          <invalidated-as-confed-loop>55</invalidated-as-confed-loop>
 144          <adj-ribs-in-routes>10</adj-ribs-in-routes>
 145          <invalidated-as-path-loop>66</invalidated-as-path-loop>
 146          <invalidated-originator-id>70</invalidated-originator-id>
 147          <rejected-prefixes>8</rejected-prefixes>
 148         </stats>
 149        </peer>
 150        <name>name</name>
 151        <description>description</description>
 152        <info>some info;</info>
 153       </router>
 154      </monitor>
 155     </bmp-monitor>
 156     </source>
 157
 158 API Reference Documentation
 159 ---------------------------
 160
 161 Javadocs are generated while creating mvn:site and they are located in
 162 target/ directory in each module.