BGP Flowspec Action

A BGP Action is an action configured with a type of "bgp-flowspec-v4" for IPv4, and "bgp-flowspec-v6" for IPv6. When this action is started, one or more BGP Flowspec announcements are made based on its configuration, and withdrawn when the action is stopped.

warning

FlowSpec capabilities are heavily dependent on your router. When deploying BGP FlowSpec actions, be aware that not all matcher or filter actions specified by Director may be supported by your router. Refer to your router manufacturer's documentation for the specifics on its support for FlowSpec.

Flowspec Matchers

[actions.BgpFlowspecExample]
type = "bgp-flowspec-v4"

##### Flowspec matchers
# The following parameters set what packets this Flowspec rule will match against.

# This optional key uses 'Destination' values
# Note, if destination resolves to multiple prefixes, this action will result in
# multiple announcements
destination = "detected"

# For "bgp-flowspec-v6" only, use this destination offset for
# the Flowspec matcher
# Optional, default 0
# destination-offset = 0

# If present, any destination prefix longer than this value will be announced
# with this mask length.
# WARNING - this may not respect zone boundaries, it is your responsibility to
# make sure this feature is applied properly.
# Optional
# # Must be <=32 for "bgp-flowspec-v4", and <=128 for "bgp-flowspec-v6"
aggregate = 24

# Match a source network.
source = "198.51.100.0/24"
# Must match the type of the action, below is valid only for "bgp-flowspec-v6"
# source = "2001:db8::/64"

# For "bgp-flowspec-v6" only, use this source offset for
# the Flowspec matcher
# Optional, default 0
# source-offset = 0

# The following  optional keys use 'BGP Flowspec Numeric' values:

# IPv4 Protocol / IPv6 Upper-Layer Protocol
protocol = "==6 ==17" # Match TCP or UDP

# Source OR Dest port
port = "> 100 & < 200" # Ports between 100 & 200

# Destination/Source Port
destination-port = "!= 42"
source-port = "< 7"

# ICMP Type or Code
# NB: Types are different between ICMPv4 and ICMPv6, make sure you are
# specifying correctly based on the action's address family
icmp-type = "== 8"
icmp-code = "== 0"

# Packet length - excluding layer 2 header
packet-length = "> 1500"

# Differentiated Services Code Point
dscp = "!= 0"

# IPv6 flow label
# Only used for "bgp-flowspec-v6"
# flow-label = "== 7"

# This optional key uses 'BGP Flowspec TCP Flags' values
tcp-flags = "=SYN+ACK & !=PSH"

# This optional key uses 'BGP Flowspec Fragment' values
fragment = "first-fragment+is-fragment"

Flowspec Matcher Keys

This set of optional keys controls what traffic will be matched by the BGP Flowspec Announcement.

• destination: The set of prefixes that will be announced by this BGP Flowspec Action. The set of acceptable values maps to the destination special data type. It can be set to match what triggered the workflow (potentially producing multiple prefixes) or set to a static value. If multiple prefixes are produced by the destination value, this will result in multiple announcements. If a static value, this must match the address family of the action type (i.e. IPv4 for "bgp-flowspec-v4" and IPv6 for "bgp-flowspec-v6").
• destination-offset: An optional key, defaulting to 0, that specifies a destination offset for the matcher if destination is an IPv6 address. Valid only for "bgp-flowspec-v6".
• aggregate: An optional key, that if configured, uses this value to mask announcements for longer prefixes. For example, if there was a single detected IPv4 /32 host, and aggregate was set to /24, it would announce the /24 that encloses that /32.

warning

Depending on the aggregate value, the derived announcement could affect traffic to a Zone other than the one associated with this action's workflow. You are responsible for deconflicting cases where a Zone may have routing that is affected by these overlaps.

• source: An optional key, that if configured, attempts to match the source network. If specified, this must match the address family of the action type (i.e. IPv4 for "bgp-flowspec-v4" and IPv6 for "bgp-flowspec-v6").
• source-offset: An optional key, defaulting to 0, that specifies a source offset for the matcher if destination is an IPv6 address. Valid only for "bgp-flowspec-v6".
• The following optional keys use BGP Flowspec Numeric values:
  • protocol: Matches the protocol of the packet. This will be the IPv4 Protocol field, or the topmost IPv6 Next Header field.
  • port: Matches the Source or Destination port of the transport layer of the packets. This will only work for TCP or UDP packets (protocol 6 or 17, respectively), and if the packet is fragmented, against the first fragment.
  • destination-port, source-port: Identical to port, except specific to the Destination or Source port.
  • icmp-type: Matches the ICMP type header values for ICMP. As the type values are different between the two address families (ICMPv4 vs ICMPv6), these values should be reviewed carefully.
  • `icmp-code: Matches the ICMP code header values for ICMP. As the code values can be different between the two address families (ICMPv4 vs ICMPv6), these values should be reviewed carefully.
  • packet-length: Matches against the length of the packet. This excludes the layer 2 header.
  • dscp: Matches against the Differentiated Services Code Point in the IP header (this is the Traffic Class header in IPv6).
  • flow-label: Matches against the IPv6 flow label header value. This is only valid for "bgp-flowspec-v6".
• tcp-flags: This optional key uses BGP Flowspec TCP Flag values to match against TCP flags in the packets.
• fragment: This optional key uses BGP Flowspec Fragment values to match against fragmented packets.

Flowspec Filtering Actions

##### Flowspec filtering actions
# The following parameters set how matched packets will be treated.

# Rate limit on bytes per second.
traffic-rate-bytes = "1 k"
# Low-order 16 bits of this will be sent with the traffic rate limit
# Optional, default 0
traffic-rate-bytes-as = 64496

# Rate limit on packets per second
traffic-rate-packets = "1 k"
# Low-order 16 bits of this will be sent with the traffic rate limit
# Optional, default 0
traffic-rate-packets-as = 64496

# Setting either of these will add a `traffic-action` community.
# Optional, default false
traffic-action-terminal = true
traffic-action-sample = true

# Add an rt-redirect community.
# Redirect to route target.
# Route target is global identifier followed by local identifier
# Optional
rt-redirect-asn = "64496:123"

# Add an rt-redirect community.
# Redirect to route target based on IP address.
# Optional
rt-redirect = {ip = "192.0.2.100", local=123}
# If using "bgp-flowspec-v6", IP must be IPv6
# rt-redirect = {ip = "2001:db8::F00", local=123}

# Redirect-to-IP Draft support
# Community 0x010c / 0x000c
# Per draft-ietf-idr-flowspec-redirect-ip-02
# Note that we do -not- support draft-simpson-idr-flowspec-redirect (0x0800)
# Optional
ip-redirect-legacy-ietf = { ip = "198.51.100.7", copy=false }
# If using "bgp-flowspec-v6", IP must be IPv6
# ip-redirect-legacy-ietf = { ip = "2001:db8::1", copy=true }

# Set DSCP bits
# Optional
traffic-marking = 1

# Zero or more communities to add to the announcement.
# Optional.
communities = [
    "NO_EXPORT",
    "64496:123",
]

# Zero or more large communities (RFC 8092) to add to the announcement.
# Optional
large-communities = [
    "123:456:789",
]

# Set the AS Path of the announcement
# Optional
as-path = [64496, 64496, 64496]

# Sets BGP LOCAL_PREF attribute. 
# Optional
local-pref = 100

# Sets BGP MULTI_EXIT_DISC attribute - multiple exit discriminator.
# Optional
multi-exit-disc = 10

# Sets AIGP attribute (RFC 7311)
# Optional
aigp-metric = 10

# Just log, don't actually announce anything
# Optional, default is false
no-op = true

Flowspec Filtering Action Keys

This set of optional keys specifies how traffic matching the defined matcher logic will be handled.

• traffic-rate-bytes: An optional unit value that will limit matched traffic to this rate, in bytes per second.

info

This value is bytes, not bits, so please double check that this value matches your intended rate limits.

• traffic-rate-bytes-as: An optional value, defaulting to 0, that if set along with traffic-rate-bytes, will have its lower 16 bits sent as AS information as described in RFC 8955.
• traffic-rate-packets: An optional unit value that will limit matched traffic to this rate, in packets per second.
• traffic-rate-packets-as: An optional value, defaulting to 0, that if set along with traffic-rate-packets, will have its lower 16 bits sent as AS information as described in RFC 8955.
• traffic-action-terminal, traffic-action-sample: Optional values, defaulting to false, that when set true will add their respective traffic-action communities as identified in RFC 8955.
• rt-redirect-asn: An optional value, if set allows redirection to a route target using the RT Redirect Extended Community. This is specified using the global identifier followed by the local identifier (e.g. "64496:123").
• rt-redirect: Optional values that when set allow redirection to a route target based on IP address. The "ip" value must match the address family of the action type (i.e. IPv4 for "bgp-flowspec-v4" and IPv6 for "bgp-flowspec-v6").

# Action type is "bgp-flowspec-v4"
rt-redirect = {ip = "192.0.2.100", local=123}
# Action type is "bgp-flowspec-v6"
rt-redirect = {ip = "2001:db8::F00", local=123}

• ip-redirect-legacy-ietf: An optional value, if set, that allows redirection to an IP following draft-ietf-idr-flowspec-redirect-ip-02. The "ip" value must match the address family of the action type (i.e. IPv4 for "bgp-flowspec-v4" and IPv6 for "bgp-flowspec-v6"), with the copy bit set accordingly:

# Action type is "bgp-flowspec-v4", copy bit unset
ip-redirect-legacy-ietf = { ip = "198.51.100.7", copy=false }
# Action type is "bgp-flowspec-v6", copy bit set
ip-redirect-legacy-ietf = { ip = "2001:db8::1", copy=true }

• traffic-marking: An optional value that specifies a new value that will be used for the IPv4 DSCP header field or IPv6 Traffic Class header field for matching traffic.
• communities: An optional list of BGP Communities that will be used in the announcement. Each entry can be one of the values from the community special type.
• large-communities" An optional list of BGP Large Communities to add to the announcement. Each entry requires three colon-separated numbers between 0 and 4294967295, such as "123:456:789".
• as-path: An optional list of AS numbers that will be set as the AS Path in the announcement. This can be used when you want to do path prepending.
• local-pref: An optional value that, when set, modifies the BGP LOCAL_PREF attribute that will be used in the announcement.
• multi-exit-disc: An optional value that, when set, modifies the BGP MULTI_EXIT_DISC attribute that will be used in the announcement.
• aigp-metric: An optional value that, when set, modifies the BGP AIGP attribute used in the announcement. The metric value used will be the value field set within the AIGP TLV.
• no-op: An optional value that, when set to true, indicates this BGP Flowspec Action should be logged only, but not actively make announcements. This can be useful to test your configured action to ensure that any BGP Flowspec announcements are being made as you expect, without actually redirecting any traffic.