docs/bgp/bgp-user-guide-bgp-peering.rst

   1 .. _bgp-user-guide-bgp-peering:
   2
   3 BGP Peering
   4 ===========
   5 To exchange routing information between two BGP systems (peers), it is required to configure a peering on both BGP speakers first.
   6 This mean that each BGP speaker has a white list of neighbors, representing remote peers, with which the peering is allowed.
   7 The TCP connection is established between two peers and they exchange messages to open and confirm the connection parameters followed by routes exchange.
   8
   9 Here is a sample basic neighbor configuration:
  10
  11 **URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/openconfig-network-instance:protocols/protocol=openconfig-policy-types:BGP/bgp-example/bgp/neighbors``
  12
  13 **Method:** ``POST``
  14
  15 .. tabs::
  16
  17    .. tab:: XML
  18
  19       **Content-Type:** ``application/xml``
  20
  21       **Request Body:**
  22
  23       .. code-block:: xml
  24          :linenos:
  25          :emphasize-lines: 2,5,6,11,12,17,19
  26
  27          <neighbor xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
  28              <neighbor-address>192.0.2.1</neighbor-address>
  29              <timers>
  30                  <config>
  31                      <hold-time>90</hold-time>
  32                      <connect-retry>10</connect-retry>
  33                  </config>
  34              </timers>
  35              <transport>
  36                  <config>
  37                      <remote-port>179</remote-port>
  38                      <passive-mode>false</passive-mode>
  39                      <!--<local-address>192.0.2.5</local-address>-->
  40                  </config>
  41              </transport>
  42              <config>
  43                  <peer-type>INTERNAL</peer-type>
  44              </config>
  45              <afi-safis>
  46                  ...
  47              </afi-safis>
  48          </neighbor>
  49
  50       @line 2: IP address of the remote BGP peer. Also serves as an unique identifier of a neighbor in a list of neighbors.
  51
  52       @line 5: Proposed number of seconds for value of the Hold Timer. Default value is **90**.
  53
  54       @line 6: Time interval in seconds between attempts to establish session with the peer. Effective in active mode only. Default value is **30**.
  55
  56       @line 11: Remote port number to which the local BGP is connecting. Effective in active mode only. Default value **179**.
  57
  58       @line 12: Wait for peers to issue requests to open a BGP session, rather than initiating sessions from the local router. Default value is **false**.
  59
  60       @line 13: Optional Local IP (either IPv4 or IPv6) address used to establish connections to the remote peer. Effective in active mode only.
  61
  62       @line 17: Explicitly designate the peer as internal or external. Default value is **INTERNAL**.
  63
  64       @line 19: Enable families.
  65
  66    .. tab:: JSON
  67
  68       **Content-Type:** ``application/json``
  69
  70       **Request Body:**
  71
  72       .. code-block:: json
  73          :linenos:
  74          :emphasize-lines: 4,7,8,13,14,18,20
  75
  76          {
  77              "neighbor": [
  78                  {
  79                      "neighbor-address": "192.0.2.1",
  80                      "timers": {
  81                          "config": {
  82                              "hold-time": 90,
  83                              "connect-retry": 10
  84                          }
  85                      },
  86                      "transport": {
  87                          "config": {
  88                              "remote-port": 179,
  89                              "passive-mode": "false"
  90                          }
  91                      },
  92                      "config": {
  93                          "peer-type": "INTERNAL"
  94                      }
  95                      "afi-safis": "..."
  96                  }
  97              ]
  98          }
  99
 100       @line 4: IP address of the remote BGP peer. Also serves as an unique identifier of a neighbor in a list of neighbors.
 101
 102       @line 7: Proposed number of seconds for value of the Hold Timer. Default value is **90**.
 103
 104       @line 8: Time interval in seconds between attempts to establish session with the peer. Effective in active mode only. Default value is **30**.
 105
 106       @line 13: Remote port number to which the local BGP is connecting. Effective in active mode only. Default value **179**.
 107
 108       @line 14: Wait for peers to issue requests to open a BGP session, rather than initiating sessions from the local router. Default value is **false**.
 109
 110       @line 18: Explicitly designate the peer as internal or external. Default value is **INTERNAL**.
 111
 112       @line 20: Enable families.
 113
 114 -----
 115
 116 Once the remote peer is connected and it advertised routes to local BGP system, routes are stored in peer's RIBs.
 117 The RIBs can be checked via REST:
 118
 119 **URL:** ``/rests/data/bgp-rib:bgp-rib/rib=bgp-example/peer=bgp%3A%2F%2F192.0.2.1?content=nonconfig``
 120
 121 **Method:** ``GET``
 122
 123 .. tabs::
 124
 125    .. tab:: XML
 126
 127       **Response Body:**
 128
 129       .. code-block:: xml
 130          :linenos:
 131          :emphasize-lines: 8,13,35,40,62,66
 132
 133          <peer xmlns="urn:opendaylight:params:xml:ns:yang:bgp-rib">
 134              <peer-id>bgp://192.0.2.1</peer-id>
 135              <supported-tables>
 136                  <afi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:ipv4-address-family</afi>
 137                  <safi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:unicast-subsequent-address-family</safi>
 138              </supported-tables>
 139              <peer-role>ibgp</peer-role>
 140              <adj-rib-in>
 141                  <tables>
 142                      <afi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:ipv4-address-family</afi>
 143                      <safi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:unicast-subsequent-address-family</safi>
 144                      <ipv4-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
 145                          <ipv4-route>
 146                              <path-id>0</path-id>
 147                              <prefix>10.0.0.10/32</prefix>
 148                              <attributes>
 149                                  <as-path></as-path>
 150                                  <origin>
 151                                      <value>igp</value>
 152                                  </origin>
 153                                  <local-pref>
 154                                      <pref>100</pref>
 155                                  </local-pref>
 156                                  <ipv4-next-hop>
 157                                      <global>10.10.1.1</global>
 158                                  </ipv4-next-hop>
 159                              </attributes>
 160                          </ipv4-route>
 161                      </ipv4-routes>
 162                      <attributes>
 163                          <uptodate>true</uptodate>
 164                      </attributes>
 165                  </tables>
 166              </adj-rib-in>
 167              <effective-rib-in>
 168                  <tables>
 169                      <afi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:ipv4-address-family</afi>
 170                      <safi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:unicast-subsequent-address-family</safi>
 171                      <ipv4-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
 172                          <ipv4-route>
 173                              <path-id>0</path-id>
 174                              <prefix>10.0.0.10/32</prefix>
 175                              <attributes>
 176                                  <as-path></as-path>
 177                                  <origin>
 178                                      <value>igp</value>
 179                                  </origin>
 180                                  <local-pref>
 181                                      <pref>100</pref>
 182                                  </local-pref>
 183                                  <ipv4-next-hop>
 184                                      <global>10.10.1.1</global>
 185                                  </ipv4-next-hop>
 186                              </attributes>
 187                          </ipv4-route>
 188                      </ipv4-routes>
 189                      <attributes>
 190                          <uptodate>true</uptodate>
 191                      </attributes>
 192                  </tables>
 193              </effective-rib-in>
 194              <adj-rib-out>
 195                  <tables>
 196                      <afi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:ipv4-address-family</afi>
 197                      <safi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:unicast-subsequent-address-family</safi>
 198                      <ipv4-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet"></ipv4-routes>
 199                      <attributes></attributes>
 200                  </tables>
 201              </adj-rib-out>
 202          </peer>
 203
 204       @line 8: **Adj-RIB-In** - Per-peer RIB, which contains unprocessed routes that has been advertised to local BGP speaker by the remote peer.
 205
 206       @line 13: Here is the reported route with destination *10.0.0.10/32* in Adj-RIB-In.
 207
 208       @line 35: **Effective-RIB-In** - Per-peer RIB, which contains processed routes as a result of applying inbound policy to Adj-RIB-In routes.
 209
 210       @line 40: Here is the reported route with destination *10.0.0.10/32*, same as in Adj-RIB-In, as it was not touched by import policy.
 211
 212       @line 62: **Adj-RIB-Out** - Per-peer RIB, which contains routes for advertisement to the peer by means of the local speaker's UPDATE message.
 213
 214       @line 66: The peer's Adj-RIB-Out is empty as there are no routes to be advertise from local BGP speaker.
 215
 216    .. tab:: JSON
 217
 218       **Response Body:**
 219
 220       .. code-block:: json
 221          :linenos:
 222          :emphasize-lines: 12,18,42,48,72,76
 223
 224          {
 225              "peer": [
 226                  {
 227                      "peer-id": "bgp://192.0.2.1",
 228                      "peer-role": "ibgp",
 229                      "supported-tables": [
 230                          {
 231                              "afi": "bgp-types:ipv4-address-family",
 232                              "safi": "bgp-types:unicast-subsequent-address-family"
 233                          }
 234                      ],
 235                      "adj-rib-in": {
 236                          "tables": [
 237                              {
 238                                  "afi": "bgp-types:ipv4-address-family",
 239                                  "safi": "bgp-types:unicast-subsequent-address-family",
 240                                  "bgp-inet:ipv4-routes":{
 241                                      "ipv4-route": [
 242                                          {
 243                                              "path-id": 0,
 244                                              "prefix": "10.0.0.10/32",
 245                                              "attributes": {
 246                                                  "origin": {
 247                                                      "value": "igp"
 248                                                  },
 249                                                  "local-pref": {
 250                                                      "pref": 100
 251                                                  },
 252                                                  "ipv4-next-hop": {
 253                                                      "global": "10.10.1.1"
 254                                                  }
 255                                              }
 256                                          }
 257                                      ]
 258                                  },
 259                                  "attributes": {
 260                                      "uptodate": true
 261                                  }
 262                              }
 263                          ]
 264                      },
 265                      "effective-rib-in": {
 266                          "tables": [
 267                              {
 268                                  "afi": "bgp-types:ipv4-address-family",
 269                                  "safi": "bgp-types:unicast-subsequent-address-family",
 270                                  "bgp-inet:ipv4-routes":{
 271                                      "ipv4-route": [
 272                                          {
 273                                              "path-id": 0,
 274                                              "prefix": "10.0.0.11/32",
 275                                              "attributes": {
 276                                                  "origin": {
 277                                                      "value": "igp"
 278                                                  },
 279                                                  "local-pref": {
 280                                                      "pref": 100
 281                                                  },
 282                                                  "ipv4-next-hop": {
 283                                                      "global": "10.11.1.1"
 284                                                  }
 285                                              }
 286                                          }
 287                                      ]
 288                                  },
 289                                  "attributes": {
 290                                      "uptodate": true
 291                                  }
 292                              }
 293                          ]
 294                      },
 295                      "adj-rib-out": {
 296                          "tables": [
 297                              {
 298                                  "afi": "bgp-types:ipv4-address-family",
 299                                  "safi": "bgp-types:unicast-subsequent-address-family"
 300                              }
 301                          ]
 302                      }
 303                  }
 304              ]
 305          }
 306
 307       @line 12: **Adj-RIB-In** - Per-peer RIB, which contains unprocessed routes that has been advertised to local BGP speaker by the remote peer.
 308
 309       @line 18: Here is the reported route with destination *10.0.0.10/32* in Adj-RIB-In.
 310
 311       @line 42: **Effective-RIB-In** - Per-peer RIB, which contains processed routes as a result of applying inbound policy to Adj-RIB-In routes.
 312
 313       @line 48: Here is the reported route with destination *10.0.0.10/32*, same as in Adj-RIB-In, as it was not touched by import policy.
 314
 315       @line 72: **Adj-RIB-Out** - Per-peer RIB, which contains routes for advertisement to the peer by means of the local speaker's UPDATE message.
 316
 317       @line 76: The peer's Adj-RIB-Out is empty as there are no routes to be advertise from local BGP speaker.
 318
 319 -----
 320
 321 Also the same route should appeared in Loc-RIB now:
 322
 323 **URL:** ``/rests/data/bgp-rib:bgp-rib/rib/bgp-example/loc-rib/tables=bgp-types:ipv4-address-family,bgp-types:unicast-subsequent-address-family/ipv4-routes?content=nonconfig``
 324
 325 **Method:** ``GET``
 326
 327 .. tabs::
 328
 329    .. tab:: XML
 330
 331       **Response Body:**
 332
 333       .. code-block:: xml
 334          :linenos:
 335          :emphasize-lines: 4,6,8,11,14
 336
 337          <ipv4-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
 338              <ipv4-route>
 339                  <path-id>0</path-id>
 340                  <prefix>10.0.0.10/32</prefix>
 341                  <attributes>
 342                      <as-path></as-path>
 343                      <origin>
 344                          <value>igp</value>
 345                      </origin>
 346                      <local-pref>
 347                          <pref>100</pref>
 348                      </local-pref>
 349                      <ipv4-next-hop>
 350                          <global>10.10.1.1</global>
 351                      </ipv4-next-hop>
 352                  </attributes>
 353              </ipv4-route>
 354          </ipv4-routes>
 355
 356       @line 4: **Destination** - IPv4 Prefix Address.
 357
 358       @line 6: **AS_PATH** - mandatory attribute, contains a list of the autonomous system numbers through that routing information has traversed.
 359
 360       @line 8: **ORIGIN** - mandatory attribute, indicates an origin of the route - **ibgp**, **egp**, **incomplete**.
 361
 362       @line 11: **LOCAL_PREF** - indicates a degree of preference for external routes, higher value is preferred.
 363
 364       @line 14: **NEXT_HOP** - mandatory attribute, defines IP address of the router that should be used as the next hop to the destination.
 365
 366    .. tab:: JSON `
 367
 368       **Response Body:**
 369
 370       .. code-block:: json
 371          :linenos:
 372          :emphasize-lines: 6,8,10,13,16
 373
 374          {
 375              "bgp-inet:ipv4-routes":{
 376                  "ipv4-route": [
 377                      {
 378                          "path-id": 0,
 379                          "prefix": "10.0.0.10/32",
 380                          "attributes": {
 381                              "as-path": "",
 382                              "origin": {
 383                                  "value": "igp"
 384                              },
 385                              "local-pref": {
 386                                  "pref": "100"
 387                              },
 388                              "ipv4-next-hop": {
 389                                  "global": "10.10.1.1"
 390                              }
 391                          }
 392                      }
 393                  ]
 394              }
 395          }
 396
 397       @line 6: **Destination** - IPv4 Prefix Address.
 398
 399       @line 8: **AS_PATH** - mandatory attribute, contains a list of the autonomous system numbers through that routing information has traversed.
 400
 401       @line 10: **ORIGIN** - mandatory attribute, indicates an origin of the route - **ibgp**, **egp**, **incomplete**.
 402
 403       @line 13: **LOCAL_PREF** - indicates a degree of preference for external routes, higher value is preferred.
 404
 405       @line 16: **NEXT_HOP** - mandatory attribute, defines IP address of the router that should be used as the next hop to the destination.
 406
 407 -----
 408
 409 There are much more attributes that may be carried along with the destination:
 410
 411 **BGP-4 Path Attributes**
 412
 413 * **MULTI_EXIT_DISC** (MED)
 414    Optional attribute, to be used to discriminate among multiple exit/entry points on external links, lower number is preferred.
 415
 416 .. tabs::
 417
 418    .. tab:: XML
 419
 420       .. code-block:: xml
 421
 422          <multi-exit-disc>
 423              <med>0</med>
 424          </multi-exit-disc>
 425
 426    .. tab:: JSON
 427
 428       .. code-block:: json
 429
 430          {
 431              "multi-exit-disc": {
 432                  "med": 0
 433              }
 434          }
 435
 436 * **ATOMIC_AGGREGATE**
 437    Indicates whether AS_SET was excluded from AS_PATH due to routes aggregation.
 438
 439 .. tabs::
 440
 441    .. tab:: XML
 442
 443       .. code-block:: xml
 444
 445          <atomic-aggregate/>
 446
 447    .. tab:: JSON
 448
 449       .. code-block:: json
 450
 451          {
 452          "atomic-aggregate": {
 453          }
 454          }
 455
 456 * **AGGREGATOR**
 457    Optional attribute, contains AS number and IP address of a BGP speaker which performed routes aggregation.
 458
 459 .. tabs::
 460
 461    .. tab:: XML
 462
 463       .. code-block:: xml
 464
 465          <aggregator>
 466              <as-number>65000</as-number>
 467              <network-address>192.0.2.2</network-address>
 468          </aggregator>
 469
 470    .. tab:: JSON
 471
 472       .. code-block:: json
 473
 474          {
 475              "aggregator": {
 476                  "as-number": 65000,
 477                  "network-address": "192.0.2.2"
 478              }
 479          }
 480
 481 * **Unrecognised**
 482    Optional attribute, used to store optional attributes, unrecognized by a local BGP speaker.
 483
 484 .. tabs::
 485
 486    .. tab:: XML
 487
 488       .. code-block:: xml
 489
 490          <unrecognized-attributes>
 491              <partial>true</partial>
 492              <transitive>true</transitive>
 493              <type>101</type>
 494              <value>0101010101010101</value>
 495          </unrecognized-attributes>
 496
 497    .. tab:: JSON
 498
 499       .. code-block:: json
 500
 501          {
 502              "unrecognized-attributes": {
 503                  "partial": true,
 504                  "transitive": true,
 505                  "type": 101,
 506                  "value": 0101010101010101
 507              }
 508          }
 509
 510 **Route Reflector Attributes**
 511
 512 * **ORIGINATOR_ID**
 513    Optional attribute, carries BGP Identifier of the originator of the route.
 514
 515 .. tabs::
 516
 517    .. tab:: XML
 518
 519       .. code-block:: xml
 520
 521          <originator-id>
 522              <originator>41.41.41.41</originator>
 523          </originator-id>
 524
 525    .. tab:: JSON
 526
 527       .. code-block:: json
 528
 529          {
 530              "originator-id": {
 531                  "originator": "41.41.41.41",
 532              }
 533          }
 534
 535 * **CLUSTER_LIST**
 536    Optional attribute, contains a list of CLUSTER_ID values representing the path that the route has traversed.
 537
 538 .. tabs::
 539
 540    .. tab:: XML
 541
 542       .. code-block:: xml
 543
 544          <cluster-id>
 545              <cluster>40.40.40.40</cluster>
 546          </cluster-id>
 547
 548    .. tab:: JSON
 549
 550       .. code-block:: json
 551
 552          {
 553              "cluster-id": {
 554                  "cluster": "41.41.41.41",
 555              }
 556          }
 557
 558 * **Communities**
 559    Optional attribute, may be used for policy routing.
 560
 561 .. tabs::
 562
 563    .. tab:: XML
 564
 565       .. code-block:: xml
 566
 567          <communities>
 568              <as-number>65000</as-number>
 569              <semantics>30740</semantics>
 570          </communities>
 571
 572    .. tab:: JSON
 573
 574       .. code-block:: json
 575
 576          {
 577              "communities": {
 578                  "as-number": 65000,
 579                  "semantics": 30740
 580              }
 581          }
 582
 583 **Extended Communities**
 584
 585 * **Route Target**
 586    Identifies one or more routers that may receive a route.
 587
 588 .. tabs::
 589
 590    .. tab:: XML
 591
 592       .. code-block:: xml
 593
 594          <extended-communities>
 595              <transitive>true</transitive>
 596              <route-target-ipv4>
 597                  <global-administrator>192.0.2.2</global-administrator>
 598                  <local-administrator>123</local-administrator>
 599              </route-target-ipv4>
 600          </extended-communities>
 601          <extended-communities>
 602              <transitive>true</transitive>
 603              <as-4-route-target-extended-community>
 604                  <as-4-specific-common>
 605                      <as-number>65000</as-number>
 606                      <local-administrator>123</local-administrator>
 607                  </as-4-specific-common>
 608              </as-4-route-target-extended-community>
 609          </extended-communities>
 610
 611    .. tab:: JSON
 612
 613       .. code-block:: json
 614
 615          {
 616              "extended-communities": [
 617                  {
 618                      "transitive": true,
 619                      "route-target-ipv4": {
 620                          "global-administrator": "192.0.2.2",
 621                          "local-administrator": 123
 622                      }
 623                  },
 624                  {
 625                      "transitive": true,
 626                      "as-4-route-target-extended-community": {
 627                          "as-4-specific-common": {
 628                              "as-number": 65000,
 629                              "local-administrator": 123
 630                          }
 631                      }
 632                  }
 633              ]
 634          }
 635
 636 * **Route Origin**
 637    Identifies one or more routers that injected a route.
 638
 639 .. tabs::
 640
 641    .. tab:: XML
 642
 643       .. code-block:: xml
 644
 645          <extended-communities>
 646              <transitive>true</transitive>
 647              <route-origin-ipv4>
 648                  <global-administrator>192.0.2.2</global-administrator>
 649                  <local-administrator>123</local-administrator>
 650              </route-origin-ipv4>
 651          </extended-communities>
 652          <extended-communities>
 653              <transitive>true</transitive>
 654              <as-4-route-origin-extended-community>
 655                  <as-4-specific-common>
 656                      <as-number>65000</as-number>
 657                      <local-administrator>123</local-administrator>
 658                  </as-4-origin-common>
 659              </as-4-route-target-extended-community>
 660          </extended-communities>
 661
 662    .. tab:: JSON
 663
 664       .. code-block:: json
 665
 666          {
 667              "extended-communities": [
 668                  {
 669                      "transitive": true,
 670                      "route-origin-ipv4": {
 671                          "global-administrator": "192.0.2.2",
 672                          "local-administrator": 123
 673                      }
 674                  },
 675                  {
 676                      "transitive": true,
 677                      "as-4-route-target-extended-community": {
 678                          "as-4-specific-common": {
 679                              "as-number": 65000,
 680                              "local-administrator": 123
 681                          }
 682                      }
 683                  }
 684              ]
 685          }
 686
 687 * **Link Bandwidth**
 688    Carries the cost to reach external neighbor.
 689
 690 .. tabs::
 691
 692    .. tab:: XML
 693
 694       .. code-block:: xml
 695
 696          <extended-communities>
 697              <transitive>true</transitive>
 698              <link-bandwidth-extended-community>
 699                  <bandwidth>BH9CQAA=</bandwidth>
 700              </link-bandwidth-extended-community>
 701          </extended-communities>
 702
 703    .. tab:: JSON
 704
 705       .. code-block:: json
 706
 707          {
 708              "extended-communities": {
 709                  "transitive": true,
 710                  "link-bandwidth-extended-community": {
 711                      "bandwidth": "BH9CQAA="
 712                  }
 713              }
 714          }
 715
 716 * **AIGP**
 717    Optional attribute, carries accumulated IGP metric.
 718
 719 .. tabs::
 720
 721    .. tab:: XML
 722
 723       .. code-block:: xml
 724
 725          <aigp>
 726              <aigp-tlv>
 727                  <metric>120</metric>
 728              </aigp-tlv>
 729          </aigp>
 730
 731    .. tab:: JSON
 732
 733       .. code-block:: json
 734
 735          {
 736              "aigp": {
 737                  "aigp-tlv": {
 738                      "metric": 120
 739                  }
 740              }
 741          }
 742
 743 .. note:: When the remote peer disconnects, it disappear from operational state of local speaker instance and advertised routes are removed too.
 744
 745 External peering configuration
 746 ''''''''''''''''''''''''''''''
 747 An example above provided configuration for internal peering only.
 748 Following configuration sample is intended for external peering:
 749
 750 **URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/openconfig-network-instance:protocols/protocol=openconfig-policy-types:BGP/bgp-example/bgp/neighbors``
 751
 752 **Method:** ``POST``
 753
 754 .. tabs::
 755
 756    .. tab:: XML
 757
 758       **Content-Type:** ``application/xml``
 759
 760       **Request Body:**
 761
 762       .. code-block:: xml
 763          :linenos:
 764          :emphasize-lines: 5
 765
 766          <neighbor xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
 767              <neighbor-address>192.0.2.3</neighbor-address>
 768              <config>
 769                  <peer-type>EXTERNAL</peer-type>
 770                  <peer-as>64999</peer-as>
 771              </config>
 772          </neighbor>
 773
 774       @line 5: AS number of the remote peer.
 775
 776    .. tab:: JSON
 777
 778       **Content-Type:** ``application/json``
 779
 780       **Request Body:**
 781
 782       .. code-block:: json
 783          :linenos:
 784          :emphasize-lines: 6
 785
 786          {
 787              "neighbor": [
 788                  {
 789                      "neighbor-address": "192.0.2.3",
 790                      "config": {
 791                          "peer-as": 64999,
 792                          "peer-type": "EXTERNAL"
 793                      }
 794                  }
 795              ]
 796          }
 797
 798       @line 6: AS number of the remote peer.
 799
 800 Local AS
 801 ''''''''
 802
 803 .. figure:: ./images/local-as.png
 804    :alt: BGP eBGP with Local AS setup.
 805
 806 The local-AS feature allows a router(eBGP) to appear to be a member of a second autonomous system (AS), in addition to its real AS.
 807
 808 In above figure, R3 is eBGP router with configured local-as of 62, and peer-as of 63.
 809
 810 In updates sent from R3 to R2, the AS_SEQUENCE in the AS_PATH attribute contains "62 63". And updates sent from R2 to R3, the AS_SEQUENCE in the AS_PATH attribute contains "62 65".
 811
 812 AS 62 will be prepended to updates that are sent to and received from R3.
 813
 814 Following configuration sample is intended for external peering with Local AS:
 815
 816 **URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/openconfig-network-instance:protocols/protocol=openconfig-policy-types:BGP/bgp-example/bgp/neighbors``
 817
 818 **Method:** ``POST``
 819
 820 .. tabs::
 821
 822    .. tab:: XML
 823
 824       **Content-Type:** ``application/xml``
 825
 826       **Request Body:**
 827
 828       .. code-block:: xml
 829          :linenos:
 830          :emphasize-lines: 5,6
 831
 832          <neighbor xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
 833              <neighbor-address>192.0.2.3</neighbor-address>
 834              <config>
 835                  <peer-type>EXTERNAL</peer-type>
 836                  <peer-as>63</peer-as>
 837                  <local-as>62</local-as>
 838              </config>
 839          </neighbor>
 840
 841       @line 5: AS number of the remote peer.
 842
 843       @line 6: Local AS number of the remote peer.
 844
 845    .. tab:: JSON
 846
 847       **Content-Type:** ``application/json``
 848
 849       **Request Body:**
 850
 851       .. code-block:: json
 852          :linenos:
 853          :emphasize-lines: 7,8
 854
 855          {
 856              "neighbor": [
 857                  {
 858                      "neighbor-address": "192.0.2.3",
 859                      "config": {
 860                          "peer-type": "EXTERNAL",
 861                          "peer-as": 63,
 862                          "local-as":62
 863                      }
 864                  }
 865              ]
 866          }
 867
 868       @line 7: AS number of the remote peer.
 869
 870       @line 8: Local AS number of the remote peer.
 871
 872 Route reflector configuration
 873 '''''''''''''''''''''''''''''
 874 The local BGP speaker can be configured with a specific *cluster ID*.
 875 Following example adds the cluster ID to the existing speaker instance:
 876
 877 **URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/openconfig-network-instance:protocols/protocol=openconfig-policy-types:BGP/bgp-example/bgp/global/config``
 878
 879 **Method:** ``PUT``
 880
 881 .. tabs::
 882
 883    .. tab:: XML
 884
 885       **Content-Type:** ``application/xml``
 886
 887       **Request Body:**
 888
 889       .. code-block:: xml
 890          :linenos:
 891          :emphasize-lines: 4
 892
 893          <config>
 894              <router-id>192.0.2.2</router-id>
 895              <as>65000</as>
 896              <route-reflector-cluster-id>192.0.2.1</route-reflector-cluster-id>
 897          </config>
 898
 899       @line 4: Route-reflector cluster id to use when local router is configured as a route reflector.
 900          The *router-id* is used as a default value.
 901
 902    .. tab:: JSON
 903
 904       **Content-Type:** ``application/json``
 905
 906       **Request Body:**
 907
 908       .. code-block:: json
 909          :linenos:
 910          :emphasize-lines: 5
 911
 912          {
 913              "bgp-openconfig-extensions:config": {
 914                  "router-id": "192.0.2.2",
 915                  "as": 65000,
 916                  "route-reflector-cluster-id": "192.0.2.1"
 917              }
 918          }
 919
 920       @line 5: Route-reflector cluster id to use when local router is configured as a route reflector.
 921          The *router-id* is used as a default value.
 922
 923 -----
 924
 925 Following configuration sample is intended for route reflector client peering:
 926
 927 **URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/openconfig-network-instance:protocols/protocol=openconfig-policy-types:BGP/bgp-example/bgp/neighbors``
 928
 929 **Method:** ``POST``
 930
 931 .. tabs::
 932
 933    .. tab:: XML
 934
 935       **Content-Type:** ``application/xml``
 936
 937       **Request Body:**
 938
 939       .. code-block:: xml
 940          :linenos:
 941          :emphasize-lines: 8
 942
 943          <neighbor xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
 944              <neighbor-address>192.0.2.4</neighbor-address>
 945              <config>
 946                  <peer-type>INTERNAL</peer-type>
 947              </config>
 948              <route-reflector>
 949                  <config>
 950                      <route-reflector-client>true</route-reflector-client>
 951                  </config>
 952              </route-reflector>
 953          </neighbor>
 954
 955       @line 8: Configure the neighbor as a route reflector client. Default value is *false*.
 956
 957    .. tab:: JSON
 958
 959       **Content-Type:** ``application/json``
 960
 961       **Request Body:**
 962
 963       .. code-block:: json
 964          :linenos:
 965          :emphasize-lines: 10
 966
 967          {
 968              "neighbor": [
 969                  {
 970                      "neighbor-address": "192.0.2.4",
 971                      "config": {
 972                          "peer-type": "INTERNAL"
 973                      },
 974                      "route-reflector": {
 975                          "config": {
 976                              "route-reflector-client": true
 977                          }
 978                      }
 979                  }
 980              ]
 981          }
 982
 983       @line 10: Configure the neighbor as a route reflector client. Default value is *false*.
 984
 985 Route reflector and Multiple Cluster IDs
 986 ''''''''''''''''''''''''''''''''''''''''
 987
 988 An optional non-transitive attribute called CLUSTER_LIST is modified when a route reflector reflects a prefix.
 989 For loop prevention the route reflector adds its own cluster ID to, and discards any update containing router's own cluster ID.
 990 Using multiple cluster IDs allows updates to propagate to nodes that reside in a different cluster.
 991
 992
 993 .. figure:: ./images/MultipleClustersIds.png
 994    :alt: BGP RR Multiple Cluster IDs setup.
 995
 996 Following configuration sample is intended for route reflector client peering using specific cluster id:
 997
 998 **URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/openconfig-network-instance:protocols/protocol=openconfig-policy-types:BGP/bgp-example/bgp/neighbors``
 999
1000 **Method:** ``POST``
1001
1002 .. tabs::
1003
1004    .. tab:: XML
1005
1006       **Content-Type:** ``application/xml``
1007
1008       **Request Body:**
1009
1010       .. code-block:: xml
1011          :linenos:
1012          :emphasize-lines: 8,9
1013
1014          <neighbor xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
1015              <neighbor-address>192.0.2.4</neighbor-address>
1016              <config>
1017                  <peer-type>INTERNAL</peer-type>
1018              </config>
1019              <route-reflector>
1020                  <config>
1021                      <route-reflector-client>true</route-reflector-client>
1022                      <route-reflector-cluster-id>192.0.2.4</route-reflector-cluster-id>
1023                  </config>
1024              </route-reflector>
1025          </neighbor>
1026
1027       @line 8: Configure the neighbor as a route reflector client. Default value is *false*.
1028
1029       @line 9: Route-reflector cluster id to use for this specific neighbor when local router is configured as a route reflector.
1030
1031    .. tab:: JSON
1032
1033       **Content-Type:** ``application/json``
1034
1035       **Request Body:**
1036
1037       .. code-block:: json
1038          :linenos:
1039          :emphasize-lines: 10,11
1040
1041          {
1042              "neighbor": [
1043                  {
1044                      "neighbor-address": "192.0.2.4",
1045                      "config": {
1046                          "peer-type": "INTERNAL"
1047                      },
1048                      "route-reflector": {
1049                          "config": {
1050                              "route-reflector-client": true,
1051                              "route-reflector-cluster-id":"192.0.2.4"
1052                          }
1053                      }
1054                  }
1055              ]
1056          }
1057
1058       @line 10: Configure the neighbor as a route reflector client. Default value is *false*.
1059
1060       @line 11: Route-reflector cluster id to use for this specific neighbor when local router is configured as a route reflector.
1061
1062 MD5 authentication configuration
1063 ''''''''''''''''''''''''''''''''
1064 The OpenDaylight BGP implementation is supporting TCP MD5 for authentication.
1065 Sample configuration below shows how to set authentication password for a peer:
1066
1067 **URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/openconfig-network-instance:protocols/protocol=openconfig-policy-types:BGP/bgp-example/bgp/neighbors``
1068
1069 **Method:** ``POST``
1070
1071 .. tabs::
1072
1073    .. tab:: XML
1074
1075       **Content-Type:** ``application/xml``
1076
1077       **Request Body:**
1078
1079       .. code-block:: xml
1080          :linenos:
1081          :emphasize-lines: 4
1082
1083          <neighbor xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
1084              <neighbor-address>192.0.2.5</neighbor-address>
1085              <config>
1086                  <auth-password>topsecret</auth-password>
1087              </config>
1088          </neighbor>
1089
1090       @line 4: Configures an MD5 authentication password for use with neighboring devices.
1091
1092    .. tab:: JSON
1093
1094       **Content-Type:** ``application/json``
1095
1096       **Request Body:**
1097
1098       .. code-block:: json
1099          :linenos:
1100          :emphasize-lines: 6
1101
1102          {
1103              "neighbor": [
1104                  {
1105                      "neighbor-address": "192.0.2.5",
1106                      "config": {
1107                          "auth-password": "topsecret"
1108                      }
1109                  }
1110              ]
1111          }
1112
1113       @line 6: Configures an MD5 authentication password for use with neighboring devices.
1114
1115 BGP Peer Group
1116 ''''''''''''''
1117
1118 Allows the creation of a peer group configuration that applies to all peers configured as part of the group.
1119
1120 A sample peer group configuration follows:
1121
1122 **URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/openconfig-network-instance:protocols/protocol=openconfig-policy-types:BGP/bgp-example/bgp/peer-groups``
1123
1124 **Method:** ``POST``
1125
1126 .. tabs::
1127
1128    .. tab:: XML
1129
1130       **Content-Type:** ``application/xml``
1131
1132       **Request Body:**
1133
1134       .. code-block:: xml
1135          :linenos:
1136          :emphasize-lines: 2
1137
1138          <peer-group xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
1139              <peer-group-name>internal-neighbor</peer-group-name>
1140              <config>
1141                  <peer-type>INTERNAL</peer-type>
1142                  <peer-as>64496</peer-as>
1143              </config>
1144              <transport>
1145                  <config>
1146                      <remote-port>179</remote-port>
1147                      <passive-mode>true</passive-mode>
1148                  </config>
1149              </transport>
1150              <timers>
1151                  <config>
1152                      <hold-time>180</hold-time>
1153                      <connect-retry>10</connect-retry>
1154                  </config>
1155              </timers>
1156              <route-reflector>
1157                  <config>
1158                      <route-reflector-client>false</route-reflector-client>
1159                  </config>
1160              </route-reflector>
1161              <afi-safis>
1162                  <afi-safi>
1163                      <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:IPV4-UNICAST</afi-safi-name>
1164                      <!--Advertise N Paths
1165                      <receive>true</receive>
1166                      <send-max>0</send-max>-->
1167                  </afi-safi>
1168                  <afi-safi>
1169                      <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:IPV6-UNICAST</afi-safi-name>
1170                  </afi-safi>
1171                  <afi-safi>
1172                      <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:IPV4-LABELLED-UNICAST</afi-safi-name>
1173                  </afi-safi>
1174                  <afi-safi>
1175                      <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:IPV6-LABELLED-UNICAST</afi-safi-name>
1176                  </afi-safi>
1177                  <afi-safi>
1178                      <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:L3VPN-IPV4-UNICAST</afi-safi-name>
1179                  </afi-safi>
1180                  <afi-safi>
1181                      <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:L3VPN-IPV6-UNICAST</afi-safi-name>
1182                  </afi-safi>
1183                  <afi-safi>
1184                      <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:L2VPN-EVPN</afi-safi-name>
1185                  </afi-safi>
1186                  <afi-safi>
1187                      <afi-safi-name>LINKSTATE</afi-safi-name>
1188                  </afi-safi>
1189                  <afi-safi>
1190                      <afi-safi-name>IPV4-FLOW</afi-safi-name>
1191                  </afi-safi>
1192                  <afi-safi>
1193                      <afi-safi-name>IPV6-FLOW</afi-safi-name>
1194                  </afi-safi>
1195                  <afi-safi>
1196                      <afi-safi-name>IPV4-L3VPN-FLOW</afi-safi-name>
1197                  </afi-safi>
1198                  <afi-safi>
1199                      <afi-safi-name>IPV6-L3VPN-FLOW</afi-safi-name>
1200                  </afi-safi>
1201              </afi-safis>
1202          </peer-group>
1203
1204       @line 2: Peer Group Identifier.
1205
1206    .. tab:: JSON
1207
1208       **Content-Type:** ``application/json``
1209
1210       **Request Body:**
1211
1212       .. code-block:: json
1213          :linenos:
1214          :emphasize-lines: 4
1215
1216          {
1217              "peer-group": [
1218                  {
1219                      "peer-group-name": "internal-neighbor",
1220                      "config": {
1221                          "peer-as": 64496,
1222                          "peer-type": "INTERNAL"
1223                      },
1224                      "transport": {
1225                          "config": {
1226                              "remote-port": 179,
1227                              "passive-mode": true
1228                          }
1229                      },
1230                      "timers": {
1231                          "config": {
1232                              "hold-time": 180,
1233                              "connect-retry": 10
1234                          }
1235                      },
1236                      "route-reflector": {
1237                          "config": {
1238                              "route-reflector-client": false
1239                          }
1240                      },
1241                      "afi-safis": {
1242                          "afi-safi": [
1243                              {
1244                                  "afi-safi-name": "openconfig-bgp-types:L2VPN-EVPN"
1245                              },
1246                              {
1247                                  "afi-safi-name": "openconfig-bgp-types:L3VPN-IPV6-UNICAST"
1248                              },
1249                              {
1250                                  "afi-safi-name": "bgp-openconfig-extensions:IPV6-FLOW"
1251                              },
1252                              {
1253                                  "afi-safi-name": "openconfig-bgp-types:IPV4-LABELLED-UNICAST"
1254                              },
1255                              {
1256                                  "afi-safi-name": "openconfig-bgp-types:L3VPN-IPV4-UNICAST"
1257                              },
1258                              {
1259                                  "afi-safi-name": "openconfig-bgp-types:IPV6-LABELLED-UNICAST"
1260                              },
1261                              {
1262                                  "afi-safi-name": "bgp-openconfig-extensions:LINKSTATE"
1263                              },
1264                              {
1265                                  "afi-safi-name": "openconfig-bgp-types:IPV6-UNICAST"
1266                              },
1267                              {
1268                                  "afi-safi-name": "bgp-openconfig-extensions:IPV4-L3VPN-FLOW"
1269                              },
1270                              {
1271                                  "afi-safi-name": "bgp-openconfig-extensions:IPV6-L3VPN-FLOW"
1272                              },
1273                              {
1274                                  "afi-safi-name": "openconfig-bgp-types:IPV4-UNICAST"
1275                              },
1276                              {
1277                                  "afi-safi-name": "bgp-openconfig-extensions:IPV4-FLOW"
1278                              }
1279                          ]
1280                      }
1281                  }
1282              ]
1283          }
1284
1285       @line 4: Peer Group Identifier.
1286
1287 -----
1288
1289 A sample basic neighbor configuration using a peer group follows:
1290
1291 **URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/openconfig-network-instance:protocols/protocol=openconfig-policy-types:BGP/bgp-example/bgp/neighbors``
1292
1293 **Method:** ``POST``
1294
1295 .. tabs::
1296
1297    .. tab:: XML
1298
1299       **Content-Type:** ``application/xml``
1300
1301       **Request Body:**
1302
1303       .. code-block:: xml
1304          :linenos:
1305          :emphasize-lines: 4
1306
1307          <neighbor xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
1308             <neighbor-address>192.0.2.1</neighbor-address>
1309             <config>
1310                <peer-group>/bgp/neighbors/neighbor/bgp/peer-groups/peer-group[peer-group-name="internal-neighbor"]</peer-group>
1311             </config>
1312          </neighbor>
1313
1314       @line 4: Peer group identifier.
1315
1316    .. tab:: JSON
1317
1318       **Content-Type:** ``application/json``
1319
1320       **Request Body:**
1321
1322       .. code-block:: json
1323          :linenos:
1324          :emphasize-lines: 6
1325
1326          {
1327              "neighbor": [
1328                  {
1329                      "neighbor-address": "192.0.2.1",
1330                      "config": {
1331                          "peer-group": "/bgp/neighbors/neighbor/bgp/peer-groups/peer-group[peer-group-name=\"internal-neighbor\"]"
1332                      }
1333                  }
1334              ]
1335          }
1336
1337       @line 6: Peer group identifier.
1338
1339 .. note:: Existing neighbor configuration can be reconfigured (change configuration parameters) anytime.
1340    As a result, established connection is dropped, peer instance is recreated with a new configuration settings and connection re-established.
1341
1342 .. note:: The BGP configuration is persisted on OpendDaylight shutdown and restored after the re-start.