Fix MRI project list
[docs.git] / docs / user-guide / bgpcep-guide / bgp / bgp-user-guide-evpn-family.rst
1 .. _bgp-user-guide-evpn-family:
2
3 EVPN Family
4 ===========
5 The BGP MPLS-Based Ethernet VPN (BGP EVPN) Multiprotocol extension can be used to distribute Ethernet L2VPN service related routes in order to support a concept of MAC routing.
6 A major use-case for BGP EVPN is data-center interconnection (DCI), where advantage of BGP EVPN are MAC/IP address advertising across MPLS network, Multihoming functionality including Fast Convergence, Split Horizon and Aliasing support, VM (MAC) Mobility, support Multicast and Broadcast traffic.
7 In addition to MPLS, IP tunnelling encapsulation techniques like VXLAN, NVGRE, MPLSoGRE and others can be used for packet transportation.
8 Also, Provider Backbone Bridging (PBB) can be combined with EVPN in order to reduce a number of MAC Advertisement routes.
9
10 .. contents:: Contents
11    :depth: 2
12    :local:
13
14 Configuration
15 ^^^^^^^^^^^^^
16 This section shows a way to enable EVPN family in BGP speaker and peer configuration.
17
18 BGP Speaker
19 '''''''''''
20 To enable EVPN support in BGP plugin, first configure BGP speaker instance:
21
22 **URL:** ``/restconf/config/openconfig-network-instance:network-instances/network-instance/global-bgp/openconfig-network-instance:protocols``
23
24 **Method:** ``POST``
25
26 **Content-Type:** ``application/xml``
27
28 **Request Body:**
29
30 .. code-block:: xml
31
32    <protocol xmlns="http://openconfig.net/yang/network-instance">
33        <name>bgp-example</name>
34        <identifier xmlns:x="http://openconfig.net/yang/policy-types">x:BGP</identifier>
35        <bgp xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
36            <global>
37                <config>
38                    <router-id>192.0.2.2</router-id>
39                    <as>65000</as>
40                </config>
41                <afi-safis>
42                    <afi-safi>
43                        <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:L2VPN-EVPN</afi-safi-name>
44                    </afi-safi>
45                </afi-safis>
46            </global>
47        </bgp>
48    </protocol>
49
50 BGP Peer
51 ''''''''
52 Here is an example for BGP peer configuration with enabled EVPN family.
53
54 **URL:** ``/restconf/config/openconfig-network-instance:network-instances/network-instance/global-bgp/openconfig-network-instance:protocols/protocol/openconfig-policy-types:BGP/bgp-example/bgp/neighbors``
55
56 **Method:** ``POST``
57
58 **Content-Type:** ``application/xml``
59
60 **Request Body:**
61
62 .. code-block:: xml
63
64    <neighbor xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
65        <neighbor-address>192.0.2.1</neighbor-address>
66        <afi-safis>
67            <afi-safi>
68                <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:L2VPN-EVPN</afi-safi-name>
69            </afi-safi>
70        </afi-safis>
71    </neighbor>
72
73 EVPN Route API
74 ^^^^^^^^^^^^^^
75 Following tree illustrate the BGP EVPN route structure.
76
77 .. code-block:: console
78
79    :(evpn-routes-case)
80       +--ro evpn-routes
81          +--ro evpn-route* [route-key path-id]
82             +--ro route-key                     string
83             +--ro path-id                       path-id
84             +--ro (evpn-choice)
85             |  +--:(ethernet-a-d-route-case)
86             |  |  +--ro ethernet-a-d-route
87             |  |     +--ro (esi)
88             |  |     |  +--:(arbitrary-case)
89             |  |     |  |  +--ro arbitrary
90             |  |     |  |     +--ro arbitrary    binary
91             |  |     |  +--:(lacp-auto-generated-case)
92             |  |     |  |  +--ro lacp-auto-generated
93             |  |     |  |     +--ro ce-lacp-mac-address    yang:mac-address
94             |  |     |  |     +--ro ce-lacp-port-key       uint16
95             |  |     |  +--:(lan-auto-generated-case)
96             |  |     |  |  +--ro lan-auto-generated
97             |  |     |  |     +--ro root-bridge-mac-address    yang:mac-address
98             |  |     |  |     +--ro root-bridge-priority       uint16
99             |  |     |  +--:(mac-auto-generated-case)
100             |  |     |  |  +--ro mac-auto-generated
101             |  |     |  |     +--ro system-mac-address     yang:mac-address
102             |  |     |  |     +--ro local-discriminator    uint24
103             |  |     |  +--:(router-id-generated-case)
104             |  |     |  |  +--ro router-id-generated
105             |  |     |  |     +--ro router-id              inet:ipv4-address
106             |  |     |  |     +--ro local-discriminator    uint32
107             |  |     |  +--:(as-generated-case)
108             |  |     |     +--ro as-generated
109             |  |     |        +--ro as                     inet:as-number
110             |  |     |        +--ro local-discriminator    uint32
111             |  |     +--ro ethernet-tag-id
112             |  |     |  +--ro vlan-id    uint32
113             |  |     +--ro mpls-label             netc:mpls-label
114             |  +--:(mac-ip-adv-route-case)
115             |  |  +--ro mac-ip-adv-route
116             |  |     +--ro (esi)
117             |  |     |  +--:(arbitrary-case)
118             |  |     |  |  +--ro arbitrary
119             |  |     |  |     +--ro arbitrary    binary
120             |  |     |  +--:(lacp-auto-generated-case)
121             |  |     |  |  +--ro lacp-auto-generated
122             |  |     |  |     +--ro ce-lacp-mac-address    yang:mac-address
123             |  |     |  |     +--ro ce-lacp-port-key       uint16
124             |  |     |  +--:(lan-auto-generated-case)
125             |  |     |  |  +--ro lan-auto-generated
126             |  |     |  |     +--ro root-bridge-mac-address    yang:mac-address
127             |  |     |  |     +--ro root-bridge-priority       uint16
128             |  |     |  +--:(mac-auto-generated-case)
129             |  |     |  |  +--ro mac-auto-generated
130             |  |     |  |     +--ro system-mac-address     yang:mac-address
131             |  |     |  |     +--ro local-discriminator    uint24
132             |  |     |  +--:(router-id-generated-case)
133             |  |     |  |  +--ro router-id-generated
134             |  |     |  |     +--ro router-id              inet:ipv4-address
135             |  |     |  |     +--ro local-discriminator    uint32
136             |  |     |  +--:(as-generated-case)
137             |  |     |     +--ro as-generated
138             |  |     |        +--ro as                     inet:as-number
139             |  |     |        +--ro local-discriminator    uint32
140             |  |     +--ro ethernet-tag-id
141             |  |     |  +--ro vlan-id    uint32
142             |  |     +--ro mac-address            yang:mac-address
143             |  |     +--ro ip-address?            inet:ip-address
144             |  |     +--ro mpls-label1            netc:mpls-label
145             |  |     +--ro mpls-label2?           netc:mpls-label
146             |  +--:(inc-multi-ethernet-tag-res-case)
147             |  |  +--ro inc-multi-ethernet-tag-res
148             |  |     +--ro ethernet-tag-id
149             |  |     |  +--ro vlan-id    uint32
150             |  |     +--ro orig-route-ip?     inet:ip-address
151             |  +--:(es-route-case)
152             |     +--ro es-route
153             |        +--ro (esi)
154             |        |  +--:(arbitrary-case)
155             |        |  |  +--ro arbitrary
156             |        |  |     +--ro arbitrary    binary
157             |        |  +--:(lacp-auto-generated-case)
158             |        |  |  +--ro lacp-auto-generated
159             |        |  |     +--ro ce-lacp-mac-address    yang:mac-address
160             |        |  |     +--ro ce-lacp-port-key       uint16
161             |        |  +--:(lan-auto-generated-case)
162             |        |  |  +--ro lan-auto-generated
163             |        |  |     +--ro root-bridge-mac-address    yang:mac-address
164             |        |  |     +--ro root-bridge-priority       uint16
165             |        |  +--:(mac-auto-generated-case)
166             |        |  |  +--ro mac-auto-generated
167             |        |  |     +--ro system-mac-address     yang:mac-address
168             |        |  |     +--ro local-discriminator    uint24
169             |        |  +--:(router-id-generated-case)
170             |        |  |  +--ro router-id-generated
171             |        |  |     +--ro router-id              inet:ipv4-address
172             |        |  |     +--ro local-discriminator    uint32
173             |        |  +--:(as-generated-case)
174             |        |     +--ro as-generated
175             |        |        +--ro as                     inet:as-number
176             |        |        +--ro local-discriminator    uint32
177             |        +--ro orig-route-ip          inet:ip-address
178             +--ro route-distinguisher           bgp-t:route-distinguisher
179             +--ro attributes
180                +--ro extended-communities*
181                |  +--ro transitive?                              boolean
182                |  +--ro (extended-community)?
183                |     +--:(encapsulation-case)
184                |     |  +--ro encapsulation-extended-community
185                |     |     +--ro tunnel-type    encapsulation-tunnel-type
186                |     +--:(esi-label-extended-community-case)
187                |     |  +--ro esi-label-extended-community
188                |     |     +--ro single-active-mode?   boolean
189                |     |     +--ro esi-label             netc:mpls-label
190                |     +--:(es-import-route-extended-community-case)
191                |     |  +--ro es-import-route-extended-community
192                |     |     +--ro es-import    yang:mac-address
193                |     +--:(mac-mobility-extended-community-case)
194                |     |  +--ro mac-mobility-extended-community
195                |     |     +--ro static?       boolean
196                |     |     +--ro seq-number    uint32
197                |     +--:(default-gateway-extended-community-case)
198                |     |  +--ro default-gateway-extended-community!
199                |     +--:(layer-2-attributes-extended-community-case)
200                |        +--ro layer-2-attributes-extended-community
201                |           +--ro primary-pe?     boolean
202                |           +--ro backup-pe?      boolean
203                |           +--ro control-word?   boolean
204                |           +--ro l2-mtu          uint16
205                +--ro pmsi-tunnel!
206                   +--ro leaf-information-required    boolean
207                   +--ro mpls-label?                  netc:mpls-label
208                   +--ro (tunnel-identifier)?
209                      +--:(rsvp-te-p2mp-lsp)
210                      |  +--ro rsvp-te-p2mp-lps
211                      |     +--ro p2mp-id               uint32
212                      |     +--ro tunnel-id             uint16
213                      |     +--ro extended-tunnel-id    inet:ip-address
214                      +--:(mldp-p2mp-lsp)
215                      |  +--ro mldp-p2mp-lsp
216                      |     +--ro address-family       identityref
217                      |     +--ro root-node-address    inet:ip-address
218                      |     +--ro opaque-value*
219                      |        +--ro opaque-type             uint8
220                      |        +--ro opaque-extended-type?   uint16
221                      |        +--ro opaque                  yang:hex-string
222                      +--:(pim-ssm-tree)
223                      |  +--ro pim-ssm-tree
224                      |     +--ro p-address            inet:ip-address
225                      |     +--ro p-multicast-group    inet:ip-address
226                      +--:(pim-sm-tree)
227                      |  +--ro pim-sm-tree
228                      |     +--ro p-address            inet:ip-address
229                      |     +--ro p-multicast-group    inet:ip-address
230                      +--:(bidir-pim-tree)
231                      |  +--ro bidir-pim-tree
232                      |     +--ro p-address            inet:ip-address
233                      |     +--ro p-multicast-group    inet:ip-address
234                      +--:(ingress-replication)
235                      |  +--ro ingress-replication
236                      |     +--ro receiving-endpoint-address?   inet:ip-address
237                      +--:(mldp-mp2mp-lsp)
238                         +--ro mldp-mp2mp-lsp
239                            +--ro opaque-type             uint8
240                            +--ro opaque-extended-type?   uint16
241                            +--ro opaque
242                      ...
243
244 Usage
245 ^^^^^
246 The L2VPN EVPN table in an instance of the speaker's Loc-RIB can be verified via REST:
247
248 **URL:** ``/restconf/operational/bgp-rib:bgp-rib/rib/bgp-example/loc-rib/tables/odl-bgp-evpn:l2vpn-address-family/odl-bgp-evpn:evpn-subsequent-address-family/evpn-routes``
249
250 **Method:** ``GET``
251
252 **Response Body:**
253
254 .. code-block:: xml
255
256    <evpn-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-evpn">
257       <evpn-route>
258          <route-key>AxEAAcCoZAED6AAAAQAgwKhkAQ==</route-key>
259          <path-id>0</path-id>
260          <route-distinguisher>192.168.100.1:1000</route-distinguisher>
261          <inc-multi-ethernet-tag-res>
262             <ethernet-tag-id>
263                <vlan-id>256</vlan-id>
264             </ethernet-tag-id>
265             <orig-route-ip>192.168.100.1</orig-route-ip>
266          </inc-multi-ethernet-tag-res>
267          <attributes>
268             <ipv4-next-hop>
269                <global>172.23.29.104</global>
270             </ipv4-next-hop>
271             <as-path/>
272             <origin>
273                <value>igp</value>
274             </origin>
275             <extended-communities>
276                <extended-communities>
277                    <transitive>true</transitive>
278                    <route-target-extended-community>
279                        <global-administrator>65504</global-administrator>
280                        <local-administrator>AAAD6A==</local-administrator>
281                    </route-target-extended-community>
282                </extended-communities>
283             </extended-communities>
284             <pmsi-tunnel>
285                 <leaf-information-required>true</leaf-information-required>
286                 <mpls-label>20024</mpls-label>
287                 <ingress-replication>
288                     <receiving-endpoint-address>192.168.100.1</receiving-endpoint-address>
289                 </ingress-replication>
290             </pmsi-tunnel>
291          </attributes>
292       </evpn-route>
293    </evpn-routes>
294
295 Programming
296 ^^^^^^^^^^^
297 This examples show how to originate and remove EVPN routes via programmable RIB.
298 There are four different types of EVPN routes, and several extended communities.
299 Routes can be used for variety of use-cases supported by BGP/MPLS EVPN, PBB EVPN and NVO EVPN.
300 Make sure the *Application Peer* is configured first.
301
302 **URL:** ``/restconf/config/bgp-rib:application-rib/10.25.1.9/tables/odl-bgp-evpn:l2vpn-address-family/odl-bgp-evpn:evpn-subsequent-address-family/odl-bgp-evpn:evpn-routes``
303
304 **Method:** ``POST``
305
306 **Content-Type:** ``application/xml``
307
308 **Request Body:**
309
310 .. code-block:: xml
311    :linenos:
312    :emphasize-lines: 4,5,15
313
314    <evpn-route xmlns="urn:opendaylight:params:xml:ns:yang:bgp-evpn">
315        <route-key>evpn</route-key>
316        <path-id>0</path-id>
317        <route-distinguisher>172.12.123.3:200</route-distinguisher>
318        ....
319        <attributes>
320            <ipv4-next-hop>
321                <global>199.20.166.41</global>
322            </ipv4-next-hop>
323            <as-path/>
324            <origin>
325                <value>igp</value>
326            </origin>
327            <extended-communities>
328            ....
329            </extended-communities>
330        </attributes>
331    </evpn-route>
332
333 @line 4: Route Distinguisher (RD) - set to RD of the MAC-VRF advertising the NLRI, recommended format *<IP>:<VLAN_ID>*
334
335 @line 5: One of the EVPN route must be set here.
336
337 @line 15: In some cases, specific extended community presence is required. The route may carry one or more Route Target attributes.
338
339 -----
340
341 EVPN Routes
342 ^^^^^^^^^^^
343
344 * **Ethernet AD per ESI**
345    .. code-block:: xml
346
347       <ethernet-a-d-route>
348           <mpls-label>0</mpls-label>
349           <ethernet-tag-id>
350               <vlan-id>4294967295</vlan-id>
351           </ethernet-tag-id>
352           <arbitrary>
353               <arbitrary>AAAAAAAAAAAA</arbitrary>
354           </arbitrary>
355       </ethernet-a-d-route>
356
357 * **Ethernet AD per EVI**
358    .. code-block:: xml
359
360       <ethernet-a-d-route>
361           <mpls-label>24001</mpls-label>
362           <ethernet-tag-id>
363               <vlan-id>2200</vlan-id>
364           </ethernet-tag-id>
365           <arbitrary>
366               <arbitrary>AAAAAAAAAAAA</arbitrary>
367           </arbitrary>
368       </ethernet-a-d-route>
369
370 * **MAC/IP Advertisement**
371    .. code-block:: xml
372
373       <mac-ip-adv-route>
374           <arbitrary>
375               <arbitrary>AAAAAAAAAAAA</arbitrary>
376           </arbitrary>
377           <ethernet-tag-id>
378               <vlan-id>2100</vlan-id>
379           </ethernet-tag-id>
380           <mac-address>f2:0c:dd:80:9f:f7</mac-address>
381           <ip-address>10.0.1.12</ip-address>
382           <mpls-label1>299776</mpls-label1>
383       </mac-ip-adv-route>
384
385
386 * **Inclusive Multicast Ethernet Tag**
387    .. code-block:: xml
388
389       <inc-multi-ethernet-tag-res>
390           <ethernet-tag-id>
391               <vlan-id>2100</vlan-id>
392           </ethernet-tag-id>
393           <orig-route-ip>43.43.43.43</orig-route-ip>
394       </inc-multi-ethernet-tag-res>
395
396 * **Ethernet Segment**
397    .. code-block:: xml
398
399       <es-route>
400           <orig-route-ip>43.43.43.43</orig-route-ip>
401           <arbitrary>
402               <arbitrary>AAAAAAAAAAAA</arbitrary>
403           </arbitrary>
404       </es-route>
405
406 **EVPN Ethernet Segment Identifier (ESI):**
407
408 * **Type 0**
409    Indicates an arbitrary 9-octet ESI.
410
411    .. code-block:: xml
412
413       <arbitrary>
414           <arbitrary>AAAAAAAAAAAA</arbitrary>
415       </arbitrary>
416
417 * **Type 1**
418    IEEE 802.1AX LACP is used.
419
420    .. code-block:: xml
421
422       <lacp-auto-generated>
423           <ce-lacp-mac-address>f2:0c:dd:80:9f:f7</ce-lacp-mac-address>
424           <ce-lacp-port-key>22</ce-lacp-port-key>
425       </lacp-auto-generated>
426
427 * **Type 2**
428    Indirectly connected hosts via a bridged LAN.
429
430    .. code-block:: xml
431
432       <lan-auto-generated>
433           <root-bridge-mac-address>f2:0c:dd:80:9f:f7</root-bridge-mac-address>
434           <root-bridge-priority>20</root-bridge-priority>
435       </lan-auto-generated>
436
437 * **Type 3**
438    MAC-based ESI.
439
440    .. code-block:: xml
441
442       <mac-auto-generated>
443           <system-mac-address>f2:0c:dd:80:9f:f7</system-mac-address>
444           <local-discriminator>2000</local-discriminator>
445       </mac-auto-generated>
446
447 * **Type 4**
448    Router-ID ESI
449
450    .. code-block:: xml
451
452       <router-id-generated>
453           <router-id>43.43.43.43</router-id>
454           <local-discriminator>2000</local-discriminator>
455       </router-id-generated>
456
457 * **Type 5**
458    AS-based ESI
459
460    .. code-block:: xml
461
462       <as-generated>
463           <as>16843009</as>
464           <local-discriminator>2000</local-discriminator>
465       </as-generated>
466
467 **Attributes:**
468
469 .. include:: bgp-user-guide-pmsi-attribute.rst
470
471 **Extended Communities:**
472
473 * **ESI Label Extended Community**
474    .. code-block:: xml
475
476       <extended-communities>
477           <transitive>true</transitive>
478           <esi-label-extended-community>
479               <single-active-mode>false</single-active-mode>
480               <esi-label>24001</esi-label>
481           </esi-label-extended-community>
482       </extended-communities>
483
484 * **ES-Import Route Target**
485    .. code-block:: xml
486
487       <extended-communities>
488           <transitive>true</transitive>
489           <es-import-route-extended-community>
490               <es-import>f2:0c:dd:80:9f:f7</es-import>
491           </es-import-route-extended-community>
492       </extended-communities>
493
494 * **MAC Mobility Extended Community**
495    .. code-block:: xml
496
497       <extended-communities>
498           <transitive>true</transitive>
499           <mac-mobility-extended-community>
500               <static>true</static>
501               <seq-number>200</seq-number>
502           </mac-mobility-extended-community>
503       </extended-communities>
504
505 * **Default Gateway Extended Community**
506    .. code-block:: xml
507
508       <extended-communities>
509           <transitive>true</transitive>
510           <default-gateway-extended-community>
511           </default-gateway-extended-community>
512       </extended-communities>
513
514 * **EVPN Layer 2 attributes extended community**
515    .. code-block:: xml
516
517       <extended-communities>
518           <transitive>false</transitive>
519           <layer-2-attributes-extended-community>
520               <primary-pe>true</primary-pe>
521               <backup-pe>true</backup-pe>
522               <control-word >true</control-word>
523               <l2-mtu>200</l2-mtu>
524           </layer-2-attributes-extended-community>
525       </extended-communities>
526
527 * **BGP Encapsulation extended community**
528    .. code-block:: xml
529       :linenos:
530       :emphasize-lines: 4
531
532       <extended-communities>
533           <transitive>false</transitive>
534           <encapsulation-extended-community>
535               <tunnel-type>vxlan</tunnel-type>
536           </encapsulation-extended-community>
537       </extended-communities>
538
539    @line 4: `full list of tunnel types <http://www.iana.org/assignments/bgp-parameters/bgp-parameters.xhtml#tunnel-types>`_
540
541 -----
542
543 To remove the route added above, following request can be used:
544
545 **URL:** ``/restconf/config/bgp-rib:application-rib/10.25.1.9/tables/bgp-types:ipv4-address-family/odl-bgp-evpn:l2vpn-address-family/odl-bgp-evpn:evpn-subsequent-address-family/odl-bgp-evpn:evpn-routes/evpn-route/evpn/0``
546
547 **Method:** ``DELETE``
548
549 -----
550
551 .. table:: EVPN Routes Usage.
552
553    +--------------------------------------+-----------------------------------------------------+-------------------------------------------+
554    | EVN Route Type                       | Extended Communities                                | Usage                                     |
555    +======================================+=====================================================+===========================================+
556    | **Ethernet Auto-discovery**          | ESI Label, BGP EncapsulationEVPN Layer 2 attributes | Fast Convergence, Split Horizon, Aliasing |
557    +--------------------------------------+-----------------------------------------------------+-------------------------------------------+
558    | **MAC/IP Advertisement**             | BGP Encapsulation, MAC Mobility, Default Gateway    | MAC address reachability                  |
559    +--------------------------------------+-----------------------------------------------------+-------------------------------------------+
560    | **Inclusive Multicast Ethernet Tag** | PMSI Tunnel, BGP Encapsulation                      | Handling of Multi-destination traffic     |
561    +--------------------------------------+-----------------------------------------------------+-------------------------------------------+
562    | **Ethernet Segment**                 | BGP Encapsulation, ES-Import Route Target           | Designated Forwarder Election             |
563    +--------------------------------------+-----------------------------------------------------+-------------------------------------------+
564
565 References
566 ^^^^^^^^^^
567 * `BGP MPLS-Based Ethernet VPN <https://tools.ietf.org/html/rfc7432>`_
568 * `Provider Backbone Bridging Combined with Ethernet VPN <https://tools.ietf.org/html/rfc7623>`_
569 * `VPWS support in EVPN <https://tools.ietf.org/html/draft-ietf-bess-evpn-vpws-07>`_
570 * `A Network Virtualization Overlay Solution using EVPN <https://tools.ietf.org/html/draft-ietf-bess-evpn-overlay-04>`_
571 * `Interconnect Solution for EVPN Overlay networks <https://tools.ietf.org/html/draft-ietf-bess-dci-evpn-overlay-04>`_
572 * `Usage and applicability of BGP MPLS based Ethernet VPN <https://tools.ietf.org/html/draft-ietf-bess-evpn-usage-03>`_