The Contribution
FRRouting (FRR) is the most widely deployed open-source routing suite in production networks. Its FlowSpec implementation lets routers receive BGP FlowSpec rules from an external controller and install them as Netfilter rules for surgical traffic filtering. The existing documentation covered protocol design, configuration syntax, and troubleshooting, but it lacked worked examples for the most common real-world use case: DDoS mitigation.
We submitted a pull request adding a new "DDoS Mitigation Examples" section to the FlowSpec user guide. It was reviewed and merged on June 29, 2026. The addition covers three mitigation patterns with full router configuration, CLI output, and verification commands.
What the Examples Cover
The new documentation section walks through three scenarios that network operators encounter regularly during DDoS attacks. Each example shows what the FRR router receives, what Netfilter state it creates, and how to verify that rules are active.
1. Dropping UDP Amplification Traffic
UDP amplification attacks (DNS, NTP, memcached, CLDAP) remain the most common volumetric DDoS vector. The example shows a FlowSpec rule that matches all UDP traffic destined for a victim prefix and sets the traffic rate to zero, which FRR translates into an iptables drop rule.
router# show bgp ipv4 flowspec detail BGP flowspec entry: (flags 0x418) Destination Address 198.51.100.0/24 IP Protocol = 17 FS:rate 0.000000 received for 00:05:12 installed in PBR (match0x1a2b3c)
The example then shows the corresponding Netfilter state:
router# show pbr ipset match0x1a2b3c
IPset match0x1a2b3c type net
to 198.51.100.0/24:proto 17 (1)
pkts 0, bytes 0
router# show pbr iptable
IPtable match0x1a2b3c action drop (1)
pkts 0, bytes 0
2. Rate-Limiting TCP SYN Floods
SYN floods exhaust connection-state resources. Unlike amplification attacks, you often cannot drop all TCP traffic to the target. The example demonstrates a FlowSpec rule that matches TCP traffic with the SYN flag set and applies a rate-limit action rather than a full discard.
router# show bgp ipv4 flowspec detail BGP flowspec entry: (flags 0x418) Destination Address 198.51.100.10/32 IP Protocol = 6 TCP Flags = 0x02 FS:rate 1000000.000000 received for 00:02:47 installed in PBR (match0x4d5e6f)
The documentation notes that FRR installs rate-limit rules as redirect actions, where traffic exceeding the specified byte rate is forwarded to a routing table that may blackhole the excess. This is an important operational detail that was not previously documented.
3. Source-Based Blocking
When the attack source is identified, the controller can advertise a FlowSpec rule matching that source prefix regardless of protocol or destination. The example shows a rule that drops all traffic from a /24 source range:
router# show bgp ipv4 flowspec detail BGP flowspec entry: (flags 0x418) Source Address 203.0.113.0/24 FS:rate 0.000000 received for 00:08:33 installed in PBR (match0x7a8b9c)
Router Configuration
The examples include a minimal bgpd.conf showing how to configure an FRR router as a FlowSpec client. The key elements are the FlowSpec address family activation and the local-install directive that restricts rule installation to a specific interface:
router bgp 65001 bgp router-id 192.0.2.1 neighbor 192.0.2.100 remote-as 65100 neighbor 192.0.2.100 description FlowSpec-Controller ! address-family ipv4 flowspec neighbor 192.0.2.100 activate local-install eth0 exit-address-family
The local-install eth0 directive is critical. Without it, FlowSpec rules apply globally, which on multi-interface routers can cause traffic to be filtered or accounted for twice.
Verification and Operational Notes
The contribution includes a verification section covering the commands operators need during an active mitigation:
show bgp ipv4 flowspecandshow bgp ipv4 flowspec detailto inspect received FlowSpec NLRIshow pbr ipsetandshow pbr iptableto verify Netfilter rule installationshow ip route table TABLEIDto inspect routing tables used by redirect rulesdebug bgp flowspecanddebug bgp pbr errorfor troubleshooting
The operational notes section covers several edge cases that are important in production but were not previously documented:
- FRR is a FlowSpec client only. Rules cannot be originated from the CLI; they must come from an external BGP speaker.
- If the system is missing
ipsetoriptablesutilities, rule installation fails silently. Thedebug bgp pbr errorcommand surfaces these failures. - If FRR terminates unexpectedly, stale Netfilter entries remain and must be cleaned up manually.
- Complex match criteria combining multiple port ranges may not be installable due to Netfilter limitations.
Why We Contributed This
FlowSpec is one of the primary mechanisms Flowtriq uses for upstream DDoS mitigation. When Flowtriq's escalation policy determines that an attack needs to be filtered at the router level, it advertises FlowSpec rules via ExaBGP, GoBGP, or BIRD 2. FRR receives those rules and installs them into Netfilter.
We kept running into the same gap: operators understood what FlowSpec was in theory, but the existing FRR documentation did not show what it looks like in practice during a DDoS attack. The verification commands existed but were not tied to concrete scenarios. Operators had to piece together the workflow from multiple sources.
The contribution fills that gap. All example addresses use RFC 5737 documentation ranges, no vendor-specific products are mentioned, and the content is focused purely on how FRR handles FlowSpec rules as a client. It is a documentation improvement that benefits anyone using FRR for DDoS mitigation, regardless of what controller they are using upstream.
The full documentation is live in the FRRouting docs under BGP FlowSpec > DDoS Mitigation Examples. If you are running FRR as your FlowSpec client, it is worth reading through the operational notes section in particular.
Flowtriq automates FlowSpec rule deployment. Detect attacks at 1-second granularity, classify the vector, and push FlowSpec filters to your FRR routers automatically. $9.99/node/month, 14-day free trial. Start your trial.