docs/bgp/bgp-user-guide-ip-unicast-family.rst

   1 .. _bgp-user-guide-ip-unicast-family:
   2
   3 IP Unicast Family
   4 =================
   5 The BGP-4 allows to carry IPv4 specific information only.
   6 The basic BGP Multiprotocol extension brings *Unicast* Subsequent Address Family (SAFI) - intended to be used for IP unicast forwarding.
   7 The combination of IPv4 and IPv6 Address Family (AF) and Unicast SAFI is essential for Internet routing.
   8 The IPv4 Unicast routes are interchangeable with BGP-4 routes, as they can carry the same type of routing information.
   9
  10 .. contents:: Contents
  11    :depth: 2
  12    :local:
  13
  14 Configuration
  15 ^^^^^^^^^^^^^
  16 This section shows a way to enable IPv4 and IPv6 Unicast family in BGP speaker and peer configuration.
  17
  18 BGP Speaker
  19 '''''''''''
  20 To enable IPv4 and IPv6 Unicast 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:IPV4-UNICAST</afi-safi-name>
  44                    </afi-safi>
  45                    <afi-safi>
  46                        <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:IPV6-UNICAST</afi-safi-name>
  47                    </afi-safi>
  48                </afi-safis>
  49            </global>
  50        </bgp>
  51    </protocol>
  52
  53 BGP Peer
  54 ''''''''
  55 Here is an example for BGP peer configuration with enabled IPv4 and IPv6 Unicast family.
  56
  57 **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``
  58
  59 **Method:** ``POST``
  60
  61 **Content-Type:** ``application/xml``
  62
  63 **Request Body:**
  64
  65 .. code-block:: xml
  66
  67    <neighbor xmlns="urn:opendaylight:params:xml:ns:yang:bgp:openconfig-extensions">
  68        <neighbor-address>192.0.2.1</neighbor-address>
  69        <afi-safis>
  70            <afi-safi>
  71                <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:IPV4-UNICAST</afi-safi-name>
  72            </afi-safi>
  73            <afi-safi>
  74                <afi-safi-name xmlns:x="http://openconfig.net/yang/bgp-types">x:IPV6-UNICAST</afi-safi-name>
  75            </afi-safi>
  76        </afi-safis>
  77    </neighbor>
  78
  79 IP Unicast API
  80 ^^^^^^^^^^^^^^
  81 Following trees illustrate the BGP IP Unicast routes structures.
  82
  83 IPv4 Unicast Route
  84 ''''''''''''''''''
  85 .. code-block:: console
  86
  87    :(ipv4-routes-case)
  88       +--ro ipv4-routes
  89         +--ro ipv4-route* [route-key path-id]
  90            +--ro route-key     string
  91            +--ro prefix        inet:ipv4-prefix
  92            +--ro path-id       path-id
  93            +--ro attributes
  94               +--ro origin
  95               |  +--ro value    bgp-t:bgp-origin
  96               +--ro as-path
  97               |  +--ro segments*
  98               |     +--ro as-sequence*   inet:as-number
  99               |     +--ro as-set*        inet:as-number
 100               +--ro (c-next-hop)?
 101               |  +--:(ipv4-next-hop-case)
 102               |  |  +--ro ipv4-next-hop
 103               |  |     +--ro global?   inet:ipv4-address
 104               |  +--:(ipv6-next-hop-case)
 105               |  |  +--ro ipv6-next-hop
 106               |  |     +--ro global?       inet:ipv6-address
 107               |  |     +--ro link-local?   inet:ipv6-address
 108               |  +--:(empty-next-hop-case)
 109               |     +--ro empty-next-hop?            empty
 110               +--ro multi-exit-disc
 111               |  +--ro med?   uint32
 112               +--ro local-pref
 113               |  +--ro pref?   uint32
 114               +--ro atomic-aggregate!
 115               +--ro aggregator
 116               |  +--ro as-number?         inet:as-number
 117               |  +--ro network-address?   inet:ipv4-address
 118               +--ro communities*
 119               |  +--ro as-number?   inet:as-number
 120               |  +--ro semantics?   uint16
 121               +--ro extended-communities*
 122               |  +--ro transitive?                             boolean
 123               |  +--ro (extended-community)?
 124               |     +--:(as-specific-extended-community-case)
 125               |     |  +--ro as-specific-extended-community
 126               |     |     +--ro global-administrator?   short-as-number
 127               |     |     +--ro local-administrator?    binary
 128               |     +--:(inet4-specific-extended-community-case)
 129               |     |  +--ro inet4-specific-extended-community
 130               |     |     +--ro global-administrator?   inet:ipv4-address
 131               |     |     +--ro local-administrator?    binary
 132               |     +--:(opaque-extended-community-case)
 133               |     |  +--ro opaque-extended-community
 134               |     |     +--ro value?   binary
 135               |     +--:(route-target-extended-community-case)
 136               |     |  +--ro route-target-extended-community
 137               |     |     +--ro global-administrator?   short-as-number
 138               |     |     +--ro local-administrator?    binary
 139               |     +--:(route-origin-extended-community-case)
 140               |     |  +--ro route-origin-extended-community
 141               |     |     +--ro global-administrator?   short-as-number
 142               |     |     +--ro local-administrator?    binary
 143               |     +--:(route-target-ipv4-case)
 144               |     |  +--ro route-target-ipv4
 145               |     |     +--ro global-administrator?   inet:ipv4-address
 146               |     |     +--ro local-administrator?    uint16
 147               |     +--:(route-origin-ipv4-case)
 148               |     |  +--ro route-origin-ipv4
 149               |     |     +--ro global-administrator?   inet:ipv4-address
 150               |     |     +--ro local-administrator?    uint16
 151               |     +--:(link-bandwidth-case)
 152               |     |  +--ro link-bandwidth-extended-community
 153               |     |     +--ro bandwidth    netc:bandwidth
 154               |     +--:(as-4-generic-spec-extended-community-case)
 155               |     |  +--ro as-4-generic-spec-extended-community
 156               |     |     +--ro as-4-specific-common
 157               |     |        +--ro as-number              inet:as-number
 158               |     |        +--ro local-administrator    uint16
 159               |     +--:(as-4-route-target-extended-community-case)
 160               |     |  +--ro as-4-route-target-extended-community
 161               |     |     +--ro as-4-specific-common
 162               |     |        +--ro as-number              inet:as-number
 163               |     |        +--ro local-administrator    uint16
 164               |     +--:(as-4-route-origin-extended-community-case)
 165               |     |  +--ro as-4-route-origin-extended-community
 166               |     |     +--ro as-4-specific-common
 167               |     |        +--ro as-number              inet:as-number
 168               |     |        +--ro local-administrator    uint16
 169               |     +--:(encapsulation-case)
 170               |        +--ro encapsulation-extended-community
 171               |           +--ro tunnel-type    encapsulation-tunnel-type
 172               +--ro originator-id
 173               |  +--ro originator?   inet:ipv4-address
 174               +--ro cluster-id
 175               |  +--ro cluster*   bgp-t:cluster-identifier
 176               +--ro aigp
 177               |  +--ro aigp-tlv
 178               |     +--ro metric?   netc:accumulated-igp-metric
 179               +--ro unrecognized-attributes* [type]
 180                  +--ro partial       boolean
 181                  +--ro transitive    boolean
 182                  +--ro type          uint8
 183                  +--ro value         binary
 184
 185 IPv6 Unicast Route
 186 ''''''''''''''''''
 187 .. code-block:: console
 188
 189    :(ipv6-routes-case)
 190       +--ro ipv6-routes
 191          +--ro ipv6-route* [route-key path-id]
 192             +--ro route-key     string
 193             +--ro prefix        inet:ipv6-prefix
 194             +--ro path-id       path-id
 195             +--ro attributes
 196             ...
 197
 198 Usage
 199 ^^^^^
 200 IPv4 Unicast
 201 ''''''''''''
 202 The IPv4 Unicast table in an instance of the speaker's Loc-RIB can be verified via REST:
 203
 204 **URL:** ``/restconf/operational/bgp-rib:bgp-rib/rib/bgp-example/loc-rib/tables/bgp-types:ipv4-address-family/bgp-types:unicast-subsequent-address-family/ipv4-routes``
 205
 206 **Method:** ``GET``
 207
 208 **Response Body:**
 209
 210 .. code-block:: xml
 211
 212    <ipv4-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
 213        <ipv4-route>
 214            <route-key>193.0.2.1/32</route-key>
 215            <path-id>0</path-id>
 216            <prefix>193.0.2.1/32</prefix>
 217            <attributes>
 218                <as-path></as-path>
 219                <origin>
 220                    <value>igp</value>
 221                </origin>
 222                <local-pref>
 223                    <pref>100</pref>
 224                </local-pref>
 225                <ipv4-next-hop>
 226                    <global>10.0.0.1</global>
 227                </ipv4-next-hop>
 228            </attributes>
 229        </ipv4-route>
 230    </ipv4-routes>
 231
 232 IPv6 Unicast
 233 ''''''''''''
 234 The IPv6 Unicast table in an instance of the speaker's Loc-RIB can be verified via REST:
 235
 236 **URL:** ``/restconf/operational/bgp-rib:bgp-rib/rib/bgp-example/loc-rib/tables/bgp-types:ipv4-address-family/bgp-types:unicast-subsequent-address-family/ipv6-routes``
 237
 238 **Method:** ``GET``
 239
 240 **Response Body:**
 241
 242 .. code-block:: xml
 243
 244    <ipv6-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
 245        <ipv6-route>
 246            <route-key>2a02:b80:0:1::/64</route-key>
 247            <path-id>0</path-id>
 248            <prefix>2a02:b80:0:1::/64</prefix>
 249            <attributes>
 250                <as-path></as-path>
 251                <origin>
 252                    <value>igp</value>
 253                </origin>
 254                <local-pref>
 255                    <pref>200</pref>
 256                </local-pref>
 257                <ipv6-next-hop>
 258                    <global>2a02:b80:0:2::1</global>
 259                </ipv6-next-hop>
 260            </attributes>
 261        </ipv6-route>
 262    </ipv6-routes>
 263
 264 .. note:: IPv4/6 routes mapping to topology nodes is supported by BGP Topology Provider.
 265
 266 Programming
 267 ^^^^^^^^^^^
 268 IPv4 Unicast
 269 ''''''''''''
 270 This examples show how to originate and remove IPv4 route via programmable RIB.
 271 Make sure the *Application Peer* is configured first.
 272
 273 .. note:: IPv4 Route Key must be equal to prefix.
 274
 275 **URL:** ``/restconf/config/bgp-rib:application-rib/10.25.1.9/tables/bgp-types:ipv4-address-family/bgp-types:unicast-subsequent-address-family/bgp-inet:ipv4-routes``
 276
 277 **Method:** ``POST``
 278
 279 **Content-Type:** ``application/xml``
 280
 281 **Request Body:**
 282
 283 .. code-block:: xml
 284
 285    <ipv4-route xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
 286        <route-key>10.0.0.11/32</route-key>
 287        <prefix>10.0.0.11/32</prefix>
 288        <path-id>0</path-id>
 289        <attributes>
 290            <as-path></as-path>
 291            <origin>
 292                <value>igp</value>
 293            </origin>
 294            <local-pref>
 295                <pref>100</pref>
 296            </local-pref>
 297            <ipv4-next-hop>
 298                <global>10.11.1.1</global>
 299            </ipv4-next-hop>
 300        </attributes>
 301    </ipv4-route>
 302
 303 -----
 304
 305 To remove the route added above, following request can be used:
 306
 307 **URL:** ``/restconf/config/bgp-rib:application-rib/10.25.1.9/tables/bgp-types:ipv4-address-family/bgp-types:unicast-subsequent-address-family/bgp-inet:ipv4-routes/ipv4-route/10.0.0.11%2F32/0``
 308
 309 **Method:** ``DELETE``
 310
 311 IPv6 Unicast
 312 ''''''''''''
 313 This examples show how to originate and remove IPv6 route via programmable RIB:
 314
 315 .. note:: IPv6 Route Key must be equal to prefix.
 316
 317 **URL:** ``/restconf/config/bgp-rib:application-rib/10.25.1.9/tables/bgp-types:ipv6-address-family/bgp-types:unicast-subsequent-address-family/bgp-inet:ipv6-routes``
 318
 319 **Method:** ``POST``
 320
 321 **Content-Type:** ``application/xml``
 322
 323 **Request Body:**
 324
 325 .. code-block:: xml
 326
 327    <ipv6-route xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
 328        <route-key>2001:db8:30::3/128</route-key>
 329        <prefix>2001:db8:30::3/128</prefix>
 330        <path-id>0</path-id>
 331        <attributes>
 332            <ipv6-next-hop>
 333                <global>2001:db8:1::6</global>
 334            </ipv6-next-hop>
 335            <as-path/>
 336            <origin>
 337                <value>igp</value>
 338            </origin>
 339            <local-pref>
 340                <pref>100</pref>
 341            </local-pref>
 342        </attributes>
 343    </ipv6-route>
 344
 345 -----
 346
 347 To remove the route added above, following request can be used:
 348
 349 **URL:** ``/restconf/config/bgp-rib:application-rib/10.25.1.9/tables/bgp-types:ipv6-address-family/bgp-types:unicast-subsequent-address-family/bgp-inet:ipv6-routes/ipv6-route/2001:db8:30::3%2F128/0``
 350
 351 **Method:** ``DELETE``
 352
 353 References
 354 ^^^^^^^^^^
 355 * `Multiprotocol Extensions for BGP-4 <https://tools.ietf.org/html/rfc4760>`_