1 .. _bgp-developer-guide:
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
17 Each feature represents a module in the BGPCEP codebase. The following
18 diagram illustrates how the features are related.
20 .. figure:: ./images/bgpcep/bgp-dependency-tree.png
21 :alt: BGP Dependency Tree
25 Key APIs and Interfaces
26 -----------------------
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>`__.
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>`__.
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.
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>`__.
54 *API* module defines BGP messages in YANG.
56 *IMPL* module contains actual parsers and serializers for BGP messages
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>`__
61 *SPI* module contains helper classes needed for registering parsers into
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``).
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>
77 <type xmlns:bgpspi="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">bgpspi:extension</type>
78 <name>base-bgp-parser</name>
81 <type xmlns:bgpspi="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">bgpspi:extension</type>
82 <name>bgp-linkstate</name>
86 - *base-bgp-parser* - will register parsers and serializers implemented
87 in the bgp-parser-impl module
89 - *bgp-linkstate* - will register parsers and serializers implemented
90 in the bgp-linkstate module
92 The bgp-linkstate module is a good example of a BGP parser extension.
94 The configuration of bgp-parser-spi specifies one implementation of
95 *Extension provider* that will take care of registering mentioned parser
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>`__.
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.
122 .. figure:: ./images/bgpcep/PathAttributesSerialization.png
123 :alt: PathAttributesSerialization
125 PathAttributesSerialization
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:
133 if (pathAttributes.getAtomicAggregate() == null) {
136 //continue with serialization of Atomic Aggregate
141 The BGP RIB module can be divided into two parts:
143 - BGP listener and speaker session handling
150 ``31-bgp.xml`` defines only bgp-dispatcher and the parser it should be
151 using (global-bgp-extensions).
156 <type>prefix:bgp-dispatcher-impl</type>
157 <name>global-bgp-dispatcher</name>
159 <type>bgpspi:extensions</type>
160 <name>global-bgp-extensions</name>
163 <type>netty:netty-threadgroup</type>
164 <name>global-boss-group</name>
167 <type>netty:netty-threadgroup</type>
168 <name>global-worker-group</name>
172 For user configuration of BGP, check User Guide.
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
184 - IPv4 EOR is an empty Update message.
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.
190 - Linkstate EOR is an Update message with empty MP\_UNREACH attribute
191 where AFI and SAFI are set to Linkstate.
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>`__.
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.
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.
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*.
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).
233 Following picture describes the data flow from BGP message that is sent
234 to *BGPPeer* to datastore and various types of RIB.
236 .. figure:: ./images/bgpcep/RIB.png
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.
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.
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.
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.
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
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
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
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>`__.
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.
322 BGP topology provider
323 ---------------------
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>`__.
329 API Reference Documentation
330 ---------------------------
332 Javadocs are generated while creating mvn:site and they are located in
333 target/ directory in each module.