Repository navigation
First BGP Session
Step-by-step guide to establishing your first BGP session with ExaBGP
- BGP Basics
- Lab Setup
- Configuration Walkthrough
- Establishing the Session
- Understanding BGP Messages
- Adding Your First Route
- Dynamic Route Announcement
- Receiving Routes
- Troubleshooting
- Next Steps
BGP (Border Gateway Protocol) is the routing protocol of the Internet. It's how routers exchange routing information.
Key concepts:
- AS (Autonomous System): A network under a single administrative control (e.g., an ISP, enterprise)
- ASN (AS Number): Unique identifier for an AS (e.g., 65000)
- Peer/Neighbor: Another BGP speaker you exchange routes with
- Route: Network prefix (e.g., 100.10.0.0/24) and how to reach it
- Next-hop: IP address where traffic should be sent
⚠️ Remember: ExaBGP does NOT manipulate the kernel routing table (RIB/FIB).
The flow:
Your Program → ExaBGP → BGP Protocol → Router → Router's RIB/FIB → Traffic Flow
- Your program tells ExaBGP "announce this route"
- ExaBGP sends BGP UPDATE message to router
- Router installs route in its routing table
- Router forwards traffic according to that route
ExaBGP's role: Pure BGP protocol speaker. It talks BGP, you talk to ExaBGP via API.
Minimum lab:
- ExaBGP host (your machine)
- BGP router/speaker to peer with
Options for BGP peer:
- Production router (Cisco, Juniper, Arista) - if you have access
- FRRouting (free, full-featured) - recommended for learning
- BIRD (free, high-performance) - good alternative
- GNS3/EVE-NG (network simulator) - realistic lab
┌─────────────────┐ ┌─────────────────┐
│ ExaBGP Host │ │ BGP Router │
│ │ │ (FRRouting) │
│ 192.168.1.2 │ ←─── eBGP ────→ │ 192.168.1.1 │
│ AS 65001 │ TCP 179 │ AS 65000 │
│ │ │ │
│ Announces: │ │ Installs route │
│ 100.10.0.0/24 │ │ in RIB/FIB │
└─────────────────┘ └─────────────────┘
Network details:
- ExaBGP:
192.168.1.2in AS 65001 - Router:
192.168.1.1in AS 65000 - Connection: eBGP (different ASNs)
- Route to announce:
100.10.0.0/24
If you don't have a router, set up FRRouting for testing:
# Install FRRouting (Ubuntu/Debian)
curl -s https://deb.frrouting.org/frr/keys.asc | sudo apt-key add -
echo deb https://deb.frrouting.org/frr $(lsb_release -s -c) frr-stable | sudo tee /etc/apt/sources.list.d/frr.list
sudo apt update
sudo apt install frr frr-pythontools
# Enable BGP
sudo sed -i 's/bgpd=no/bgpd=yes/' /etc/frr/daemons
sudo systemctl restart frr
# Configure BGP
sudo vtyshFRRouting config:
configure terminal
router bgp 65000
bgp router-id 192.168.1.1
neighbor 192.168.1.2 remote-as 65001
address-family ipv4 unicast
network 10.0.0.0/8
exit-address-family
exit
write memory
Create /etc/exabgp/exabgp.conf:
# Minimal BGP configuration
neighbor 192.168.1.1 {
# Basic identification
router-id 192.168.1.2;
local-address 192.168.1.2;
local-as 65001;
peer-as 65000;
# Announce a static route
static {
route 100.10.0.0/24 next-hop self;
}
}The IP address of the BGP peer (router) we're connecting to.
Router ID: Unique identifier for this BGP speaker. Typically use your IP address. Must be unique in the BGP domain.
Local Address: IP address ExaBGP binds to. Must be reachable by the peer. Usually same as router-id for simple setups.
Local ASN: Our autonomous system number. ASN 64512-65534 are private (like RFC 1918 IPs).
Peer ASN: The router's autonomous system number.
eBGP vs iBGP:
- Different ASNs (65001 ≠ 65000) = eBGP (external BGP)
- Same ASN (65001 = 65001) = iBGP (internal BGP)
Static route announcement: Tell the peer about network 100.10.0.0/24.
next-hop self means "send traffic to me (192.168.1.2)".
exabgp /etc/exabgp/exabgp.confExaBGP logs the loading of its configuration, then the connection to the neighbor. The wording of the log lines differs between versions; the router, below, shows whether the session is established and the route received.
BGP sessions go through these states:
- Idle - Not connected
- Connect - TCP connection attempt
- Active - Failed, retrying
- OpenSent - Sent OPEN message
- OpenConfirm - Received OPEN message
- Established - Session UP ✅
Goal: Reach Established state.
FRRouting:
vtysh -c "show ip bgp summary"Expected output:
Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd
192.168.1.2 4 65001 5 5 0 0 0 00:00:30 1
State/PfxRcd: 1 means session is up and 1 prefix received (our 100.10.0.0/24)
View received route:
vtysh -c "show ip bgp neighbor 192.168.1.2 received-routes"Output:
Network Next Hop Metric LocPrf Weight Path
*> 100.10.0.0/24 192.168.1.2 0 0 65001 i
*> = Best route, installed in RIB
BGP uses 4 message types:
Sent when connection is established. Contains:
- BGP version (4)
- ASN (65001)
- Hold time (180 seconds typically)
- Router ID (192.168.1.2)
- Capabilities (multi-protocol, 4-byte ASN, etc.)
Announces or withdraws routes.
Announcement:
UPDATE: route 100.10.0.0/24 next-hop 192.168.1.2 origin IGP as-path [ 65001 ]
Withdrawal:
UPDATE: withdraw route 100.10.0.0/24
Sent periodically (every 60 seconds) to keep session alive.
If no KEEPALIVE for hold-time seconds (180s), session drops.
Error message. Causes session termination.
Example:
NOTIFICATION: Cease - Administrative Reset
Common reasons:
- Configuration change
- Manual shutdown
- Protocol error
ExaBGP can announce multiple static routes:
neighbor 192.168.1.1 {
router-id 192.168.1.2;
local-address 192.168.1.2;
local-as 65001;
peer-as 65000;
family {
ipv4 unicast;
ipv6 unicast; # carry IPv6 routes over this IPv4 session
}
static {
# Multiple routes
route 100.10.0.0/24 next-hop self;
route 100.20.0.0/24 next-hop self;
route 100.30.0.0/24 next-hop self;
# IPv6: "self" is the IPv4 session address, so name the next-hop
route 2001:db8:100::/48 next-hop 2001:db8::2;
# With attributes
route 100.40.0.0/24 {
next-hop self;
med 100; # Multi-Exit Discriminator (metric)
local-preference 200; # Preference for iBGP
community [ 65001:100 ]; # BGP community
}
}
}MED (Multi-Exit Discriminator): Lower is preferred. Suggests which path to use when multiple exist.
route 100.10.0.0/24 next-hop self med 50; # Preferred
route 100.10.0.0/24 next-hop self med 100; # Less preferredLocal Preference (iBGP only): Higher is preferred. Used within an AS to prefer certain paths.
route 100.10.0.0/24 next-hop self local-preference 200;Communities: Tags attached to routes for policy decisions.
route 100.10.0.0/24 next-hop self community [ 65001:100 65001:200 ];AS Path Prepending: Make path longer (less preferred) for traffic engineering.
route 100.10.0.0/24 next-hop self as-path [ 65001 65001 65001 ];Appears as: 65001 65001 65001 (prepended twice)
The real power: announce routes based on application logic.
Configuration:
neighbor 192.168.1.1 {
router-id 192.168.1.2;
local-address 192.168.1.2;
local-as 65001;
peer-as 65000;
# No static routes - API controls everything
api {
processes [ dynamic-routes ];
}
}
process dynamic-routes {
run /etc/exabgp/api/announce.py;
encoder text;
}Create /etc/exabgp/api/announce.py:
#!/usr/bin/env python3
"""
Simple dynamic route announcement
"""
import sys
def send(command):
"""Write one command, then read lines until ExaBGP answers it."""
sys.stdout.write(command + '\n')
sys.stdout.flush()
while True:
line = sys.stdin.readline()
if not line: # ExaBGP closed the pipe: it is stopping
sys.exit(0)
answer = line.strip()
if answer == 'done':
return True
if answer == 'error':
return False
# Announce routes
routes = [
"100.10.0.0/24",
"100.20.0.0/24",
"100.30.0.0/24"
]
for route in routes:
if send(f"announce route {route} next-hop self"):
sys.stderr.write(f"[API] Announced {route}\n")
else:
sys.stderr.write(f"[API] ExaBGP refused {route}\n")
# Keep process alive until ExaBGP closes the pipe
while sys.stdin.readline():
passExaBGP answers each command with done or error on the script's standard input, and the script reads that answer before sending the next command, see Reading the answers. ExaBGP 6.0 writes these commands with a peer * selector, see How a program talks to ExaBGP.
Make executable:
chmod +x /etc/exabgp/api/announce.pyRun ExaBGP:
exabgp /etc/exabgp/exabgp.confOutput:
[API] Announced 100.10.0.0/24
[API] Announced 100.20.0.0/24
[API] Announced 100.30.0.0/24
The script writes these lines on its standard error, which ExaBGP does not read: they appear wherever ExaBGP's own standard error goes, here the terminal.
ExaBGP can receive routes from the router and process them.
neighbor 192.168.1.1 {
router-id 192.168.1.2;
local-address 192.168.1.2;
local-as 65001;
peer-as 65000;
# Receive IPv4 unicast routes
family {
ipv4 unicast;
}
# API processes receive updates
api {
processes [ receive-routes ];
neighbor-changes; # Receive session state changes
receive {
parsed; # Receive parsed BGP messages
update; # Receive route updates
}
}
}
process receive-routes {
run /etc/exabgp/api/receive.py;
encoder json; # JSON format for easier parsing
}Create /etc/exabgp/api/receive.py:
#!/usr/bin/env python3
"""
Receive and process BGP routes
"""
import sys
import json
for line in sys.stdin:
line = line.strip()
if line in ('done', 'error') or line.startswith('error:'):
continue # the answer to a command, not a message
try:
message = json.loads(line)
# Handle route updates
if message['type'] == 'update':
update = message['neighbor']['message']['update']
# New route announced: family -> next hop -> list of routes
if 'announce' in update:
announce = update['announce']
if 'ipv4 unicast' in announce:
for next_hop, routes in announce['ipv4 unicast'].items():
for route in routes:
if 'nlri' not in route:
continue # an End-of-RIB marker
print(f"[RECEIVED] Route {route['nlri']} via {next_hop}", file=sys.stderr)
# Route withdrawn: family -> list of routes
if 'withdraw' in update:
withdraw = update['withdraw']
if 'ipv4 unicast' in withdraw:
for route in withdraw['ipv4 unicast']:
print(f"[WITHDRAWN] Route {route['nlri']}", file=sys.stderr)
# Handle session state
elif message['type'] == 'state':
state = message['neighbor']['state']
print(f"[STATE] BGP session state: {state}", file=sys.stderr)
except json.JSONDecodeError:
pass
except Exception as e:
print(f"[ERROR] {e}", file=sys.stderr)On router (FRRouting), announce a route:
vtysh -c "configure terminal" -c "router bgp 65000" -c "network 10.0.0.0/8"ExaBGP output:
[RECEIVED] Route 10.0.0.0/8 via 192.168.1.1
Symptom: BGP stays in Connect or Active state
Check:
-
Network connectivity
ping 192.168.1.1 telnet 192.168.1.1 179
-
Firewall rules
# Allow TCP 179 sudo iptables -A INPUT -p tcp --dport 179 -j ACCEPT sudo iptables -A OUTPUT -p tcp --sport 179 -j ACCEPT -
Router configuration
- Peer address correct (
neighbor 192.168.1.2) - AS numbers match expectation
- Address family enabled
- Peer address correct (
-
ExaBGP config
-
local-addressreachable by peer -
peer-asmatches router's AS -
local-asis correct
-
Debug:
env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.confSymptom: The TCP connection never establishes, although the network and the BGP settings are correct.
Cause: MD5 password mismatch. With TCP MD5, the receiving kernel drops every segment whose signature is wrong or missing, so neither side receives a BGP NOTIFICATION.
Solution: Add MD5 password to both ExaBGP and router
ExaBGP:
neighbor 192.168.1.1 {
router-id 192.168.1.2;
local-address 192.168.1.2;
local-as 65001;
peer-as 65000;
md5-password "secretpassword";
}FRRouting:
router bgp 65000
neighbor 192.168.1.2 password secretpassword
Symptom: Session established, but routes not in router's RIB
Check:
-
ExaBGP has the route in its Adj-RIB-Out
exabgp run rib show out # 6.0 exabgp cli show adj-rib out # 5.x
-
Router sees the route
# FRRouting vtysh -c "show ip bgp neighbor 192.168.1.2 received-routes"
-
Route accepted (not filtered)
- Check prefix-lists, route-maps, AS-path filters
-
Best path selected
- Lower MED
- Higher local-pref (iBGP)
- Shorter AS path
- Lower IGP metric
Debug on router:
vtysh -c "show ip bgp 100.10.0.0/24"Look for *> = best path, installed in RIB
Symptom: Process not in ps aux | grep announce.py
Check:
-
Script executable
chmod +x /etc/exabgp/api/announce.py
-
Shebang correct
#!/usr/bin/env python3 -
Path correct
run /etc/exabgp/api/announce.py; # Absolute path -
ExaBGP log: ExaBGP logs the failure to start the program, with the reason.
Test manually:
/etc/exabgp/api/announce.pySymptom: API script runs, but routes not announced
Check:
-
STDOUT flush
sys.stdout.write("announce route 100.10.0.0/24 next-hop self\n") sys.stdout.flush() # CRITICAL - without this, nothing happens
-
Command syntax
# Correct print("announce route 100.10.0.0/24 next-hop self") # Wrong print("announce 100.10.0.0/24 next-hop self") # Missing 'route'
-
ExaBGP log shows command: with
exabgp.log.level=DEBUGandexabgp.log.processes=true, ExaBGP logs every command a program writes and the answer it gives.
⚠️ Important: ExaBGP's API and configuration syntax changed significantly between versions.
- ExaBGP 3.x (legacy, deprecated)
- ExaBGP 4.x (maintenance, 4.2.25+)
- ExaBGP 5.x (stable)
- ExaBGP 6.0.0 (development - main branch)
Configuration Format Changed:
ExaBGP 3.x (OLD):
neighbor 192.168.1.1 {
router-id 192.168.1.2;
local-address 192.168.1.2;
local-as 65001;
peer-as 65000;
# OLD process syntax
process announce-routes {
run /usr/bin/python /etc/exabgp/api/announce.py;
}
}ExaBGP 4.x (NEW):
neighbor 192.168.1.1 {
router-id 192.168.1.2;
local-address 192.168.1.2;
local-as 65001;
peer-as 65000;
# NEW api syntax
api {
processes [ announce-routes ];
}
}
process announce-routes {
run /etc/exabgp/api/announce.py;
encoder text;
}Key differences:
- Separate
processblock outsideneighborin 4.x -
api { processes [ ... ] }syntax in 4.x -
encoderdirective added in 4.x
JSON Message Format Changed:
ExaBGP 3.4 JSON output:
{
"exabgp": "3.4.8",
"time": 1699564800,
"host": "exabgp-host",
"pid": "12345",
"ppid": "1",
"counter": 1,
"type": "update",
"neighbor": {
"ip": "192.168.1.1",
"address": {
"local": "192.168.1.2",
"peer": "192.168.1.1"
},
"asn": {
"local": "65001",
"peer": "65000"
},
"message": {
"update": {
"announce": {
"ipv4 unicast": {
"192.168.1.2": {
"100.10.0.0/24": {}
}
}
}
}
}
}
}ExaBGP 4.x JSON output:
{
"exabgp": "4.0.1",
"time": 1699564800.0,
"host": "exabgp-host",
"pid": 12345,
"ppid": 1,
"counter": 1,
"type": "update",
"neighbor": {
"address": {
"local": "192.168.1.2",
"peer": "192.168.1.1"
},
"asn": {
"local": 65001,
"peer": 65000
},
"message": {
"update": {
"announce": {
"ipv4 unicast": {
"192.168.1.2": [
{
"nlri": "100.10.0.0/24"
}
]
}
}
}
}
}
}Key differences:
- The
exabgpfield gives the version of the JSON format,3.4.8for 3.4 and4.0.1for 4.x, not the version of ExaBGP -
pid,ppidand the AS numbers are numbers in 4.x, strings in 3.4 - 4.x drops the
ipfield ofneighbor - Under each next hop, 3.4 gives an object keyed by prefix, 4.x a list of
{ "nlri": ... }objects
API Command Format:
ExaBGP 3.x:
# Announce
print("announce route 100.10.0.0/24 next-hop 192.168.1.2")
# Withdraw
print("withdraw route 100.10.0.0/24")ExaBGP 4.x:
# Announce - can use 'self'
print("announce route 100.10.0.0/24 next-hop self")
# Withdraw
print("withdraw route 100.10.0.0/24")
# FlowSpec syntax improved
print("announce flow route { match { destination 100.10.0.0/24; } then { discard; } }")Key differences:
- FlowSpec syntax cleaner in 4.x
- More attribute support in 4.x
Status: ExaBGP 5.0.0 released November 2025 (871 commits, largest release in history).
- Python 3.8+ required (3.9+ recommended, Python 2 completely removed)
-
JSON API: AS-PATH format changed (array → object of segments, each with an
elementand avalue) - BGP-LS: Field names changed (sr_capability_flags → sr-capability-flags, etc.)
- Config syntax: route-refresh, FlowSpec fragments, tcp.attempts
- Removed: Prefix-SID Type-2/4
- Deprecated: tcp.once, replaced by tcp.attempts
- New defaults: Hostname capability sent by default
New Features:
- ✅ SRv6 - Complete Segment Routing over IPv6 support
- ✅ BGP-MUP - Mobile User Plane SAFI
- ✅ RFC 9072 - Extended Optional Parameters Length
- ✅ ACK runtime control - disable-ack, enable-ack, silence-ack
- ✅ Security fixes - TOCTOU vulnerability patched
Recommendation: See 4.x → 5.0.0 Migration Guide for upgrade planning. ExaBGP 4.x remains in maintenance mode (critical fixes only).
ExaBGP 5.0 (stable, recommended, currently 5.0.13)
- ✅ Current stable series (5.0.0 released November 2025)
- ✅ All newest features (SRv6, BGP-MUP, etc.)
- ✅ Security fixes (TOCTOU vulnerability)
- ✅ Python 3.8-3.13 support
- ✅ Recommended for all new deployments
⚠️ Breaking changes from 4.x - See migration guide- ✅ This documentation covers 5.0
ExaBGP 4.2.x (Previous Stable)
- ✅ Production-proven
- ✅ No breaking changes within 4.x series
- ✅ Python 2.7 + 3.6+ support
⚠️ Maintenance mode - Only critical fixes, no new features- ℹ️ Suitable for existing deployments not yet ready to migrate
- ✅ This documentation covers 4.x
main branch (development, will become 6.0.0 - not released, nothing tagged)
- ✅ Latest features (asyncio engine, shell completion, enhanced CLI)
- ✅ Python 3.12-3.14 support
⚠️ Breaking changes from 5.x - See migration guide⚠️ Python 3.12+ required (3.7-3.11 dropped)⚠️ BGP-LS JSON field names changed- ℹ️ Test thoroughly before production
ExaBGP 3.x (Deprecated)
- ❌ No longer maintained
- ❌ Python 2 only (end-of-life)
- ❌ Must upgrade - See 3.x → 4.x migration
Decision Guide:
-
New deployment? → Use 5.0 (released, stable) unless you want the features being built for 6.0, then use
main -
Existing 5.x deployment? → Consider
mainif you need those features and can test thoroughly - Existing 4.x deployment? → Plan migration to 5.0.0 (test thoroughly first)
- Still on 3.x? → Upgrade to 5.0.0 (via 4.x if needed for staged migration)
See Migration Guide: 3.4 to 4.x for complete migration instructions.
Quick summary:
-
Update configuration syntax:
- Move
processblocks outsideneighbor - Change to
api { processes [ ... ] }syntax - Add
encoder textorencoder json
- Move
-
Update API scripts (if using JSON):
- Parse new JSON structure
- Under each next hop, read a list of
{ "nlri": ... }objects, not an object keyed by prefix
-
Test thoroughly:
- ExaBGP 3.x and 4.x are NOT compatible
- Configuration files don't work between versions
- API scripts need updates
Before (3.x config):
neighbor 192.168.1.1 {
router-id 192.168.1.2;
local-address 192.168.1.2;
local-as 65001;
peer-as 65000;
process announce {
run /usr/bin/python /etc/exabgp/announce.py;
}
}After (4.x config):
neighbor 192.168.1.1 {
router-id 192.168.1.2;
local-address 192.168.1.2;
local-as 65001;
peer-as 65000;
api {
processes [ announce ];
}
}
process announce {
run /etc/exabgp/announce.py;
encoder text;
}Before (3.4 API script receiving JSON):
#!/usr/bin/env python
import json, sys
for line in sys.stdin:
msg = json.loads(line)
if msg.get('type') != 'update':
continue
# 3.4 structure: family -> next hop -> prefix -> {}
update = msg['neighbor']['message']['update']
if 'announce' in update and 'ipv4 unicast' in update['announce']:
for nexthop, prefixes in update['announce']['ipv4 unicast'].items():
for prefix in prefixes:
sys.stderr.write("Route: %s via %s\n" % (prefix, nexthop))After (4.x API script):
#!/usr/bin/env python3
import json, sys
for line in sys.stdin:
line = line.strip()
if line in ('done', 'error') or line.startswith('error:'):
continue # the answer to a command, not a message
msg = json.loads(line)
if msg.get('type') != 'update':
continue
# 4.x structure: family -> next hop -> list of routes
update = msg['neighbor']['message']['update']
if 'announce' in update and 'ipv4 unicast' in update['announce']:
for nexthop, routes in update['announce']['ipv4 unicast'].items():
for route in routes:
if 'nlri' in route: # an End-of-RIB has none
sys.stderr.write(f"Route: {route['nlri']} via {nexthop}\n")Key changes:
- Under each next hop:
routesis a list of{ "nlri": ... }objects, not an object keyed by prefix - 4.x answers each command with
doneorerroron the same input, which the script skips
exabgp versionOutput:
ExaBGP : 5.0.13
Python : 3.9.16
If you see 3.x.x: You're on deprecated version - upgrade to 5.x (via 4.x if needed).
If you see 4.2.x: You're on maintenance branch - plan upgrade to 5.x when ready.
If you see 5.x.x: You're on the stable release, recommended for production.
If you see 6.x.x or main: You're on development branch - test thoroughly before production.
- Migration: 3.4 to 4.x - Complete migration guide
- Migration: 4.2 to 5.0 - When 5.0 releases
- Breaking Changes - All breaking changes across versions
- API Overview - Complete API documentation
- Configuration Syntax - All configuration options
- Text API Reference - All API commands
- High Availability - Health checks + anycast
- DDoS Mitigation - FlowSpec automated blocking
- Anycast Management - Load balancing patterns
- FlowSpec - Traffic filtering with BGP
- Communities - Route tagging and policies
- Attributes - BGP path attributes
What you learned:
✅ BGP fundamentals (AS, neighbor, route, next-hop) ✅ ExaBGP configuration syntax ✅ Establishing BGP session (Established state) ✅ Announcing static routes ✅ Using the API for dynamic routes ✅ Receiving routes from router ✅ Troubleshooting common issues
Key concepts:
- ExaBGP speaks BGP protocol but does NOT manipulate kernel routing table
- Routers install the routes ExaBGP announces
- API uses simple STDIN/STDOUT for any language
- BGP session must reach "Established" state
- Always
flush()after writing to STDOUT
Ready for more? Continue to API Overview →
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