proxmox-mirrors/mirror_frr
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_frr synced 2025-08-15 06:43:16 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc: clean up flowspec.rst

Browse Source 
* Fix broken citations
* Remove trailing whitespace
* Rewrap to 80 lines
* Tweak capitalization of section headers
* Clean up a few indented blocks

Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
This commit is contained in:
Quentin Young 2018-07-02 19:22:12 +00:00 committed by Philippe Guibert
parent b0b3080e0f
commit 9c8726a33e
1 changed files with 76 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
doc/user/flowspec.rst
View File

@ -16,10 +16,10 @@ more or less complex combination of the following:
- Network source/destination (can be one or the other, or both). - Network source/destination (can be one or the other, or both).
- Layer 4 information for UDP/TCP : source port, destination port, or any port. - Layer 4 information for UDP/TCP: source port, destination port, or any port.
- Layer 4 information for ICMP type and ICMP code. - Layer 4 information for ICMP type and ICMP code.
- Layer 4 information for TCP Flags. - Layer 4 information for TCP Flags.
- Layer 3 information : DSCP value, Protocol type, packet length, fragmentation. - Layer 3 information: DSCP value, Protocol type, packet length, fragmentation.
- Misc layer 4 TCP flags. - Misc layer 4 TCP flags.
A combination of the above rules is applied for traffic filtering. This is A combination of the above rules is applied for traffic filtering. This is
@ -30,7 +30,7 @@ discard.
The following IETF drafts and RFCs have been used to implement FRR Flowspec: The following IETF drafts and RFCs have been used to implement FRR Flowspec:
- :rfc:`5575` - :rfc:`5575`
- [Draft IETF IDR Flowspec redirect IP]_ - [Draft-IETF-IDR-Flowspec-redirect-IP]_
.. _design-principles-flowspec: .. _design-principles-flowspec:
@ -70,13 +70,13 @@ system:
For handling an incoming Flowspec entry, the following workflow is applied: For handling an incoming Flowspec entry, the following workflow is applied:
- incoming Flowspec entries are handled by *bgpd*, stored in the BGP RIB. - Incoming Flowspec entries are handled by *bgpd*, stored in the BGP RIB.
- Flowspec entry is installed according to its complexity. - Flowspec entry is installed according to its complexity.
It will be installed if one of the following filtering action is seen on the BGP It will be installed if one of the following filtering action is seen on the
extended community: either redirect IP, or redirect VRF, in conjunction with BGP extended community: either redirect IP, or redirect VRF, in conjunction
rate option, for redirecting traffic. Or rate option set to 0, for discarding with rate option, for redirecting traffic. Or rate option set to 0, for
traffic. discarding traffic.
According to the degree of complexity of the Flowspec entry, it will be According to the degree of complexity of the Flowspec entry, it will be
installed in *zebra* RIB. For more information about what is supported in the installed in *zebra* RIB. For more information about what is supported in the
@ -88,17 +88,17 @@ entry is split in several parts before being sent to *zebra*.
Policy Based Routing entities necessary to policy route the traffic in the Policy Based Routing entities necessary to policy route the traffic in the
underlying system, are received by *zebra*. Two filtering contexts will be underlying system, are received by *zebra*. Two filtering contexts will be
created or appended in ``Netfilter``: ``ipset`` and ``iptable`` context. The created or appended in ``Netfilter``: ``ipset`` and ``iptable`` context. The
former is used to define an IP filter based on multiple criterium. For instance, former is used to define an IP filter based on multiple criterium. For
an ipset ``net:net`` is based on two ip addresses, while ``net,port,net`` is instance, an ipset ``net:net`` is based on two ip addresses, while
based on two ip addresses and one port ( for ICMP, UDP, or TCP). The way the ``net,port,net`` is based on two ip addresses and one port (for ICMP, UDP, or
filtering is used ( for example, is src port or dst port used ?) is defined by TCP). The way the filtering is used (for example, is src port or dst port
the latter filtering context. ``iptable`` command will reference the ``ipset`` used?) is defined by the latter filtering context. ``iptable`` command will
context and will tell how to filter and what to do. In our case, a marker will reference the ``ipset`` context and will tell how to filter and what to do. In
be set to indicate ``iproute2`` where to forward the traffic to. Sometimes, for our case, a marker will be set to indicate ``iproute2`` where to forward the
dropping action, there is no need to add a marker; the ``iptable`` will tell to traffic to. Sometimes, for dropping action, there is no need to add a marker;
drop all packets matching the ``ipset`` entry. the ``iptable`` will tell to drop all packets matching the ``ipset`` entry.
Configuration guide Configuration Guide
------------------- -------------------
In order to configure an IPv4 Flowspec engine, use the following configuration. In order to configure an IPv4 Flowspec engine, use the following configuration.
@ -119,16 +119,16 @@ You can see Flowspec entries, by using one of the following show commands:
.. clicmd:: show bgp ipv4 flowspec [detail | A.B.C.D] .. clicmd:: show bgp ipv4 flowspec [detail | A.B.C.D]
Per-Interface Configuration Per-interface configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
One nice feature to use is the ability to apply Flowspec to a specific One nice feature to use is the ability to apply Flowspec to a specific
interface, instead of applying it to the whole machine. Despite the following interface, instead of applying it to the whole machine. Despite the following
IETF draft [Draft IETF IDR Flowspec Interface Set]_ is not implemented, it is IETF draft [Draft-IETF-IDR-Flowspec-Interface-Set]_ is not implemented, it is
possible to manually limit Flowspec application to some incoming interfaces. possible to manually limit Flowspec application to some incoming interfaces.
Actually, not using it can result to some unexpected behaviour like accounting Actually, not using it can result to some unexpected behaviour like accounting
twice the traffic, or slow down the traffic (filtering costs). To limit Flowspec twice the traffic, or slow down the traffic (filtering costs). To limit
to one specific interface, use the following command, under Flowspec to one specific interface, use the following command, under
`flowspec address-family` node. `flowspec address-family` node.
.. index:: [no] local-install <IFNAME | any> .. index:: [no] local-install <IFNAME | any>
@ -142,9 +142,9 @@ VRF redirection
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
Another nice feature to configure is the ability to redirect traffic to a Another nice feature to configure is the ability to redirect traffic to a
separate VRF. This feature does not go against the ability to configure Flowspec separate VRF. This feature does not go against the ability to configure
only on default VRF. Actually, when you receive incoming BGP flowspec entries on Flowspec only on default VRF. Actually, when you receive incoming BGP flowspec
that default VRF, you can redirect traffic to an other VRF. entries on that default VRF, you can redirect traffic to an other VRF.
As a reminder, BGP flowspec entries have a BGP extended community that contains As a reminder, BGP flowspec entries have a BGP extended community that contains
a Route Target. Finding out a local VRF based on Route Target consists in the a Route Target. Finding out a local VRF based on Route Target consists in the
@ -162,12 +162,12 @@ following:
.. clicmd:: [no] rt redirect import RTLIST... .. clicmd:: [no] rt redirect import RTLIST...
In order to illustrate, if the Route Target configured in the Flowspec entry is In order to illustrate, if the Route Target configured in the Flowspec entry is
E.F.G.H:II, then a BGP VRF instance with the same Route Target will be set set. ``E.F.G.H:II``, then a BGP VRF instance with the same Route Target will be set
That VRF will then be selected. The below full configuration example depicts how set. That VRF will then be selected. The below full configuration example
Route Targets are configured and how VRFs and cross VRF configuration is done. depicts how Route Targets are configured and how VRFs and cross VRF
Note that the VRF are mapped on Linux Network Namespaces. For data traffic to configuration is done. Note that the VRF are mapped on Linux Network
cross VRF boundaries, virtual ethernet interfaces are created with private IP Namespaces. For data traffic to cross VRF boundaries, virtual ethernet
adressing scheme. interfaces are created with private IP adressing scheme.
.. code-block:: frr .. code-block:: frr
@ -183,8 +183,8 @@ adressing scheme.
exit exit
exit exit
Flowspec Monitor and troubleshooting Flowspec monitoring & troubleshooting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can monitor policy-routing objects by using one of the following commands. You can monitor policy-routing objects by using one of the following commands.
Those command rely on the filtering contexts configured from BGP, and get the Those command rely on the filtering contexts configured from BGP, and get the
@ -194,38 +194,40 @@ those statistics are retrieved from ``Netfilter``.
.. index:: show pbr ipset IPSETNAME | iptable .. index:: show pbr ipset IPSETNAME | iptable
.. clicmd:: show pbr ipset IPSETNAME | iptable .. clicmd:: show pbr ipset IPSETNAME | iptable
``IPSETNAME`` is the policy routing object name created by ``ipset``. ``IPSETNAME`` is the policy routing object name created by ``ipset``. About
About rule contexts, it is possible to know which rule has been configured to rule contexts, it is possible to know which rule has been configured to
policy-route some specific traffic. The :clicmd:`show pbr iptable` command policy-route some specific traffic. The :clicmd:`show pbr iptable` command
displays for forwarded traffic, which table is used. Then it is easy to use that displays for forwarded traffic, which table is used. Then it is easy to use
table identifier to dump the routing table that the forwarded traffic will that table identifier to dump the routing table that the forwarded traffic will
match. match.
.. code-block:: frr .. code-block:: frr
show ip route table TABLEID .. index:: show ip route table TABLEID
.. clicmd:: show ip route table TABLEID
``TABLEID`` is the table number identifier referencing the non standard routing ``TABLEID`` is the table number identifier referencing the non standard
table used in this example. routing table used in this example.
You can troubleshoot Flowspec, or BGP policy based routing. For instance, if you
encounter some issues when decoding a Flowspec entry, you should enable
:clicmd:`debug bgp flowspec`.
.. index:: [no] debug bgp flowspec .. index:: [no] debug bgp flowspec
.. clicmd:: [no] debug bgp flowspec .. clicmd:: [no] debug bgp flowspec
If you fail to apply the flowspec entry into *zebra*, there should be some You can troubleshoot Flowspec, or BGP policy based routing. For instance, if
relationship with policy routing mechanism. Here, :clicmd:`debug bgp pbr error` you encounter some issues when decoding a Flowspec entry, you should enable
could help. :clicmd:`debug bgp flowspec`.
.. index:: [no] debug bgp pbr [error] .. index:: [no] debug bgp pbr [error]
.. clicmd:: [no] debug bgp pbr [error] .. clicmd:: [no] debug bgp pbr [error]
To get information about policy routing contexts created/removed, only use If you fail to apply the flowspec entry into *zebra*, there should be some
:clicmd:`debug bgp pbr` command. relationship with policy routing mechanism. Here,
:clicmd:`debug bgp pbr error` could help.
To get information about policy routing contexts created/removed, only use
:clicmd:`debug bgp pbr` command.
Ensuring that a Flowspec entry has been correctly installed and that incoming Ensuring that a Flowspec entry has been correctly installed and that incoming
traffic is policy-routed correctly can be checked like illustrated below. First traffic is policy-routed correctly can be checked as demonstrated below. First
of all, you must check whether the Flowspec entry has been installed or not. of all, you must check whether the Flowspec entry has been installed or not.
.. code-block:: frr .. code-block:: frr
@ -239,10 +241,10 @@ of all, you must check whether the Flowspec entry has been installed or not.
received for 18:41:37 received for 18:41:37
installed in PBR (match0x271ce00) installed in PBR (match0x271ce00)
This means that the Flowspec entry has been installed in a `iptable` This means that the Flowspec entry has been installed in an ``iptable`` named
named `match0x271ce00`. Once you have confirmation it is installed, you can ``match0x271ce00``. Once you have confirmation it is installed, you can check
check whether you find the associate entry by executing following command. You whether you find the associate entry by executing following command. You can
can also check whether incoming traffic has been matched by looking at counter also check whether incoming traffic has been matched by looking at counter
line. line.
.. code-block:: frr .. code-block:: frr
@ -254,15 +256,15 @@ line.
to 5.5.5.2:proto 17:50-90 (5) to 5.5.5.2:proto 17:50-90 (5)
pkts 1692918, bytes 157441374 pkts 1692918, bytes 157441374
As you can see, the entry is present. note that an `iptable` entry can be used As you can see, the entry is present. note that an ``iptable`` entry can be
to host several Flowspec entries. In order to know where the matching traffic is used to host several Flowspec entries. In order to know where the matching
redirected to, you have to look at the policy routing rules. The policy-routing traffic is redirected to, you have to look at the policy routing rules. The
is done by forwarding traffic to a routing table number. That routing table policy-routing is done by forwarding traffic to a routing table number. That
number is reached by using a `iptable`. The relationship between the routing routing table number is reached by using a ``iptable``. The relationship
table number and the incoming traffic is a MARKER that is set by the IPtable between the routing table number and the incoming traffic is a ``MARKER`` that
referencing the IPSet. In Flowspec case, `iptable` referencing the `ipset` is set by the IPtable referencing the IPSet. In Flowspec case, ``iptable``
context have the same name. So it is easy to know which routing table is used by referencing the ``ipset`` context have the same name. So it is easy to know
issuing following command: which routing table is used by issuing following command:
.. code-block:: frr .. code-block:: frr
@ -272,8 +274,8 @@ issuing following command:
table 257, fwmark 257 table 257, fwmark 257
... ...
As you can see, by using following Linux commands, the MARKER `0x101` is present As you can see, by using following Linux commands, the MARKER ``0x101`` is
in both ``iptable`` and ``ip rule`` contexts. present in both ``iptable`` and ``ip rule`` contexts.
.. code-block:: shell .. code-block:: shell
@ -294,15 +296,15 @@ This allows us to see where the traffic is forwarded to.
.. _flowspec-known-issues: .. _flowspec-known-issues:
Limitations / Known issues Limitations / Known Issues
-------------------------- --------------------------
As you can see, Flowspec is rich and can be very complex. As you can see, Flowspec is rich and can be very complex. As of today, not all
As of today, not all Flowspec rules will be able to be converted into Policy Flowspec rules will be able to be converted into Policy Based Routing actions.
Based Routing actions.
- The ``Netfilter`` driver is not integrated into FRR yet. Not having this piece - The ``Netfilter`` driver is not integrated into FRR yet. Not having this
of code prevents from injecting flowspec entries into the underlying system. piece of code prevents from injecting flowspec entries into the underlying
system.
- There are some limitations around filtering contexts - There are some limitations around filtering contexts
@ -329,7 +331,8 @@ There are some other known issues:
It is recommended to configure Quality of Service if needed, more globally on It is recommended to configure Quality of Service if needed, more globally on
a per interface basis. a per interface basis.
- upon crash or unknown event, *zebra* may not have time to flush pbr contexts. - Upon an unexpected crash or other event, *zebra* may not have time to flush
PBR contexts.
That is to say ``ipset``, ``iptable`` and ``ip rule`` contexts. This is also a That is to say ``ipset``, ``iptable`` and ``ip rule`` contexts. This is also a
consequence due to the fact that ip rule / ipset / iptables are not discovered consequence due to the fact that ip rule / ipset / iptables are not discovered
@ -343,6 +346,6 @@ inside FRRouting.
[Presentation]_ [Presentation]_
.. [Draft IETF IDR Flowspec redirect IP] <https://tools.ietf.org/id/draft-ietf-idr-flowspec-redirect-ip-02.txt> .. [Draft-IETF-IDR-Flowspec-redirect-IP] <https://tools.ietf.org/id/draft-ietf-idr-flowspec-redirect-ip-02.txt>
.. [Draft IETF IDR Flowspec Interface Set] <https://tools.ietf.org/id/draft-ietf-idr-flowspec-interfaceset-03.txt> .. [Draft-IETF-IDR-Flowspec-Interface-Set] <https://tools.ietf.org/id/draft-ietf-idr-flowspec-interfaceset-03.txt>
.. [Presentation] <https://docs.google.com/presentation/d/1ekQygUAG5yvQ3wWUyrw4Wcag0LgmbW1kV02IWcU4iUg/edit#slide=id.g378f0e1b5e_1_44> .. [Presentation] <https://docs.google.com/presentation/d/1ekQygUAG5yvQ3wWUyrw4Wcag0LgmbW1kV02IWcU4iUg/edit#slide=id.g378f0e1b5e_1_44>