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

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