1 .. _bgp-developer-guide:
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
18 Each feature represents a module in the BGPCEP codebase. The following
19 diagram illustrates how the features are related.
21 .. figure:: ./images/bgpcep/bgp-dependency-tree.png
22 :alt: BGP Dependency Tree
26 Key APIs and Interfaces
27 -----------------------
32 This module contains the base BGP concepts contained in `RFC
33 4271 <https://tools.ietf.org/html/rfc4271>`__, `RFC
34 4760 <https://tools.ietf.org/html/rfc4760>`__, `RFC
35 4456 <https://tools.ietf.org/html/rfc4456>`__, `RFC
36 1997 <https://tools.ietf.org/html/rfc1997>`__ and `RFC
37 4360 <https://tools.ietf.org/html/rfc4360>`__.
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>`__.
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.
49 Base BGP parser includes messages and attributes from `RFC
50 4271 <https://tools.ietf.org/html/rfc4271>`__, `RFC
51 4760 <https://tools.ietf.org/html/rfc4760>`__, `RFC
52 1997 <https://tools.ietf.org/html/rfc1997>`__ and `RFC
53 4360 <https://tools.ietf.org/html/rfc4360>`__.
55 *API* module defines BGP messages in YANG.
57 *IMPL* module contains actual parsers and serializers for BGP messages
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>`__
62 *SPI* module contains helper classes needed for registering parsers into
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``).
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>
78 <type xmlns:bgpspi="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">bgpspi:extension</type>
79 <name>base-bgp-parser</name>
82 <type xmlns:bgpspi="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">bgpspi:extension</type>
83 <name>bgp-linkstate</name>
87 - *base-bgp-parser* - will register parsers and serializers implemented
88 in the bgp-parser-impl module
90 - *bgp-linkstate* - will register parsers and serializers implemented
91 in the bgp-linkstate module
93 The bgp-linkstate module is a good example of a BGP parser extension.
95 The configuration of bgp-parser-spi specifies one implementation of
96 *Extension provider* that will take care of registering mentioned parser
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>`__.
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.
123 .. figure:: ./images/bgpcep/PathAttributesSerialization.png
124 :alt: PathAttributesSerialization
126 PathAttributesSerialization
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:
134 if (pathAttributes.getAtomicAggregate() == null) {
137 //continue with serialization of Atomic Aggregate
142 The BGP RIB module can be divided into two parts:
144 - BGP listener and speaker session handling
151 ``31-bgp.xml`` defines only bgp-dispatcher and the parser it should be
152 using (global-bgp-extensions).
157 <type>prefix:bgp-dispatcher-impl</type>
158 <name>global-bgp-dispatcher</name>
160 <type>bgpspi:extensions</type>
161 <name>global-bgp-extensions</name>
164 <type>netty:netty-threadgroup</type>
165 <name>global-boss-group</name>
168 <type>netty:netty-threadgroup</type>
169 <name>global-worker-group</name>
173 For user configuration of BGP, check User Guide.
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
185 - IPv4 EOR is an empty Update message.
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.
191 - Linkstate EOR is an Update message with empty MP\_UNREACH attribute
192 where AFI and SAFI are set to Linkstate.
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>`__.
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.
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.
223 RIB (Route Information Base) is defined as a concept in `RFC
224 4271 <https://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*.
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).
234 Following picture describes the data flow from BGP message that is sent
235 to *BGPPeer* to datastore and various types of RIB.
237 .. figure:: ./images/bgpcep/RIB.png
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.
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.
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.
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.
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
274 BGP flowspec is a module that implements `RFC
275 5575 <https://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
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
289 BGP linkstate is a module that implements
290 `draft-ietf-idr-ls-distribution <https://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/extensions/linkstate/src/main/java/org/opendaylight/protocol/bgp/linkstate/impl/attribute/LinkstateAttributeParser.java;hb=HEAD>`__,
297 `LinkstateNlriParser <https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/extensions/linkstate/src/main/java/org/opendaylight/protocol/bgp/linkstate/impl/nlri/LinkstateNlriParser.java;hb=HEAD>`__,
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>`__.
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.
323 BGP topology provider
324 ---------------------
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>`__.
330 API Reference Documentation
331 ---------------------------
333 Javadocs are generated while creating mvn:site and they are located in
334 target/ directory in each module.