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

   1 .. _bgp-developer-guide:
   2 BGP Developer Guide
   3 ===================
   4
   5 Overview
   6 --------
   7
   8 This section provides an overview of the ``odl-bgpcep-bgp-all`` Karaf
   9 feature. This feature will install everything needed for BGP (Border
  10 Gateway Protocol) from establishing the connection, storing the data in
  11 RIBs (Route Information Base) and displaying data in network-topology
  12 overview.
  13
  14 BGP Architecture
  15 ----------------
  16
  17 Each feature represents a module in the BGPCEP codebase. The following
  18 diagram illustrates how the features are related.
  19
  20 .. figure:: ./images/bgpcep/bgp-dependency-tree.png
  21    :alt: BGP Dependency Tree
  22
  23    BGP Dependency Tree
  24
  25 Key APIs and Interfaces
  26 -----------------------
  27
  28 BGP concepts
  29 ~~~~~~~~~~~~
  30
  31 This module contains the base BGP concepts contained in `RFC
  32 4271 <http://tools.ietf.org/html/rfc4271>`__, `RFC
  33 4760 <http://tools.ietf.org/html/rfc4760>`__, `RFC
  34 4456 <http://tools.ietf.org/html/rfc4456>`__, `RFC
  35 1997 <http://tools.ietf.org/html/rfc1997>`__ and `RFC
  36 4360 <http://tools.ietf.org/html/rfc4360>`__.
  37
  38 All the concepts are described in one yang model:
  39 `bgp-types.yang <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/concepts/src/main/yang/bgp-types.yang;hb=refs/heads/stable/boron>`__.
  40
  41 Outside generated classes, there is just one class
  42 `NextHopUtil <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/concepts/src/main/java/org/opendaylight/bgp/concepts/NextHopUtil.java;hb=refs/heads/stable/boron>`__
  43 that contains methods for serializing and parsing NextHop.
  44
  45 BGP parser
  46 ~~~~~~~~~~
  47
  48 Base BGP parser includes messages and attributes from `RFC
  49 4271 <http://tools.ietf.org/html/rfc4271>`__, `RFC
  50 4760 <http://tools.ietf.org/html/rfc4760>`__, `RFC
  51 1997 <http://tools.ietf.org/html/rfc1997>`__ and `RFC
  52 4360 <http://tools.ietf.org/html/rfc4360>`__.
  53
  54 *API* module defines BGP messages in YANG.
  55
  56 *IMPL* module contains actual parsers and serializers for BGP messages
  57 and
  58 `Activator <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/parser-impl/src/main/java/org/opendaylight/protocol/bgp/parser/impl/BGPActivator.java;hb=refs/heads/stable/boron>`__
  59 class
  60
  61 *SPI* module contains helper classes needed for registering parsers into
  62 activators
  63
  64 Registration
  65 ^^^^^^^^^^^^
  66
  67 All parsers and serializers need to be registered into the *Extension
  68 provider*. This *Extension provider* is configured in initial
  69 configuration of the parser-spi module (``31-bgp.xml``).
  70
  71 .. code:: xml
  72
  73      <module>
  74       <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">prefix:bgp-extensions-impl</type>
  75       <name>global-bgp-extensions</name>
  76       <extension>
  77        <type xmlns:bgpspi="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">bgpspi:extension</type>
  78        <name>base-bgp-parser</name>
  79       </extension>
  80       <extension>
  81        <type xmlns:bgpspi="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">bgpspi:extension</type>
  82        <name>bgp-linkstate</name>
  83       </extension>
  84      </module>
  85
  86 -  *base-bgp-parser* - will register parsers and serializers implemented
  87    in the bgp-parser-impl module
  88
  89 -  *bgp-linkstate* - will register parsers and serializers implemented
  90    in the bgp-linkstate module
  91
  92 The bgp-linkstate module is a good example of a BGP parser extension.
  93
  94 The configuration of bgp-parser-spi specifies one implementation of
  95 *Extension provider* that will take care of registering mentioned parser
  96 extensions:
  97 `SimpleBGPExtensionProviderContext <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/parser-spi/src/main/java/org/opendaylight/protocol/bgp/parser/spi/pojo/SimpleBGPExtensionProviderContext.java;hb=refs/heads/stable/boron>`__.
  98 All registries are implemented in package
  99 `bgp-parser-spi <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=tree;f=bgp/parser-spi/src/main/java/org/opendaylight/protocol/bgp/parser/spi;hb=refs/heads/stable/boron>`__.
 100
 101 Serializing
 102 ^^^^^^^^^^^
 103
 104 The serializing of BGP elements is mostly done in the same way as in
 105 `PCEP <#_pcep_developer_guide>`__, the only exception is the
 106 serialization of path attributes, which is described here. Path
 107 attributes are different from any other BGP element, as path attributes
 108 don’t implement one common interface, but this interface contains
 109 getters for individual path attributes (this structure is because update
 110 message can contain exactly one instance of each path attribute). This
 111 means, that a given *PathAttributes* object, you can only get to the
 112 specific type of the path attribute through checking its presence.
 113 Therefore method *serialize()* in *AttributeRegistry*, won’t look up the
 114 registered class, instead it will go through the registrations and offer
 115 this object to the each registered parser. This way the object will be
 116 passed also to serializers unknown to module bgp-parser, for example to
 117 LinkstateAttributeParser. RFC 4271 recommends ordering path attributes,
 118 hence the serializers are ordered in a list as they are registered in
 119 the *Activator*. In other words, this is the only case, where
 120 registration ordering matters.
 121
 122 .. figure:: ./images/bgpcep/PathAttributesSerialization.png
 123    :alt: PathAttributesSerialization
 124
 125    PathAttributesSerialization
 126
 127 *serialize()* method in each Path Attribute parser contains check for
 128 presence of its attribute in the PathAttributes object, which simply
 129 returns, if the attribute is not there:
 130
 131 .. code:: java
 132
 133      if (pathAttributes.getAtomicAggregate() == null) {
 134          return;
 135      }
 136      //continue with serialization of Atomic Aggregate
 137
 138 BGP RIB
 139 -------
 140
 141 The BGP RIB module can be divided into two parts:
 142
 143 -  BGP listener and speaker session handling
 144
 145 -  RIB handling.
 146
 147 Session handling
 148 ~~~~~~~~~~~~~~~~
 149
 150 ``31-bgp.xml`` defines only bgp-dispatcher and the parser it should be
 151 using (global-bgp-extensions).
 152
 153 .. code:: xml
 154
 155     <module>
 156      <type>prefix:bgp-dispatcher-impl</type>
 157      <name>global-bgp-dispatcher</name>
 158      <bgp-extensions>
 159       <type>bgpspi:extensions</type>
 160       <name>global-bgp-extensions</name>
 161      </bgp-extensions>
 162      <boss-group>
 163       <type>netty:netty-threadgroup</type>
 164       <name>global-boss-group</name>
 165      </boss-group>
 166      <worker-group>
 167       <type>netty:netty-threadgroup</type>
 168       <name>global-worker-group</name>
 169      </worker-group>
 170     </module>
 171
 172 For user configuration of BGP, check User Guide.
 173
 174 Synchronization
 175 ~~~~~~~~~~~~~~~
 176
 177 Synchronization is a phase, where upon connection, a BGP speaker sends
 178 all available data about topology to its new client. After the whole
 179 topology has been advertised, the synchronization is over. For the
 180 listener, the synchronization is over when the RIB receives End-of-RIB
 181 (EOR) messages. There is a special EOR message for each AFI (Address
 182 Family Identifier).
 183
 184 -  IPv4 EOR is an empty Update message.
 185
 186 -  Ipv6 EOR is an Update message with empty MP\_UNREACH attribute where
 187    AFI and SAFI (Subsequent Address Family Identifier) are set to Ipv6.
 188    OpenDaylight also supports EOR for IPv4 in this format.
 189
 190 -  Linkstate EOR is an Update message with empty MP\_UNREACH attribute
 191    where AFI and SAFI are set to Linkstate.
 192
 193 For BGP connections, where both peers support graceful restart, the EORs
 194 are sent by the BGP speaker and are redirected to RIB, where the
 195 specific AFI/SAFI table is set to *true*. Without graceful restart, the
 196 messages are generated by OpenDaylight itself and sent after second
 197 keepalive for each AFI/SAFI. This is done in
 198 `BGPSynchronization <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/BGPSynchronization.java;hb=refs/heads/stable/boron>`__.
 199
 200 **Peers**
 201
 202 `BGPPeer <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/BGPPeer.java;hb=refs/heads/stable/boron>`__
 203 has various meanings. If you configure BGP listener, *BGPPeer*
 204 represents the BGP listener itself. If you are configuring BGP speaker,
 205 you need to provide a list of peers, that are allowed to connect to this
 206 speaker. Unknown peer represents, in this case, a peer that is allowed
 207 to be refused. *BGPPeer* represents in this case peer, that is supposed
 208 to connect to your speaker. *BGPPeer* is stored in
 209 `BGPPeerRegistry <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/StrictBGPPeerRegistry.java;hb=refs/heads/stable/boron>`__.
 210 This registry controls the number of sessions. Our strict implementation
 211 limits sessions to one per peer.
 212
 213 `ApplicationPeer <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/ApplicationPeer.java;hb=refs/heads/stable/boron>`__
 214 is a special case of peer, that has it’s own RIB. This RIB is populated
 215 from RESTCONF. The RIB is synchronized with default BGP RIB. Incoming
 216 routes to the default RIB are treated in the same way as they were from
 217 a BGP peer (speaker or listener) in the network.
 218
 219 RIB handling
 220 ~~~~~~~~~~~~
 221
 222 RIB (Route Information Base) is defined as a concept in `RFC
 223 4271 <http://tools.ietf.org/html/rfc4271#section-3.2>`__. RFC does not
 224 define how it should be implemented. In our implementation, the routes
 225 are stored in the MD-SAL datastore. There are four supported routes -
 226 *Ipv4Routes*, *Ipv6Routes*, *LinkstateRoutes* and *FlowspecRoutes*.
 227
 228 Each route type needs to provide a
 229 `RIBSupport.java <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-spi/src/main/java/org/opendaylight/protocol/bgp/rib/spi/RIBSupport.java;hb=refs/heads/stable/boron>`__
 230 implementation. *RIBSupport* tells RIB how to parse binding-aware data
 231 (BGP Update message) to binding-independent (datastore format).
 232
 233 Following picture describes the data flow from BGP message that is sent
 234 to *BGPPeer* to datastore and various types of RIB.
 235
 236 .. figure:: ./images/bgpcep/RIB.png
 237    :alt: RIB
 238
 239    RIB
 240
 241 `AdjRibInWriter <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/AdjRibInWriter.java;hb=refs/heads/stable/boron>`__
 242 - represents the first step in putting data to datastore. This writer is
 243 notified whenever a peer receives an Update message. The message is
 244 transformed into binding-independent format and pushed into datastore to
 245 *adj-rib-in*. This RIB is associated with a peer.
 246
 247 `EffectiveRibInWriter <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/EffectiveRibInWriter.java;hb=refs/heads/stable/boron>`__
 248 - this writer is notified whenever *adj-rib-in* is updated. It applies
 249 all configured import policies to the routes and stores them in
 250 *effective-rib-in*. This RIB is also associated with a peer.
 251
 252 `LocRibWriter <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/LocRibWriter.java;hb=refs/heads/stable/boron>`__
 253 - this writer is notified whenever **any** *effective-rib-in* is updated
 254 (in any peer). Performs best path selection filtering and stores the
 255 routes in *loc-rib*. It also determines which routes need to be
 256 advertised and fills in *adj-rib-out* that is per peer as well.
 257
 258 `AdjRibOutListener <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/AdjRibOutListener.java;h=a14fd54a29ea613b381a36248f67491d968963b8;hb=refs/heads/stable/boron>`__
 259 - listens for changes in *adj-rib-out*, transforms the routes into
 260 BGPUpdate messages and sends them to its associated peer.
 261
 262 BGP inet
 263 --------
 264
 265 This module contains only one YANG model
 266 `bgp-inet.yang <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/inet/src/main/yang/bgp-inet.yang;hb=refs/heads/stable/boron>`__
 267 that summarizes the ipv4 and ipv6 extensions to RIB routes and BGP
 268 messages.
 269
 270 BGP flowspec
 271 ------------
 272
 273 BGP flowspec is a module that implements `RFC
 274 5575 <http://tools.ietf.org/html/rfc5575>`__ for IPv4 AFI and
 275 `draft-ietf-idr-flow-spec-v6-06 <https://tools.ietf.org/html/draft-ietf-idr-flow-spec-v6-06>`__
 276 for IPv6 AFI. The RFC defines an extension to BGP in form of a new
 277 subsequent address family, NLRI and extended communities. All of those
 278 are defined in the
 279 `bgp-flowspec.yang <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/flowspec/src/main/yang/bgp-flowspec.yang;hb=refs/heads/stable/boron>`__
 280 model. In addition to generated sources, the module contains parsers for
 281 newly defined elements and RIBSupport for flowspec-routes. The route key
 282 of flowspec routes is a string representing human-readable flowspec
 283 request.
 284
 285 BGP linkstate
 286 -------------
 287
 288 BGP linkstate is a module that implements
 289 `draft-ietf-idr-ls-distribution <http://tools.ietf.org/html/draft-ietf-idr-ls-distribution-04>`__
 290 version 04. The draft defines an extension to BGP in form of a new
 291 address family, subsequent address family, NLRI and path attribute. All
 292 of those are defined in the
 293 `bgp-linkstate.yang <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/linkstate/src/main/yang/bgp-linkstate.yang;hb=refs/heads/stable/boron>`__
 294 model. In addition to generated sources, the module contains
 295 `LinkstateAttributeParser <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/linkstate/src/main/java/org/opendaylight/protocol/bgp/linkstate/attribute/LinkstateAttributeParser.java;hb=refs/heads/stable/boron>`__,
 296 `LinkstateNlriParser <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/linkstate/src/main/java/org/opendaylight/protocol/bgp/linkstate/nlri/LinkstateNlriParser.java;hb=refs/heads/stable/boron>`__,
 297 activators for both, parser and RIB, and RIBSupport handler for
 298 linkstate address family. As each route needs a key, in case of
 299 linkstate, the route key is defined as a binary string, containing all
 300 the NLRI serialized to byte format. The BGP linkstate extension also
 301 supports distribution of MPLS TE state as defined in
 302 `draft-ietf-idr-te-lsp-distribution-03 <https://tools.ietf.org/html/draft-ietf-idr-te-lsp-distribution-03>`__,
 303 extension for Segment Routing
 304 `draft-gredler-idr-bgp-ls-segment-routing-ext-00 <https://tools.ietf.org/html/draft-gredler-idr-bgp-ls-segment-routing-ext-00>`__
 305 and Segment Routing Egress Peer Engineering
 306 `draft-ietf-idr-bgpls-segment-routing-epe-02 <https://tools.ietf.org/html/draft-ietf-idr-bgpls-segment-routing-epe-02>`__.
 307
 308 BGP labeled-unicast
 309 -------------------
 310
 311 BGP labeled unicast is a module that implements `RFC
 312 3107 <https://tools.ietf.org/html/rfc3107>`__. The RFC defines an
 313 extension to the BGP MP to carry Label Mapping Information as a part of
 314 the NLRI. The AFI indicates, as usual, the address family of the
 315 associated route. The fact that the NLRI contains a label is indicated
 316 by using SAFI value 4. All of those are defined in
 317 `bgp-labeled-unicast.yang <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob_plain;f=bgp/labeled-unicast/src/main/yang/bgp-labeled-unicast.yang;hb=refs/heads/stable/boron>`__
 318 model. In addition to the generated sources, the module contains new
 319 NLRI codec and RIBSupport. The route key is defined as a binary, where
 320 whole NLRI information is encoded.
 321
 322 BGP topology provider
 323 ---------------------
 324
 325 BGP data besides RIB, is stored in network-topology view. The format of
 326 how the data is displayed there conforms to
 327 `draft-clemm-netmod-yang-network-topo <https://tools.ietf.org/html/draft-clemm-netmod-yang-network-topo-01>`__.
 328
 329 API Reference Documentation
 330 ---------------------------
 331
 332 Javadocs are generated while creating mvn:site and they are located in
 333 target/ directory in each module.
 334