ExaBGP

BGP Swiss Army Knife of Networking

ExaBGP is a BGP implementation designed to enable network engineers and developers to interact with BGP networks using simple Python scripts or external programs via a simple API.

Key Differentiator: Unlike traditional BGP daemons (BIRD, FRRouting), ExaBGP does not manipulate the FIB (Forwarding Information Base). Instead, it focuses on BGP protocol implementation and provides an API for external process.

Table of Contents

Getting Started Use Cases Features Quick Start

Installation Docker Zipapp pip releases GitHub releases git main OS packages

Usage Upgrade Documentation Support Contributing

Development Requirements Version Information Testing Debug Options Message Decoding

Use Cases

ExaBGP is used for:

• Service Resilience: Cross-datacenter failover solutions, migrating /32 service IPs
• DDoS Mitigation: Centrally deploying network-level filters (blackhole and/or FlowSpec)
• Network Monitoring: Gathering network information via BGP-LS or BGP with Add-Path
• Traffic Engineering: Dynamic route injection and manipulation via API
• Anycast Management: Automated anycast network control

Learn more on the wiki.

Features

Protocol Support

• RFC Compliance: ASN4, IPv6, MPLS, VPLS, Flow, Graceful Restart, Enhanced Route Refresh, Extended Next-Hop, BGP-LS, AIGP, and more
• Address Families: IPv4/IPv6 Unicast/Multicast, VPNv4/VPNv6, EVPN, FlowSpec, BGP-LS, MUP, SRv6
• Capabilities: Add-Path, Route Refresh, Graceful Restart, 4-byte ASN

See RFC compliance details for the latest developments.

Architecture

• JSON API: Control BGP via external programs (Python, shell scripts, etc.)
• No FIB Manipulation: Pure BGP protocol implementation
• Event-Driven: Custom reactor pattern (pre-dates asyncio)
• Extensible: Registry-based plugin architecture

Note: If you need FIB manipulation, consider other open source BGP daemons such as BIRD or FRRouting.

Quick Start

The fastest way to get started:

# Using Docker
docker pull ghcr.io/exa-networks/exabgp:latest
docker run -it --rm ghcr.io/exa-networks/exabgp:latest --help

# Using zipapp (self-contained executable)
git clone https://github.com/Exa-Networks/exabgp
cd exabgp
./release binary /usr/local/sbin/exabgp
/usr/local/sbin/exabgp --version

# Using pip
pip install exabgp
exabgp --help

# From source
git clone https://github.com/Exa-Networks/exabgp
cd exabgp
./sbin/exabgp --help

See Installation for detailed options and Documentation for configuration examples.

Installation

Should you encounter any issues, we will ask you to install the latest version from git. The simplest way to install ExaBGP is as a zipapp.

Docker

Official container images are built and published on GitHub. To install from the command line use:

docker pull ghcr.io/exa-networks/exabgp:latest
docker run -it --rm ghcr.io/exa-networks/exabgp:latest version

You can also build your own container image from the repository:

git clone https://github.com/Exa-Networks/exabgp exabgp-git
cd exabgp-git
docker build -t exabgp ./
docker run -p 179:1790 --mount type=bind,source=`pwd`/etc/exabgp,target=/etc/exabgp -it exabgp -v /etc/exabgp/parse-simple-v4.conf

It is possible to add your configuration file within the docker image and/or use the container like the exabgp binary. You can also use the Docker.remote file to build it using pip (does not require any other file).

Zipapp

From the source folder, it is possible to create a self-contained executable which only requires an installed python3 interpreter:

git clone https://github.com/Exa-Networks/exabgp exabgp-git
cd exabgp-git
./release binary /usr/local/sbin/exabgp
/usr/local/sbin/exabgp --version

which is a helper function and creates a python3 zipapp:

git clone https://github.com/Exa-Networks/exabgp exabgp-git
cd exabgp-git
python3 -m zipapp -o /usr/local/sbin/exabgp -m exabgp.application:main -p "/usr/bin/env python3" src
/usr/local/sbin/exabgp --version

pip releases

The latest version is available on pypi, the Python Package Index:

pip install exabgp

exabgp --version
exabgp --help

exabgp --run healthcheck --help
python3 -m exabgp healthcheck --help

GitHub releases

It is also possible to download releases from GitHub:

curl -L https://github.com/Exa-Networks/exabgp/archive/4.2.22.tar.gz | tar zx
cd exabgp-4.2.22
./sbin/exabgp --version
./sbin/exabgp --help

./sbin/exabgp --run healthcheck --help
env PYTHONPATH=./src python3 -m exabgp healthcheck --help
./bin/healthcheck --help

git main

In case of issues, we are asking users to run the latest code directly from a local git clone:

git clone https://github.com/Exa-Networks/exabgp exabgp-git
cd exabgp-git
./sbin/exabgp --version
./sbin/exabgp --help

./sbin/exabgp --run healthcheck --help
env PYTHONPATH=./src python3 -m exabgp healthcheck --help
./bin/healthcheck --help

It is then possible to change git to use any release (here 4.2.22):

git checkout 4.2.22
./sbin/exabgp --version

OS packages

The program is packaged for many systems such as Debian, Ubuntu, ArchLinux, Gentoo, FreeBSD, OSX.

RHEL users can find help here.

Many OS distributions provide older releases, but on the plus side, the packaged version will be integrated with systemd.

Feel free to use your preferred installation option, but should you encounter any issues, we will ask you to install the latest code (the main branch) using git.

Pick and Choose

Multiple versions can be used simultaneously without conflict when ExaBGP is run from extracted archives, docker, and/or local git repositories. If you are using main, you can use exabgp version to identify the location of your installation.

Upgrade

ExaBGP is self-contained and easy to upgrade/downgrade by:

• replacing the downloaded release folder for releases downloaded from GitHub
• running git pull in the repository folder for installation using git main
• running pip install -U exabgp, for pip installations
• running apt update; apt upgrade exabgp for Debian/Ubuntu

If you are migrating your application from ExaBGP 3.4 to 4.x please read this wiki entry.

The configuration file and API format may change occasionally, but every effort is made to ensure backward compatibility is kept. However, users are encouraged to read the release note/CHANGELOG and check their setup after any upgrade.

Documentation

📚 Official Wiki Documentation

Comprehensive documentation is available in the ExaBGP Wiki:

🚀 Getting Started:

• Home - Main documentation hub
• Quick Start - 5-minute tutorial
• Installation Guide - Detailed installation for all platforms
• First BGP Session - Step-by-step BGP setup

🔧 API Documentation:

• API Overview - Architecture and patterns
• Text API Reference - Complete text command reference
• JSON API Reference - JSON message format
• API Commands - A-Z command reference

🛡️ FlowSpec & DDoS Mitigation:

• FlowSpec Overview - DDoS mitigation guide
• Match Conditions - All match types
• Actions Reference - All actions (discard, rate-limit, redirect)

⚙️ Configuration:

• Configuration Syntax - Complete syntax guide
• Directives Reference - A-Z configuration directives

📖 Additional Resources:

• RFC Compliance - 55+ RFCs implemented
• Migration Guide - Upgrading from 3.4 to 4.x
• Related Projects - Community tools and integrations
• User Articles - Tutorials and blog posts

💡 Examples

To understand ExaBGP configuration in practice, explore the 98 configuration examples in the etc/exabgp folder covering:

• Basic BGP peering
• FlowSpec rules
• IPv4/IPv6 unicast and multicast
• L3VPN, EVPN, BGP-LS
• API integration patterns
• Health checks and failover

Run exabgp --help for command-line options and built-in documentation.

🤝 Contributing to Documentation

Documentation contributions are genuinely welcomed! Even small improvements help the community. See the Contributing section below.

Development

Requirements

• Python 3.8.1+ required (supports recent versions through 3.12+)
• No asyncio: Uses custom reactor pattern predating asyncio adoption
• Compatibility: Focus on reliability over adopting latest Python features

ExaBGP 3.4 and previous versions were Python 2 applications. ExaBGP 4.0 had support for both Python 2 and 3. The current version of ExaBGP (4.2 and main) targets Python 3 only. The code should work with all recent versions (>= 3.6), but the requirement is set to 3.8.1 as some of the tooling now requires it (such as ruff).

ExaBGP is nearly as old as Python 3. A lot has changed since 2009; the application does not use Python 3's async-io (as we run a homemade async core engine). It may never do as development slowed, and our primary goal is ensuring reliability for current and new users.

Version Information

• Current stable: 4.2.x (recommended for production)
• Development: 5.0.x (main branch)
  • Breaking changes: Command-line arguments changed from 4.x

The main branch (previously the master branch) is now ExaBGP 5.0.x. The program command line arguments have already been changed and are no longer fully backwards compatible with versions 3 and 4. We recommend using the 4.2 releases in production, but running main is sometimes required for troubleshooting.

Testing

File descriptor limit: Ensure ulimit -n ≥ 64000 before running tests:

ulimit -n 64000

Functional tests - BGP message encoding/decoding validation:

ExaBGP comes with a set of functional tests. Each test starts an IBGP daemon expecting a number of pre-recorded UPDATEs for the matching configuration file.

# List all available tests
./qa/bin/functional encoding --list

# Run all tests
./qa/bin/functional encoding

# Run specific test (using letter from --list, e.g., A, B)
./qa/bin/functional encoding A

You can also manually run both the server and client for any given test:

# In shell 1
./qa/bin/functional encoding --server A

# In shell 2
./qa/bin/functional encoding --client A

Unit tests - with coverage reporting:

A test suite is present to complement the functional testing (requires pip3 install pytest pytest-cov):

env exabgp_log_enable=false pytest --cov --cov-reset ./tests/*_test.py

Configuration parsing tests:

./qa/bin/parsing

Debug Options

The following "unsupported" options are available to help with development:

exabgp.debug.configuration  # Trace configuration parsing errors with pdb
exabgp.debug.pdb           # Enable python debugger on runtime errors
                           # (be ready to use `killall python` for orphaned processes)
exabgp.debug.route         # Similar to using decode but using the environment

Message Decoding

You can decode UPDATE messages using ExaBGP's decode option:

env exabgp_tcp_bind='' ./sbin/exabgp decode -c ./etc/exabgp/api-open.conf \
  FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF:003C:02:0000001C4001010040020040030465016501800404000000C840050400000064000000002001010101

Output (JSON format):

{
  "exabgp": "4.0.1",
  "time": 1560371099.404008,
  "host": "ptr-41.212.219.82.rev.exa.net.uk",
  "pid": 37750,
  "ppid": 10834,
  "counter": 1,
  "type": "update",
  "neighbor": {
    "address": {
      "local": "127.0.0.1",
      "peer": "127.0.0.1"
    },
    "asn": {
      "local": 1,
      "peer": 1
    }
  },
  "direction": "in",
  "message": {
    "update": {
      "attribute": {
        "origin": "igp",
        "med": 200,
        "local-preference": 100
      },
      "announce": {
        "ipv4 unicast": {
          "101.1.101.1": [
            {
              "nlri": "1.1.1.1/32",
              "path-information": "0.0.0.0"
            }
          ]
        }
      }
    }
  }
}

Support

The most common issue reported (ExaBGP hangs after some time) is caused by using code written for ExaBGP 3.4 with 4.2 or main without having read this wiki entry

ExaBGP is supported through GitHub's issue tracker. So should you encounter any problems, please do not hesitate to report it so we can help you.

During "day time" (GMT/BST) feel free to contact us on Slack. We will try to respond if available.

The best way to be informed about our progress/releases is to follow us on Twitter.

If there are any bugs, we'd like to ask you to help us fix the issue using the main branch. We may then backport the fixes to the 4.2 stable branch.

Please remove any non git main installations if you are trying the latest release to prevent running the wrong code by accident; it happens more than you think. Verify the binary by running exabgp version.

We will nearly systematically ask for the FULL output of exabgp with the option -d.

Contributing

Contributions are welcome! Here's how you can help:

1. Report Issues: Use our issue tracker
2. Improve Documentation: Even small improvements are genuinely appreciated
3. Submit Pull Requests:
   • Target the main branch for new features
   • Target 4.2 branch for bug fixes (we may backport)
   • Include tests for new functionality
   • Run ruff format before committing

Development Setup

git clone https://github.com/Exa-Networks/exabgp
cd exabgp
pip install -e .
pip install pytest pytest-cov ruff

See CLAUDE.md for detailed development guidelines and architecture overview.