ExaBGP¶
ExaBGP is controlled with text
commands such as announce route 10.0.0.0/24 next-hop 192.0.2.1, printed by
helper scripts ("processes") that it runs. bgpipe reads and writes the same
commands, one per line, in every stage that takes --format exa:
stdin, stdout, read,
write, exec, pipe, and
websocket. Files named *.exa are detected
automatically.
This lets you:
- run a script written for ExaBGP under bgpipe, with no ExaBGP involved
- turn MRT files, live feeds, or a BGP session into commands for an ExaBGP instance
- keep routes in a plain text file that both tools understand
Supported commands¶
announce route PREFIX [next-hop ADDR|self] [ATTRIBUTE ...]
withdraw route PREFIX
announce attributes [next-hop ADDR|self] [ATTRIBUTE ...] nlri PREFIX [PREFIX ...]
withdraw attributes nlri PREFIX [PREFIX ...]
announce flow route MATCH ... ACTION ...
withdraw flow route MATCH ...
ipv4 unicast and ipv6 unicast are accepted in place of route. Empty lines
and lines starting with # are skipped. A leading neighbor selector
(neighbor 192.0.2.1 announce route ...) is accepted and ignored: a bgpipe
pipeline is one BGP session, so run one bgpipe per neighbor.
The prefixes after nlri go into one UPDATE, so they must be all IPv4 or all
IPv6. See Flowspec for flow route.
| Attribute | Example | Notes |
|---|---|---|
next-hop |
next-hop 192.0.2.1 |
self is our address on the BGP session. An IPv4 next-hop for an IPv6 prefix is sent IPv4-mapped (::ffff:192.0.2.1), as ExaBGP does |
origin |
origin igp |
igp, egp, or incomplete; igp if not given |
as-path |
as-path [ 65001 65002 ] |
If not given: our ASN on an eBGP session, else empty |
med |
med 100 |
|
local-preference |
local-preference 200 |
|
community |
community [ 65000:1 no-export ] |
Also no-advertise, no-export-subconfed, no-peer, blackhole |
large-community |
large-community [ 65000:1:2 ] |
|
extended-community |
extended-community [ target:65000:1 ] |
target: and origin: with an ASN or an IPv4 address, or any value as 0x and 16 hex digits |
atomic-aggregate |
atomic-aggregate |
|
aggregator |
aggregator ( 65000:192.0.2.1 ) |
|
originator-id |
originator-id 192.0.2.1 |
|
cluster-list |
cluster-list [ 192.0.2.1 ] |
Lists follow the ExaBGP syntax: brackets need no spaces around them
([65001 65002]), and a single value needs no brackets (community 65000:1).
What bgpipe takes from the session¶
As ExaBGP does, bgpipe completes each announcement with what it knows about the BGP session the commands are sent to:
next-hop selfbecomes the local address of the connection- a route with no
as-pathgets our ASN, if the peer is in another AS (eBGP) - exec
--readanswers each command with adoneorerrorline on the script's stdin, which ExaBGP scripts may wait for
The first two need the session to be up: start the stage that reads the
commands with --wait ESTABLISHED. With no session (eg. when converting
files), the commands are taken as written, and next-hop self leaves the
next-hop unset.
Differences from ExaBGP¶
- Other attributes are errors (eg.
label,path-information,aigp,attribute), as are other commands (announce eor,announce vpls, ...): bgpipe does not announce a route without what was asked for. Add--pardonto skip such lines instead. Use the JSON format when you need every attribute. - Attributes after
withdraw route PREFIXare accepted but not needed. - AS sets are flattened into the AS sequence.
- Output is one command per UPDATE:
routefor a single prefix, elseattributes ... nlri, and aflow routeper Flowspec rule. Other message types (OPEN, KEEPALIVE, End-of-RIB) have no command and are skipped. - Scripts get commands, not ExaBGP's JSON. Without
--read, exec writes the messages of the pipeline to the script as commands; scripts that parse ExaBGP's JSON encoding of received routes need porting.
Run an ExaBGP script¶
An ExaBGP process script prints commands on its stdout. Run it with exec and bgpipe announces the routes itself:
bgpipe \
-- speaker --active --asn 65001 --id 192.0.2.2 \
-- exec --format exa --read --wait ESTABLISHED /usr/local/bin/healthcheck.sh \
-- connect 192.0.2.1
--wait ESTABLISHEDstarts the script once the session is up--readmakes the stage read-only: bgpipe writes nothing butdoneanderrorto the script's stdin
For example, this script announces a service prefix and withdraws it when the service stops responding:
#!/bin/sh
up=0
while sleep 5; do
if curl -fs -m 2 -o /dev/null http://127.0.0.1/health; then
[ $up = 1 ] || echo "announce route 203.0.113.0/24 next-hop self community [65001:100]"
up=1
else
[ $up = 0 ] || echo "withdraw route 203.0.113.0/24"
up=0
fi
done
ExaBGP's own health checker runs unmodified, too:
bgpipe \
-- speaker --active --asn 65001 --id 192.0.2.2 \
-- exec --format exa --read --wait ESTABLISHED -A \
exabgp healthcheck --no-syslog --no-ip-setup --ip 203.0.113.1/32 \
--cmd "curl -fs -m 2 -o /dev/null http://127.0.0.1/health" --withdraw-on-down -- \
-- connect 192.0.2.1
Flowspec¶
Flow routes (RFC 8955) are read in both ExaBGP forms, and written in the second, flat one:
announce flow route { match { destination 192.0.2.1/32; protocol tcp; destination-port =80; } then { discard; } }
announce flow route destination 192.0.2.1/32 protocol =6 destination-port =80 discard
| Match | Example | Notes |
|---|---|---|
destination, source |
destination 192.0.2.0/24 |
An IPv6 prefix makes it an IPv6 rule; 2001:db8::/64/32 has an offset of 32 bits |
protocol, next-header |
protocol [ tcp udp ] |
next-header for IPv6. A number, or icmp, igmp, tcp, egp, udp, rsvp, gre, esp, ah, ospf, pim, sctp |
port, destination-port, source-port |
destination-port [ =80 =443 ], port >1024&<2048 |
Numbers only |
packet-length |
packet-length >=1000 |
|
icmp-type, icmp-code |
icmp-type echo-request |
A number, or echo-reply, unreachable, redirect, echo-request, time-exceeded |
tcp-flags |
tcp-flags [ syn !ack ], tcp-flags =syn+ack |
fin, syn, rst, push, ack, urg, ece, cwr, or a number as 0x12 |
fragment |
fragment is-fragment |
dont-fragment, is-fragment, first-fragment, last-fragment, or a number |
dscp, traffic-class |
dscp =10 |
traffic-class for IPv6 |
flow-label |
flow-label =5 |
IPv6 only |
Numeric values take = (the default), >, >=, <, <=, !=, and & to
require both conditions; tcp-flags and fragment take no operator (any of
the bits), = (exactly these bits), ! (none of them), and !=. bgpipe
writes all values as numbers.
| Action | Example | Notes |
|---|---|---|
discard |
discard |
|
rate-limit |
rate-limit 9600, rate-limit 1000 packets |
Bytes per second, unless packets |
redirect |
redirect 65000:100, redirect 192.0.2.9 |
To a VRF (route target), or to a next-hop |
redirect-to-nexthop |
redirect-to-nexthop |
|
copy |
copy 192.0.2.9 |
|
mark |
mark 12 |
DSCP |
action |
action sample-terminal |
sample, terminal, or both |
community, large-community, extended-community |
community [ 65000:1 ] |
As for routes |
For example, to drop a DNS amplification attack on one of your addresses, on
a session that carries IPV4/FLOWSPEC:
echo "announce flow route destination 203.0.113.7/32 protocol udp source-port =53 packet-length >=512 discard" |
bgpipe -- speaker --active --asn 65001 --id 192.0.2.2 \
-- stdin --format exa --wait ESTABLISHED \
-- connect 192.0.2.1
bgpipe keeps the session up after its input ends, and the rule with it: stop
bgpipe to remove the rule, or send a withdraw flow route with the same match.
See Flowspec JSON format for the same rules in JSON.
Feed an ExaBGP instance¶
To have ExaBGP announce routes taken from an MRT file (or any other bgpipe input), convert them to commands first:
Then print the file from an ExaBGP process. The script must keep running, as ExaBGP restarts a process that exits: