Repository navigation
Actions Reference
Complete reference for all FlowSpec actions
RFC 8955 (IPv4, obsoletes RFC 5575) / RFC 8956 (IPv6) - Extended Community-based actions
- Overview
- Discard
- Rate-Limit
- Redirect to VRF
- Mark (DSCP)
- Community Tagging
- Combining Actions
- Extended Community Format
- Router Support
- Best Practices
- Common Patterns
FlowSpec actions define what to do with matched traffic.
Basic structure:
announce flow route { match { <conditions> } then { <action>; } }A program writes the whole command on one line, since ExaBGP reads one command per line. In the configuration file the same match and then blocks go in a flow { route <name> { ... } } section.
Actions are implemented as BGP Extended Communities sent with the FlowSpec route.
Available actions:
| Action | Extended Community Type | Purpose |
|---|---|---|
discard |
traffic-rate (0x8006) with a rate of 0 | Drop packets |
rate-limit <n> |
traffic-rate (0x8006), bytes per second | Limit bandwidth |
rate-limit <n> packets |
traffic-rate-packets (0x800C) | Limit packets per second |
redirect |
redirect (0x8008, or 0x8208 for a four octet AS or <asn>L:<n>) |
Redirect to VRF |
mark |
traffic-marking (0x8009) | Remark DSCP |
action sample|terminal|sample-terminal |
traffic-action (0x8007) | Sample the traffic, stop at this rule, or both |
accept |
none | No action: the traffic is accepted |
community, large-community, extended-community
|
Standard/Large/Extended | Tag the route |
The redirect-to-IP forms (redirect <ip>, copy, redirect-to-nexthop and the -simpson spellings) are described under Redirect to an IP Address.
Drop matching packets completely
then {
discard;
}Traffic-rate: 0
Matching packets are immediately dropped at the router.
Characteristics:
- ✅ Most common action for DDoS mitigation
- ✅ Hardware-based (wire-speed performance)
- ✅ Zero bandwidth consumption for dropped packets
⚠️ No logging of dropped packets (router-dependent)⚠️ Legitimate traffic may be affected if rule too broad
announce flow route { match { destination 100.10.0.100/32; destination-port =80; protocol =tcp; tcp-flags [ syn ]; } then { discard; } }Result: All TCP SYN packets to 100.10.0.100:80 are dropped.
announce flow route { match { source-port =53; protocol =udp; packet-length >512; } then { discard; } }Result: Large DNS responses (likely amplification) are dropped.
announce flow route { match { protocol =icmp; } then { discard; } }Result: All ICMP packets dropped (use during ICMP flood).
- DDoS mitigation - Block attack traffic completely
- Security blocking - Block known malicious sources
- Protocol blocking - Block entire protocols during attacks
- Emergency response - Stop attack immediately
- Be specific - Avoid blocking legitimate traffic
- Monitor impact - Check if rule affects real users
- Auto-expire - Withdraw rule when attack ends
- Log announcements - Track what you're blocking
Example with logging:
import logging
logging.info(f"[DISCARD] Blocking {source_ip} to port {port}")
# send() writes the command and reads ExaBGP's answer, see Writing-API-Programs
send(f"announce flow route {{ match {{ source {source_ip}/32; }} then {{ discard; }} }}")Limit bandwidth for matching traffic
then {
rate-limit <bytes-per-second>;
# or, as traffic-rate-packets
rate-limit <packets-per-second> packets;
}Traffic-rate: <rate-in-bytes-per-second>
Traffic-rate-packets: <rate-in-packets-per-second> (with "packets")
ExaBGP warns about a rate below 9600 bytes per second (other than 0) and caps a rate above 1,000,000,000,000 bytes per second.
Matching packets are rate-limited to specified bandwidth.
⚠️ Implementation-Specific BehaviorRFC 5575/8955 do NOT specify whether rate-limit applies per-flow or as aggregate across all matching traffic. This is router implementation-specific:
- Some vendors apply rate-limit per individual flow (per source IP)
- Some vendors apply rate-limit as aggregate across all matching traffic
- Consult your router vendor's documentation for exact behavior
ExaBGP signals the rate-limit value to the router via BGP - the router enforces it according to its own implementation.
Characteristics:
- ✅ Throttle traffic instead of dropping completely
- ✅ Allows some legitimate traffic through
- ✅ Hardware-based policing
⚠️ Excess traffic is dropped⚠️ Behavior (per-flow vs aggregate) depends on router vendor
⚠️ IMPORTANT: Vendor Implementation DifferencesRFC 5575 specifies rate-limit values in bytes per second.
However, router vendors implement this differently:
- Juniper: Converts bytes/sec to bits/sec internally (multiplies by 8)
- Cisco: May interpret values differently depending on platform
- Other vendors: Vary in implementation
ExaBGP follows RFC 5575 and sends values as bytes per second. Your router interprets these values according to its vendor-specific implementation.
Critical: Always test rate-limit behavior on your specific router platform. The same ExaBGP value may result in different actual rates on different vendor equipment.
RFC 5575 Compliant (Bytes per Second):
# 1 MB/sec (8 Mbps) = 1,000,000 bytes/sec
rate-limit 1000000
# 10 MB/sec (80 Mbps) = 10,000,000 bytes/sec
rate-limit 10000000
# 100 MB/sec (800 Mbps) = 100,000,000 bytes/sec
rate-limit 100000000
# 1 GB/sec (8 Gbps) = 1,000,000,000 bytes/sec
rate-limit 1000000000Understanding the Values:
ExaBGP value (bytes/sec) → Router interprets per vendor implementation
RFC 5575: bytes per second
Juniper: converts to bits per second (×8)
Cisco: depends on platform
Conversion Reference:
- 1 Mbps (megabit/sec) = 125,000 bytes/sec
- 10 Mbps = 1,250,000 bytes/sec
- 100 Mbps = 12,500,000 bytes/sec
- 1 Gbps = 125,000,000 bytes/sec
# 10 MB/s (~80 Mbps)
announce flow route { match { destination-port =53; protocol =udp; } then { rate-limit 10000000; } }Result: DNS traffic limited to 10 MB/s (~80 Mbps).
# 5 MB/s (~40 Mbps)
announce flow route { match { destination-port =80; protocol =tcp; tcp-flags [ syn ]; } then { rate-limit 5000000; } }Result: TCP SYN packets to port 80 limited to 5 MB/s (~40 Mbps).
# Echo request
# 1 MB/s (~8 Mbps)
announce flow route { match { protocol =icmp; icmp-type =8; } then { rate-limit 1000000; } }Result: ICMP echo requests limited to 1 MB/s (~8 Mbps).
# Attacker network
# 1 MB/s (~8 Mbps)
announce flow route { match { source 203.0.113.0/24; } then { rate-limit 1000000; } }Result: All traffic from 203.0.113.0/24 limited to 1 MB/s (~8 Mbps).
Start with rate-limiting, escalate to discard if needed:
# Step 1: Detect attack, rate-limit
# 10 MB/s (~80 Mbps)
announce flow route { match { source 10.0.0.0/8; destination-port =80; } then { rate-limit 10000000; } }
# Step 2: If still too much traffic, tighten rate
# 1 MB/s (~8 Mbps)
announce flow route { match { source 10.0.0.0/8; destination-port =80; } then { rate-limit 1000000; } }
# Step 3: If attack continues, block completely
announce flow route { match { source 10.0.0.0/8; destination-port =80; } then { discard; } }- Proportional response - Limit before blocking
- Soft mitigation - Allow some legitimate traffic
- Protocol throttling - Slow down entire protocols
- Testing - Validate rule before full block
- Start conservative - Higher rate first, lower if needed
- Monitor bandwidth - Check actual traffic reduction
- Per-service rates - Different limits for different services
- Combine with discard - Escalate if rate-limit insufficient
Extreme Networks:
- Rate values must be multiples of 22 Kbps (22,000 bytes/sec)
- Invalid rates may be rounded or rejected
Example for Extreme:
# Bad: Not a multiple of 22 Kbps
rate-limit 1000000 # May be rejected
# Good: Multiple of 22 Kbps
rate-limit 1100000 # 1.1 MB/s (~8.8 Mbps) (50 × 22 KB/s)Redirect matching traffic to a VRF (Virtual Routing and Forwarding instance)
then {
redirect <route-target>;
}Redirect: <route-target>
Matching packets are redirected to specified VRF instead of normal routing.
Characteristics:
- ✅ Traffic sent to separate routing instance
- ✅ Enables scrubbing center analysis
- ✅ Allows inspection without blocking
⚠️ Requires VRF configuration on router⚠️ Complexity increases
# ASN:Value format
redirect 65001:100
# IPv6-Address-Specific route-target (RFC 8956 section 6.1), 6.0.0 and later
redirect [2001:db8::1]:100The IPv6 form is carried in the IPv6 extended community attribute (25) as type 0x000d, and the
number is 16 bits. An IPv4 address with a number, redirect 192.168.1.1:100, is refused in the
then block. The IPv4 address route target of RFC 8955 section 7.4 (type 0x8108) is written as an
extended community instead, extended-community [ redirect:192.168.1.1:100 ], and an AS above
65535 gives the four octet AS form (type 0x8208), whether written redirect 4200000000:100 or
extended-community [ redirect:4200000000:100 ]. A trailing L asks for that form with a
smaller AS: redirect 65001L:100 sends 0x8208 where redirect 65001:100 sends 0x8008. ExaBGP
decodes all three types and shows them in the redirect:<global>:<number> text the
configuration reads back, a 0x8208 with an AS below 65536 as redirect:65001L:100 (RFC 8955
7.4). Before 6.0.0 it was shown without the L, and read back as 0x8008.
A bare address, redirect 192.168.1.1 or redirect [2001:db8::1], redirects to that next-hop,
not to a VRF. In 6.0.0 it uses draft-ietf-idr-flowspec-redirect-ip, which replaced the earlier
Simpson draft: the address travels in an extended community (type 0x010C in the extended
community attribute for IPv4, 0x000C in the IPv6 one), and the next hop of MP_REACH_NLRI stays
empty, as RFC 8955 section 4 requires.
| Written | 6.0.0 on the wire |
|---|---|
redirect <ip>, redirect-to-nexthop <ip>, redirect-to-nexthop-ietf <ip>
|
IETF redirect-to-IP community, no MP_REACH next hop |
copy <ip> |
The same community with the copy bit set |
redirect-simpson <ip>, copy-simpson <ip>
|
The Simpson form: the address in the MP_REACH next hop, and a flag community |
redirect-to-nexthop, redirect-to-nexthop-simpson
|
The Simpson flag, redirecting to the route's own next-hop
|
Use the -simpson spellings only for a peer which still expects the old draft. They take an
address only: redirect <asn>:<nn> and redirect [<ipv6>]:<nn> redirect to a VRF, which the
Simpson draft never covered, so there is no -simpson form of them.
The communities can also be written directly, which is how they come back from the API:
extended-community [ redirect-to-nexthop-ietf 192.0.2.1 copy-to-nexthop-ietf 192.0.2.2 ].
# Attacked network
# Scrubbing VRF route-target
announce flow route { match { destination 100.10.0.0/24; } then { redirect 65001:999; } }Workflow:
- Suspicious traffic matched
- Redirected to VRF with route-target 65001:999
- VRF routes traffic to scrubbing appliance
- Clean traffic returned to production network
# Suspicious network
# Inspection VRF
announce flow route { match { source 203.0.113.0/24; } then { redirect 65001:100; } }Use case: Send traffic from suspicious sources to IDS/IPS for deep inspection.
┌─────────────────┐
│ Attack Traffic │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Edge Router │ FlowSpec: redirect 65001:999
└────────┬────────┘
│
▼
┌─────────────────┐
│ Scrubbing VRF │ Route-target 65001:999
│ (VRF 999) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Scrubbing │ Analyze & clean
│ Appliance │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Clean Traffic │ Return to production
│ Back to Network │
└─────────────────┘
- Scrubbing centers - Send attack traffic for cleaning
- IDS/IPS inspection - Deep packet inspection
- Quarantine networks - Isolate suspicious traffic
- Logging/analysis - Capture attack packets
- Pre-configure VRFs - VRF must exist before redirect
- Test redirect path - Verify traffic reaches scrubbing
- Return path - Ensure clean traffic gets back
- Monitor VRF - Check scrubbing VRF capacity
Remark DSCP field for QoS processing
then {
mark <dscp-value>;
}Traffic-marking: <dscp-value>
Matching packets have their DSCP field remarked to specified value.
Characteristics:
- ✅ Packets marked for downstream QoS
- ✅ Can be combined with other policies
⚠️ Doesn't drop or rate-limit traffic⚠️ Requires downstream QoS config
| DSCP | Name | Typical Use |
|---|---|---|
| 0 | BE (Best Effort) | Default |
| 8 | CS1 | Low priority |
| 10 | AF11 | Bulk data |
| 12 | AF12 | Bulk data |
| 14 | AF13 | Bulk data |
| 26 | AF31 | Signaling |
| 34 | AF41 | Video |
| 46 | EF | Voice |
# Attack source
# CS1 (low priority)
announce flow route { match { source 10.0.0.0/8; } then { mark 8; } }Result: Traffic from 10.0.0.0/8 marked as low priority for QoS.
# Large SYN packets (suspicious)
# Best effort (lowest priority)
announce flow route { match { destination-port =80; protocol =tcp; tcp-flags [ syn ]; packet-length >1000; } then { mark 0; } }Result: Large SYN packets deprioritized by downstream QoS.
- QoS integration - Mark for downstream handling
- Prioritization - Deprioritize attack traffic
- Traffic classification - Identify specific flows
- Policy enforcement - Apply downstream policies
- Downstream QoS required - Marking alone doesn't rate-limit
- Consistent DSCP values - Align with existing QoS policy
- Combine with rate-limit - Mark + rate-limit for best control
- Monitor effectiveness - Verify QoS policies work
Tag FlowSpec routes with BGP communities
then {
community [ <community> ];
}FlowSpec route itself is tagged with communities for downstream policy decisions.
Characteristics:
- ✅ Allows policy-based filtering
- ✅ Enables selective route acceptance
⚠️ Doesn't affect matched traffic directly⚠️ Requires community-based policies
# Mark as DDoS mitigation
announce flow route { match { source 10.0.0.0/8; } then { discard; community [ 65001:666 ]; } }Downstream routers can:
- Accept FlowSpec routes with community 65001:666
- Reject FlowSpec routes without this community
- Apply different policies based on community
# SYN flood
# SYN flood tag
announce flow route { match { tcp-flags [ syn ]; } then { discard; community [ 65001:100 ]; } }
# UDP flood
# UDP flood tag
announce flow route { match { protocol =udp; packet-length >1000; } then { discard; community [ 65001:200 ]; } }Use case: Track/filter FlowSpec rules by attack type.
- Route filtering - Control FlowSpec propagation
- Policy decisions - Apply different handling
- Tracking - Identify rule types
- Logging - Categorize mitigation actions
Multiple actions can be combined in a single rule.
# 10 MB/s (~80 Mbps)
# Mark as low priority
announce flow route { match { source 10.0.0.0/8; destination-port =80; } then { rate-limit 10000000; mark 8; } }Result: Traffic rate-limited AND marked for downstream QoS.
# Tag rule
announce flow route { match { source 203.0.113.0/24; } then { discard; community [ 65001:666 ]; } }Result: Traffic discarded, FlowSpec route tagged.
# Send to scrubbing VRF
# Tag as scrubbed traffic
announce flow route { match { destination 100.10.0.0/24; } then { redirect 65001:999; community [ 65001:100 ]; } }Result: Traffic redirected to scrubbing, rule tagged for tracking.
FlowSpec actions are BGP Extended Communities in the FlowSpec route.
Type: 0x8006 (traffic-rate)
Value: <rate-in-bytes-per-second>
Type: 0x8006 (traffic-rate)
Value: 0 (no traffic allowed)
Type: 0x8007 (traffic-action)
Value: the sample and terminal bits
Type: 0x8008 (redirect, two octet AS), 0x8108 (IPv4 address), 0x8208 (four octet AS)
Value: <route-target>
Type: 0x8009 (traffic-marking)
Value: <dscp-value>
Action support varies by router vendor/model.
- ✅ Discard
- ✅ Rate-limit
- ✅ Redirect
⚠️ Mark (model-dependent)
- ✅ Discard
- ✅ Rate-limit
- ✅ Redirect
- ✅ Mark
- ✅ Discard
- ✅ Rate-limit
⚠️ Redirect (limited)⚠️ Mark (limited)
- ✅ Discard
- ✅ Rate-limit
- ✅ Redirect
- ✅ Mark
Check router documentation for specific action support.
| Situation | Recommended Action |
|---|---|
| Known attack, high confidence | discard |
| Suspected attack, testing | rate-limit |
| Need analysis | redirect |
| QoS integration | mark |
| Gradual escalation |
rate-limit → discard
|
import logging
def announce_with_logging(rule, action):
logging.info(f"[FLOWSPEC] Action={action} Rule={rule}")
# send() writes the command and reads ExaBGP's answer, see Writing-API-Programs
if not send(rule):
logging.error(f"[FLOWSPEC] ExaBGP refused Rule={rule}")
rule = "announce flow route { match { source 10.0.0.0/8; } then { discard; } }"
announce_with_logging(rule, "discard")import time
expiry = {} # rule -> time at which it is withdrawn
def announce_for(rule, timeout=300):
"""Announce a rule (the text after "announce ") and withdraw it after timeout seconds"""
if send(f"announce {rule}"): # send() as in Writing-API-Programs
expiry[rule] = time.time() + timeout
def withdraw_expired():
"""Call this regularly from the program's main loop"""
now = time.time()
for rule, when in list(expiry.items()):
if when <= now and send(f"withdraw {rule}"):
del expiry[rule]
logging.info(f"[FLOWSPEC] Auto-withdrew {rule}")
announce_for("flow route { match { source 10.0.0.0/8; } then { discard; } }", 300)Every command goes through the same send(), from the main loop: a second thread writing commands and reading answers at the same time would take answers meant for the other.
Track:
- Bandwidth before/after rule
- Number of packets matched
- False positives (legitimate traffic blocked)
- Attack duration
Tools:
- Router packet counters
- NetFlow/sFlow analysis
- SNMP monitoring
Escalation ladder:
# Level 1: Rate-limit (warning)
rate-limit 50000000 # 50 MB/s (~400 Mbps)
# Level 2: Tighter rate-limit
rate-limit 10000000 # 10 MB/s (~80 Mbps)
# Level 3: Very tight rate-limit
rate-limit 1000000 # 1 MB/s (~8 Mbps)
# Level 4: Block completely
discardannounce flow route { match { source 10.0.0.0/8; destination-port =80; tcp-flags [ syn ]; } then { discard; } }# 10 MB/s (~80 Mbps)
announce flow route { match { destination 100.10.0.100/32; destination-port =53; protocol =udp; } then { rate-limit 10000000; } }# Scrubbing VRF
announce flow route { match { destination 100.10.0.0/24; } then { redirect 65001:999; } }# Low priority
announce flow route { match { source 10.0.0.0/8; } then { mark 8; } }# Best effort
announce flow route { match { protocol =udp; packet-length >1000; } then { rate-limit 10000000; mark 0; } }- FlowSpec Overview - Introduction to FlowSpec
- Match Conditions Reference - What traffic to match
- DDoS Mitigation Guide - Complete workflow
- Text API Reference - FlowSpec commands
- API Commands - Command reference
- Quick Start - First FlowSpec rule
- Production Best Practices - Production deployment
Ready to implement DDoS mitigation? See DDoS Mitigation Guide →
Getting Started
Configuration
- Configuration Syntax
- Neighbor Configuration
- Directives A-Z
- Syntax Reference
- Templates
- Environment Variables
- Process Configuration
API
- API Overview
- Text API Reference
- JSON API Reference
- API Commands
- Writing API Programs
- Error Handling
- Production Best Practices
Address Families
- Overview
- IPv4 Unicast
- IPv6 Unicast
- FlowSpec
- EVPN
- L3VPN
- BGP-LS
- VPLS
- SRv6 / MUP
- Multicast
- RT Constraint
Features
Use Cases
Tools
Operations
Reference
- Architecture
- Design
- Attribute Reference
- Command Reference
- BGP State Machine
- Capabilities
- Communities
- Examples Index
- Glossary
- RFC Support
Integration
Migration
Community
External