.. _bgp-user-guide-flowspec-family:
Flow Specification Family
=========================
The BGP Flow Specification (BGP-FS) Multiprotocol extension can be used to distribute traffic flow specifications.
For example, the BGP-FS can be used in a case of (distributed) denial-of-service (DDoS) attack mitigation procedures and traffic filtering (BGP/MPLS VPN service, DC).
.. contents:: Contents
:depth: 2
:local:
Configuration
^^^^^^^^^^^^^
This section shows a way to enable BGP-FS family in BGP speaker and peer configuration.
BGP Speaker
'''''''''''
To enable BGP-FS support in BGP plugin, first configure BGP speaker instance:
**URL:** ``/rests/data/openconfig-network-instance:network-instances/network-instance=global-bgp/protocols``
**Method:** ``POST``
.. tabs::
.. tab:: XML
**Content-Type:** ``application/xml``
**Request Body:**
.. code-block:: xml
bgp-example
x:BGP
192.0.2.2
65000
IPV4-FLOW
IPV6-FLOW
IPV4-L3VPN-FLOW
IPV6-L3VPN-FLOW
.. tab:: JSON
**Content-Type:** ``application/json``
**Request Body:**
.. code-block:: json
{
"protocol": [
{
"identifier": "openconfig-policy-types:BGP",
"name": "bgp-example",
"bgp-openconfig-extensions:bgp": {
"global": {
"config": {
"router-id": "192.0.2.2",
"as": 65000
},
"afi-safis": {
"afi-safi": [
{
"afi-safi-name": "IPV4-FLOW"
},
{
"afi-safi-name": "IPV6-FLOW"
},
{
"afi-safi-name": "IPV4-L3VPN-FLOW"
},
{
"afi-safi-name": "IPV6-L3VPN-FLOW"
}
]
}
}
}
}
]
}
BGP Peer
''''''''
Here is an example for BGP peer configuration with enabled BGP-FS family.
**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``
**Method:** ``POST``
.. tabs::
.. tab:: XML
**Content-Type:** ``application/xml``
**Request Body:**
.. code-block:: xml
192.0.2.1
IPV4-FLOW
IPV6-FLOW
IPV4-L3VPN-FLOW
IPV6-L3VPN-FLOW
.. tab:: JSON
**Content-Type:** ``application/json``
**Request Body:**
.. code-block:: json
{
"neighbor": [
{
"neighbor-address": "192.0.2.1",
"afi-safis": {
"afi-safi": [
{
"afi-safi-name": "IPV4-FLOW"
},
{
"afi-safi-name": "IPV6-FLOW"
},
{
"afi-safi-name": "IPV4-L3VPN-FLOW"
},
{
"afi-safi-name": "IPV6-L3VPN-FLOW"
}
]
}
}
]
}
Flow Specification API
^^^^^^^^^^^^^^^^^^^^^^
Following trees illustrate the BGP Flow Specification routes structure.
IPv4 Flow Specification Route
'''''''''''''''''''''''''''''
.. code-block:: console
:(flowspec-routes-case)
+--ro flowspec-routes
+--ro flowspec-route* [route-key path-id]
+--ro route-key string
+--ro flowspec*
| +--ro (flowspec-type)?
| +--:(port-case)
| | +--ro ports*
| | +--ro op? numeric-operand
| | +--ro value? uint16
| +--:(destination-port-case)
| | +--ro destination-ports*
| | +--ro op? numeric-operand
| | +--ro value? uint16
| +--:(source-port-case)
| | +--ro source-ports*
| | +--ro op? numeric-operand
| | +--ro value? uint16
| +--:(icmp-type-case)
| | +--ro types*
| | +--ro op? numeric-operand
| | +--ro value? uint8
| +--:(icmp-code-case)
| | +--ro codes*
| | +--ro op? numeric-operand
| | +--ro value? uint8
| +--:(tcp-flags-case)
| | +--ro tcp-flags*
| | +--ro op? bitmask-operand
| | +--ro value? uint16
| +--:(packet-length-case)
| | +--ro packet-lengths*
| | +--ro op? numeric-operand
| | +--ro value? uint16
| +--:(dscp-case)
| | +--ro dscps*
| | +--ro op? numeric-operand
| | +--ro value? dscp
| +--:(fragment-case)
| | +--ro fragments*
| | +--ro op? bitmask-operand
| | +--ro value? fragment
| +--:(destination-prefix-case)
| | +--ro destination-prefix? inet:ipv4-prefix
| +--:(source-prefix-case)
| | +--ro source-prefix? inet:ipv4-prefix
| +--:(protocol-ip-case)
| +--ro protocol-ips*
| +--ro op? numeric-operand
| +--ro value? uint8
+--ro path-id path-id
+--ro attributes
+--ro extended-communities*
+--ro transitive? boolean
+--ro (extended-community)?
+--:(traffic-rate-extended-community-case)
| +--ro traffic-rate-extended-community
| +--ro informative-as? bgp-t:short-as-number
| +--ro local-administrator? netc:bandwidth
+--:(traffic-action-extended-community-case)
| +--ro traffic-action-extended-community
| +--ro sample? boolean
| +--ro terminal-action? boolean
+--:(redirect-extended-community-case)
| +--ro redirect-extended-community
| +--ro global-administrator? bgp-t:short-as-number
| +--ro local-administrator? binary
+--:(traffic-marking-extended-community-case)
| +--ro traffic-marking-extended-community
| +--ro global-administrator? dscp
+--:(redirect-ipv4-extended-community-case)
| +--ro redirect-ipv4
| +--ro global-administrator? inet:ipv4-address
| +--ro local-administrator? uint16
+--:(redirect-as4-extended-community-case)
| +--ro redirect-as4
| +--ro global-administrator? inet:as-number
| +--ro local-administrator? uint16
+--:(redirect-ip-nh-extended-community-case)
+--ro redirect-ip-nh-extended-community
+--ro next-hop-address? inet:ip-address
+--ro copy? boolean
IPv6 Flow Specification Route
'''''''''''''''''''''''''''''
.. code-block:: console
:(flowspec-ipv6-routes-case)
+--ro flowspec-ipv6-routes
+--ro flowspec-route* [route-key path-id]
+--ro flowspec*
| +--ro (flowspec-type)?
| +--:(port-case)
| | +--ro ports*
| | +--ro op? numeric-operand
| | +--ro value? uint16
| +--:(destination-port-case)
| | +--ro destination-ports*
| | +--ro op? numeric-operand
| | +--ro value? uint16
| +--:(source-port-case)
| | +--ro source-ports*
| | +--ro op? numeric-operand
| | +--ro value? uint16
| +--:(icmp-type-case)
| | +--ro types*
| | +--ro op? numeric-operand
| | +--ro value? uint8
| +--:(icmp-code-case)
| | +--ro codes*
| | +--ro op? numeric-operand
| | +--ro value? uint8
| +--:(tcp-flags-case)
| | +--ro tcp-flags*
| | +--ro op? bitmask-operand
| | +--ro value? uint16
| +--:(packet-length-case)
| | +--ro packet-lengths*
| | +--ro op? numeric-operand
| | +--ro value? uint16
| +--:(dscp-case)
| | +--ro dscps*
| | +--ro op? numeric-operand
| | +--ro value? dscp
| +--:(fragment-case)
| | +--ro fragments*
| | +--ro op? bitmask-operand
| | +--ro value? fragment
| +--:(destination-ipv6-prefix-case)
| | +--ro destination-prefix? inet:ipv6-prefix
| +--:(source-ipv6-prefix-case)
| | +--ro source-prefix? inet:ipv6-prefix
| +--:(next-header-case)
| | +--ro next-headers*
| | +--ro op? numeric-operand
| | +--ro value? uint8
| +--:(flow-label-case)
| +--ro flow-label*
| +--ro op? numeric-operand
| +--ro value? uint32
+--ro path-id path-id
+--ro attributes
+--ro extended-communities*
+--ro transitive? boolean
+--ro (extended-community)?
+--:(traffic-rate-extended-community-case)
| +--ro traffic-rate-extended-community
| +--ro informative-as? bgp-t:short-as-number
| +--ro local-administrator? netc:bandwidth
+--:(traffic-action-extended-community-case)
| +--ro traffic-action-extended-community
| +--ro sample? boolean
| +--ro terminal-action? boolean
+--:(redirect-extended-community-case)
| +--ro redirect-extended-community
| +--ro global-administrator? bgp-t:short-as-number
| +--ro local-administrator? binary
+--:(traffic-marking-extended-community-case)
| +--ro traffic-marking-extended-community
| +--ro global-administrator? dscp
+--:(redirect-ipv6-extended-community-case)
| +--ro redirect-ipv6
| +--ro global-administrator? inet:ipv6-address
| +--ro local-administrator? uint16
+--:(redirect-as4-extended-community-case)
| +--ro redirect-as4
| +--ro global-administrator? inet:as-number
| +--ro local-administrator? uint16
+--:(redirect-ip-nh-extended-community-case)
+--ro redirect-ip-nh-extended-community
+--ro next-hop-address? inet:ip-address
+--ro copy? boolean
Usage
^^^^^
The flowspec route represents rules and an action, defined as an extended community.
IPv4 Flow Specification
'''''''''''''''''''''''
The IPv4 Flowspec table in an instance of the speaker's Loc-RIB can be verified via REST:
**URL:** ``/rests/data/bgp-rib:bgp-rib/rib/bgp-example/loc-rib/tables=bgp-types:ipv4-address-family,bgp-flowspec:flowspec-subsequent-address-family/bgp-flowspec:flowspec-routes?content=nonconfig``
**Method:** ``GET``
.. tabs::
.. tab:: XML
**Response Body:**
.. code-block:: xml
0
all packets to 192.168.0.1/32 AND from 10.0.0.2/32 AND where IP protocol equals to 17 or equals to 6 AND where port equals to 80 or equals to 8080 AND where destination port is greater than 8080 and is less than 8088 or equals to 3128 AND where source port is greater than 1024
100
igp
true
AgMWLg==
258
192.168.0.1/32
10.0.0.2/32
equals
17
equals end-of-list
6
equals
80
equals end-of-list
8080
greater-than
8080
less-than and-bit
8088
equals end-of-list
3128
end-of-list greater-than
1024
.. tab:: JSON
**Response Body:**
.. code-block:: json
{
"flowspec-routes": {
"flowspec-route": {
"path-id": 0,
"route-key": "all packets to 192.168.0.1/32 AND from 10.0.0.2/32 AND where IP protocol equals to 17 or equals to 6 AND where port equals to 80 or equals to 8080 AND where destination port is greater than 8080 and is less than 8088 or equals to 3128 AND where source port is greater than 1024",
"attributes": {
"local-pref": {
"pref": 100
},
"origin": {
"value": "igp"
},
"extended-communities": {
"transitive": "true",
"redirect-extended-community": {
"local-administrator": "AgMWLg==",
"global-administrator": 258
}
}
},
"flowspec": [
{
"destination-prefix": "192.168.0.1/32"
},
{
"source-prefix": "10.0.0.2/32"
},
{
"protocol-ips": [
{
"op": "equals",
"value": 17
},
{
"op": "equals end-of-list",
"value": 6
}
]
},
{
"ports": [
{
"op": "equals",
"value": 80
},
{
"op": "equals end-of-list",
"value": 8080
}
]
},
{
"destination-ports": [
{
"op": "greater-than",
"value": 8080
},
{
"op": "less-than and-bit",
"value": 8088
},
{
"op": "equals end-of-list",
"value": 3128
}
]
},
{
"source-ports": {
"op": "end-of-list greater-than",
"value": 1024
}
}
]
}
}
}
IPv6 Flows Specification
''''''''''''''''''''''''
The IPv6 Flowspec table in an instance of the speaker's Loc-RIB can be verified via REST:
**URL:** ``/rests/data/bgp-rib:bgp-rib/rib/bgp-example/loc-rib/tables=bgp-types:ipv6-address-family,bgp-flowspec:flowspec-subsequent-address-family/bgp-flowspec:flowspec-ipv6-routes?content=nonconfig``
**Method:** ``GET``
.. tabs::
.. tab:: XML
**Response Body:**
.. code-block:: xml
0
all packets to 2001:db8:31::/64 AND from 2001:db8:30::/64 AND where next header equals to 17 AND where DSCP equals to 50 AND where flow label equals to 2013
100
igp
true
0
AAAAAA==
2001:db8:31::/64
2001:db8:30::/64
equals end-of-list
17
equals end-of-list
50
equals end-of-list
2013
.. tab:: JSON
**Response Body:**
.. code-block:: json
{
"flowspec-ipv6-routes": {
"flowspec-route": {
"path-id": 0,
"route-key": "all packets to 2001:db8:31::/64 AND from 2001:db8:30::/64 AND where next header equals to 17 AND where DSCP equals to 50 AND where flow label equals to 2013",
"attributes": {
"local-pref": {
"pref": 100
},
"origin": {
"value": "igp"
},
"extended-communities": {
"transitive": true,
"traffic-rate-extended-community": {
"informative-as": 0,
"local-administrator": "AAAAAA=="
}
}
},
"flowspec": [
{
"destination-prefix": "2001:db8:31::/64"
},
{
"source-prefix": "2001:db8:30::/64"
},
{
"next-headers": {
"op": "equals end-of-list",
"value": 17
}
},
{
"dscps": {
"op": "equals end-of-list",
"value": 50
}
},
{
"flow-label": {
"op": "equals end-of-list",
"value": 2013
}
}
]
}
}
}
IPv4 L3VPN Flows Specification
''''''''''''''''''''''''''''''
The IPv4 L3VPN Flowspec table in an instance of the speaker's Loc-RIB can be verified via REST:
**URL:** ``/rests/data/bgp-rib:bgp-rib/rib/bgp-example/loc-rib/tables=bgp-types:ipv4-address-family,bgp-flowspec:flowspec-l3vpn-subsequent-address-family/bgp-flowspec:flowspec-l3vpn-ipv4-routes?content=nonconfig``
**Method:** ``GET``
.. tabs::
.. tab:: XML
**Response Body:**
.. code-block:: xml
0
[l3vpn with route-distinguisher 172.16.0.44:101] all packets from 10.0.0.3/32
100
5.6.7.8
igp
true
false
0.0.0.0
172.16.0.44:101
10.0.0.3/32
.. tab:: JSON
**Response Body:**
.. code-block:: json
{
"flowspec-l3vpn-ipv4-routes": {
"flowspec-l3vpn-route": {
"path-id": 0,
"route-key": "[l3vpn with route-distinguisher 172.16.0.44:101] all packets from 10.0.0.3/32",
"attributes": {
"local-pref": {
"pref": 100
},
"ipv4-next-hop": {
"global":"5.6.7.8"
},
"origin": {
"value": "igp"
},
"extended-communities": {
"transitive": true,
"redirect-ip-nh-extended-community": {
"copy": false,
"next-hop-address": "0.0.0.0"
}
}
},
"route-distinguisher": "172.16.0.44:101",
"flowspec": {
"source-prefix": "10.0.0.3/32"
}
}
}
}
Programming
^^^^^^^^^^^
IPv4 Flow Specification
'''''''''''''''''''''''
This examples show how to originate and remove IPv4 fowspec route via programmable RIB.
Make sure the *Application Peer* is configured first.
**URL:** ``/rests/data/bgp-rib:application-rib/10.25.1.9/tables=bgp-types:ipv4-address-family,bgp-flowspec:flowspec-subsequent-address-family/bgp-flowspec:flowspec-routes``
**Method:** ``POST``
.. tabs::
.. tab:: XML
**Content-Type:** ``application/xml``
**Request Body:**
.. code-block:: xml
flow1
0
192.168.0.1/32
10.0.0.1/32
equals end-of-list
6
equals end-of-list
80
greater-than
8080
and-bit less-than end-of-list
8088
greater-than end-of-list
1024
equals end-of-list
0
equals end-of-list
0
match end-of-list
32
greater-than
400
and-bit less-than end-of-list
500
equals end-of-list
20
match end-of-list
first
igp
100
....
.. tab:: JSON
**Content-Type:** ``application/json``
**Request Body:**
.. code-block:: json
{
"flowspec-route": [
{
"route-key": "flow1",
"path-id": 0,
"flowspec": [
{
"destination-prefix": "192.168.0.1/32"
},
{
"source-prefix": "10.0.0.1/32"
},
{
"protocol-ips": [
{
"op": "end-of-list equals",
"value": 6
}
]
},
{
"ports": [
{
"op": "end-of-list equals",
"value": 80
}
]
},
{
"destination-ports": [
{
"op": "greater-than",
"value": 8080
},
{
"op": "end-of-list and-bit less-than",
"value": 8088
}
]
},
{
"source-ports": [
{
"op": "end-of-list greater-than",
"value": 1024
}
]
},
{
"types": [
{
"op": "end-of-list equals",
"value": 0
}
]
},
{
"codes": [
{
"op": "end-of-list equals",
"value": 0
}
]
},
{
"tcp-flags": [
{
"op": "end-of-list match",
"value": 32
}
]
},
{
"packet-lengths": [
{
"op": "greater-than",
"value": 400
},
{
"op": "end-of-list and-bit less-than",
"value": 500
}
]
},
{
"dscps": [
{
"op": "end-of-list equals",
"value": 20
}
]
},
{
"fragments": [
{
"op": "end-of-list match",
"value": "first"
}
]
}
],
"attributes": {
"origin": {
"value": "igp"
},
"local-pref": {
"pref": 100
}
}
}
]
}
-----
**Extended Communities**
* **Traffic Rate**
.. tabs::
.. tab:: XML
.. code-block:: xml
:linenos:
:emphasize-lines: 5
true
123
AAAAAA==
@line 5: A rate in bytes per second, *AAAAAA==* (0) means traffic discard.
.. tab:: JSON
.. code-block:: json
:linenos:
:emphasize-lines: 6
{
"extended-communities" : {
"transitive": true,
"traffic-rate-extended-community": {
"informative-as": 123,
"local-administrator": "AAAAAA=="
}
}
}
@line 6: A rate in bytes per second, *AAAAAA==* (0) means traffic discard.
* **Traffic Action**
.. tabs::
.. tab:: XML
.. code-block:: xml
true
true
false
.. tab:: JSON
.. code-block:: json
{
"extended-communities" : {
"transitive": true,
"traffic-action-extended-community": {
"sample": true,
"terminal-action": false
}
}
}
* **Redirect to VRF AS 2byte format**
.. tabs::
.. tab:: XML
.. code-block:: xml
true
123
AAAAew==
.. tab:: JSON
.. code-block:: json
{
"extended-communities" : {
"transitive": true,
"redirect-extended-community": {
"global-administrator": 123,
"local-administrator": "AAAAew=="
}
}
}
* **Redirect to VRF IPv4 format**
.. tabs::
.. tab:: XML
.. code-block:: xml
true
192.168.0.1
12345
.. tab:: JSON
.. code-block:: json
{
"extended-communities" : {
"transitive": true,
"redirect-ipv4": {
"global-administrator": "192.168.0.1",
"local-administrator": 12345
}
}
}
* **Redirect to VRF AS 4byte format**
.. tabs::
.. tab:: XML
.. code-block:: xml
true
64495
12345
.. tab:: JSON
.. code-block:: json
{
"extended-communities" : {
"transitive": true,
"redirect-as4": {
"global-administrator": 64495,
"local-administrator": 12345
}
}
}
* **Redirect to IP**
.. tabs::
.. tab:: XML
.. code-block:: xml
true
false
.. tab:: JSON
.. code-block:: json
{
"extended-communities" : {
"transitive": true,
"redirect-ip-nh-extended-community": {
"copy": false
}
}
}
* **Traffic Marking**
.. tabs::
.. tab:: XML
.. code-block:: xml
true
20
.. tab:: JSON
.. code-block:: json
{
"extended-communities" : {
"transitive": true,
"traffic-marking-extended-community": {
"global-administrator": 20
}
}
}
-----
To remove the route added above, following request can be used:
**URL:** ``/rests/data/bgp-rib:application-rib/10.25.1.9/tables=bgp-types:ipv4-address-family,bgp-flowspec:flowspec-subsequent-address-family/bgp-flowspec:flowspec-routes/bgp-flowspec:flowspec-route/flow1/0``
**Method:** ``DELETE``
IPv4 L3VPN Flow Specification
'''''''''''''''''''''''''''''
This examples show how to originate and remove IPv4 L3VPN fowspec route via programmable RIB.
**URL:** ``/rests/data/bgp-rib:application-rib/10.25.1.9/tables=bgp-types:ipv4-address-family,bgp-flowspec:flowspec-l3vpn-subsequent-address-family/bgp-flowspec:flowspec-l3vpn-ipv4-routes``
**Method:** ``POST``
.. tabs::
.. tab:: XML
**Content-Type:** ``application/xml``
**Request Body:**
.. code-block:: xml
0
flow-l3vpn
172.16.0.44:101
10.0.0.3/32
100
igp
true
172.16.0.44
102
.. tab:: JSON
**Content-Type:** ``application/json``
**Request Body:**
.. code-block:: json
{
"flowspec-l3vpn-route": [
{
"route-key": "flow-l3vpn",
"path-id": 0,
"route-distinguisher": "172.16.0.44:101",
"flowspec": [
{
"source-prefix": "10.0.0.3/32"
}
],
"attributes": {
"origin": {
"value": "igp"
},
"extended-communities": [
{
"redirect-ipv4": {
"global-administrator": "172.16.0.44",
"local-administrator": 102
},
"transitive": true
}
],
"local-pref": {
"pref": 100
}
}
}
]
}
-----
To remove the route added above, following request can be used:
**URL:** ``/rests/data/bgp-rib:application-rib/10.25.1.9/tables=bgp-types:ipv4-address-family,bgp-flowspec:flowspec-l3vpn-subsequent-address-family/bgp-flowspec:flowspec-l3vpn-ipv4-routes/flowspec-l3vpn-route/flow-l3vpn/0``
**Method:** ``DELETE``
IPv6 Flow Specification
'''''''''''''''''''''''
This examples show how to originate and remove IPv6 fowspec route via programmable RIB.
**URL:** ``/rests/data/bgp-rib:application-rib/10.25.1.9/tables=bgp-types:ipv6-address-family,bgp-flowspec:flowspec-subsequent-address-family/bgp-flowspec:flowspec-ipv6-routes``
**Method:** ``POST``
.. tabs::
.. tab:: XML
**Content-Type:** ``application/xml``
**Request Body:**
.. code-block:: xml
flow-v6
0
2001:db8:30::3/128
2001:db8:31::3/128
equals end-of-list
1
true
2001:db8:1::6
12345
igp
100
.. tab:: JSON
**Content-Type:** ``application/json``
**Request Body:**
.. code-block:: json
{
"flowspec-route": [
{
"route-key": "flow-v6",
"path-id": 0,
"flowspec": [
{
"destination-prefix": "2001:db8:30::3/128"
},
{
"source-prefix": "2001:db8:31::3/128"
},
{
"flow-label": [
{
"op": "end-of-list equals",
"value": 1
}
]
}
],
"attributes": {
"origin": {
"value": "igp"
},
"extended-communities": [
{
"redirect-ipv6": {
"global-administrator": "2001:db8:1::6",
"local-administrator": 12345
},
"transitive": true
}
],
"local-pref": {
"pref": 100
}
}
}
]
}
-----
To remove the route added above, following request can be used:
**URL:** ``/rests/data/bgp-rib:application-rib/10.25.1.9/tables=bgp-types:ipv6-address-family,bgp-flowspec:flowspec-subsequent-address-family/bgp-flowspec:flowspec-ipv6-routes/bgp-flowspec:flowspec-route/flow-v6/0``
**Method:** ``DELETE``
References
^^^^^^^^^^
* `Dissemination of Flow Specification Rules `_
* `Dissemination of Flow Specification Rules for IPv6 `_
* `BGP Flow-Spec Extended Community for Traffic Redirect to IP Next Hop `_
* `Clarification of the Flowspec Redirect Extended Community `_
* `Revised Validation Procedure for BGP Flow Specifications `_