.. _bgp-developer-guide: BGP Developer Guide =================== Overview -------- This section provides an overview of the ``odl-bgpcep-bgp-all`` Karaf feature. This feature will install everything needed for BGP (Border Gateway Protocol) from establishing the connection, storing the data in RIBs (Route Information Base) and displaying data in network-topology overview. BGP Architecture ---------------- Each feature represents a module in the BGPCEP codebase. The following diagram illustrates how the features are related. .. figure:: ./images/bgpcep/bgp-dependency-tree.png :alt: BGP Dependency Tree BGP Dependency Tree Key APIs and Interfaces ----------------------- BGP concepts ~~~~~~~~~~~~ This module contains the base BGP concepts contained in `RFC 4271 `__, `RFC 4760 `__, `RFC 4456 `__, `RFC 1997 `__ and `RFC 4360 `__. All the concepts are described in one yang model: `bgp-types.yang `__. Outside generated classes, there is just one class `NextHopUtil `__ that contains methods for serializing and parsing NextHop. BGP parser ~~~~~~~~~~ Base BGP parser includes messages and attributes from `RFC 4271 `__, `RFC 4760 `__, `RFC 1997 `__ and `RFC 4360 `__. *API* module defines BGP messages in YANG. *IMPL* module contains actual parsers and serializers for BGP messages and `Activator `__ class *SPI* module contains helper classes needed for registering parsers into activators Registration ^^^^^^^^^^^^ All parsers and serializers need to be registered into the *Extension provider*. This *Extension provider* is configured in initial configuration of the parser-spi module (``31-bgp.xml``). .. code:: xml prefix:bgp-extensions-impl global-bgp-extensions bgpspi:extension base-bgp-parser bgpspi:extension bgp-linkstate - *base-bgp-parser* - will register parsers and serializers implemented in the bgp-parser-impl module - *bgp-linkstate* - will register parsers and serializers implemented in the bgp-linkstate module The bgp-linkstate module is a good example of a BGP parser extension. The configuration of bgp-parser-spi specifies one implementation of *Extension provider* that will take care of registering mentioned parser extensions: `SimpleBGPExtensionProviderContext `__. All registries are implemented in package `bgp-parser-spi `__. Serializing ^^^^^^^^^^^ The serializing of BGP elements is mostly done in the same way as in `PCEP <#_pcep_developer_guide>`__, the only exception is the serialization of path attributes, which is described here. Path attributes are different from any other BGP element, as path attributes don’t implement one common interface, but this interface contains getters for individual path attributes (this structure is because update message can contain exactly one instance of each path attribute). This means, that a given *PathAttributes* object, you can only get to the specific type of the path attribute through checking its presence. Therefore method *serialize()* in *AttributeRegistry*, won’t look up the registered class, instead it will go through the registrations and offer this object to the each registered parser. This way the object will be passed also to serializers unknown to module bgp-parser, for example to LinkstateAttributeParser. RFC 4271 recommends ordering path attributes, hence the serializers are ordered in a list as they are registered in the *Activator*. In other words, this is the only case, where registration ordering matters. .. figure:: ./images/bgpcep/PathAttributesSerialization.png :alt: PathAttributesSerialization PathAttributesSerialization *serialize()* method in each Path Attribute parser contains check for presence of its attribute in the PathAttributes object, which simply returns, if the attribute is not there: .. code:: java if (pathAttributes.getAtomicAggregate() == null) { return; } //continue with serialization of Atomic Aggregate BGP RIB ------- The BGP RIB module can be divided into two parts: - BGP listener and speaker session handling - RIB handling. Session handling ~~~~~~~~~~~~~~~~ ``31-bgp.xml`` defines only bgp-dispatcher and the parser it should be using (global-bgp-extensions). .. code:: xml prefix:bgp-dispatcher-impl global-bgp-dispatcher bgpspi:extensions global-bgp-extensions netty:netty-threadgroup global-boss-group netty:netty-threadgroup global-worker-group For user configuration of BGP, check User Guide. Synchronization ~~~~~~~~~~~~~~~ Synchronization is a phase, where upon connection, a BGP speaker sends all available data about topology to its new client. After the whole topology has been advertised, the synchronization is over. For the listener, the synchronization is over when the RIB receives End-of-RIB (EOR) messages. There is a special EOR message for each AFI (Address Family Identifier). - IPv4 EOR is an empty Update message. - Ipv6 EOR is an Update message with empty MP\_UNREACH attribute where AFI and SAFI (Subsequent Address Family Identifier) are set to Ipv6. OpenDaylight also supports EOR for IPv4 in this format. - Linkstate EOR is an Update message with empty MP\_UNREACH attribute where AFI and SAFI are set to Linkstate. For BGP connections, where both peers support graceful restart, the EORs are sent by the BGP speaker and are redirected to RIB, where the specific AFI/SAFI table is set to *true*. Without graceful restart, the messages are generated by OpenDaylight itself and sent after second keepalive for each AFI/SAFI. This is done in `BGPSynchronization `__. **Peers** `BGPPeer `__ has various meanings. If you configure BGP listener, *BGPPeer* represents the BGP listener itself. If you are configuring BGP speaker, you need to provide a list of peers, that are allowed to connect to this speaker. Unknown peer represents, in this case, a peer that is allowed to be refused. *BGPPeer* represents in this case peer, that is supposed to connect to your speaker. *BGPPeer* is stored in `BGPPeerRegistry `__. This registry controls the number of sessions. Our strict implementation limits sessions to one per peer. `ApplicationPeer `__ is a special case of peer, that has it’s own RIB. This RIB is populated from RESTCONF. The RIB is synchronized with default BGP RIB. Incoming routes to the default RIB are treated in the same way as they were from a BGP peer (speaker or listener) in the network. RIB handling ~~~~~~~~~~~~ RIB (Route Information Base) is defined as a concept in `RFC 4271 `__. RFC does not define how it should be implemented. In our implementation, the routes are stored in the MD-SAL datastore. There are four supported routes - *Ipv4Routes*, *Ipv6Routes*, *LinkstateRoutes* and *FlowspecRoutes*. Each route type needs to provide a `RIBSupport.java `__ implementation. *RIBSupport* tells RIB how to parse binding-aware data (BGP Update message) to binding-independent (datastore format). Following picture describes the data flow from BGP message that is sent to *BGPPeer* to datastore and various types of RIB. .. figure:: ./images/bgpcep/RIB.png :alt: RIB RIB `AdjRibInWriter `__ - represents the first step in putting data to datastore. This writer is notified whenever a peer receives an Update message. The message is transformed into binding-independent format and pushed into datastore to *adj-rib-in*. This RIB is associated with a peer. `EffectiveRibInWriter `__ - this writer is notified whenever *adj-rib-in* is updated. It applies all configured import policies to the routes and stores them in *effective-rib-in*. This RIB is also associated with a peer. `LocRibWriter `__ - this writer is notified whenever **any** *effective-rib-in* is updated (in any peer). Performs best path selection filtering and stores the routes in *loc-rib*. It also determines which routes need to be advertised and fills in *adj-rib-out* that is per peer as well. `AdjRibOutListener `__ - listens for changes in *adj-rib-out*, transforms the routes into BGPUpdate messages and sends them to its associated peer. BGP inet -------- This module contains only one YANG model `bgp-inet.yang `__ that summarizes the ipv4 and ipv6 extensions to RIB routes and BGP messages. BGP flowspec ------------ BGP flowspec is a module that implements `RFC 5575 `__ for IPv4 AFI and `draft-ietf-idr-flow-spec-v6-06 `__ for IPv6 AFI. The RFC defines an extension to BGP in form of a new subsequent address family, NLRI and extended communities. All of those are defined in the `bgp-flowspec.yang `__ model. In addition to generated sources, the module contains parsers for newly defined elements and RIBSupport for flowspec-routes. The route key of flowspec routes is a string representing human-readable flowspec request. BGP linkstate ------------- BGP linkstate is a module that implements `draft-ietf-idr-ls-distribution `__ version 04. The draft defines an extension to BGP in form of a new address family, subsequent address family, NLRI and path attribute. All of those are defined in the `bgp-linkstate.yang `__ model. In addition to generated sources, the module contains `LinkstateAttributeParser `__, `LinkstateNlriParser `__, activators for both, parser and RIB, and RIBSupport handler for linkstate address family. As each route needs a key, in case of linkstate, the route key is defined as a binary string, containing all the NLRI serialized to byte format. The BGP linkstate extension also supports distribution of MPLS TE state as defined in `draft-ietf-idr-te-lsp-distribution-03 `__, extension for Segment Routing `draft-gredler-idr-bgp-ls-segment-routing-ext-00 `__ and Segment Routing Egress Peer Engineering `draft-ietf-idr-bgpls-segment-routing-epe-02 `__. BGP labeled-unicast ------------------- BGP labeled unicast is a module that implements `RFC 3107 `__. The RFC defines an extension to the BGP MP to carry Label Mapping Information as a part of the NLRI. The AFI indicates, as usual, the address family of the associated route. The fact that the NLRI contains a label is indicated by using SAFI value 4. All of those are defined in `bgp-labeled-unicast.yang `__ model. In addition to the generated sources, the module contains new NLRI codec and RIBSupport. The route key is defined as a binary, where whole NLRI information is encoded. BGP topology provider --------------------- BGP data besides RIB, is stored in network-topology view. The format of how the data is displayed there conforms to `draft-clemm-netmod-yang-network-topo `__. API Reference Documentation --------------------------- Javadocs are generated while creating mvn:site and they are located in target/ directory in each module.