docs/bgp-developer-guide.rst

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