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.

ExaBGP has a fully backward-compatible successor written in Go, called Ze (ze-software.net). If you need more performance than a Python program can deliver, take a look.

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.

Version Notice

Two branches are maintained and both are supported:

5.0 is the stable branch. It is the released version (currently 5.0.9), it is what pip/pipx and most OS packages install, and it runs on Python 3.8 or later. Pick it if you want a tagged release, or if you are not on Python 3.12 yet.
main is the development branch, and the default branch of the repository. It will become 6.0, but it is not 6.0 yet and nothing is tagged: expect the odd rough edge, even though the full unit and functional test suites run on every commit. It requires Python 3.12 or later. Pick it if you want the features being built for 6.0: asyncio engine, the interactive CLI with shell completion, and health monitoring API commands.

If you have no preference, use the stable branch:

git clone https://github.com/Exa-Networks/exabgp
cd exabgp
git checkout 5.0

Beware that git clone without a checkout, and docker pull ghcr.io/exa-networks/exabgp:latest, both give you main, while pip install exabgp gives you the latest 5.0 release.

See Version Information for details on differences between versions.

Related Project: Ze

Ze is a new project by the ExaBGP author, a ground-up rewrite in Go aiming to be a fully programmable network stack for device configuration and network automation. Beyond BGP, Ze manages network interfaces, programs the FIB, and serves a config editor over SSH and a web UI. Everything beyond the core engine is a plugin (Go modules or external processes in any language), and an MCP server lets AI assistants discover and operate its features directly.

Key points for ExaBGP users:

Pre-alpha -- core BGP engine works, but many advanced features are incomplete or untested. APIs and config syntax will change without notice.
ExaBGP bridge -- existing ExaBGP plugins work unchanged, and ze config migrate converts ExaBGP configs.
Feedback wanted -- if you use ExaBGP, try ze config migrate with your configs and share what works and what does not.

Links:

Official repo: github.com/ze-software/ze
Development: codeberg.org/thomas-mangin/ze
Discord: discord.gg/ykJb8meS4

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 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/5.0.9.tar.gz | tar zx
cd exabgp-5.0.9
./sbin/exabgp version
./sbin/exabgp --help

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

git (stable)

For the released version, clone and checkout the stable 5.0 branch (Python 3.8+):

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

git (development)

For the features listed in Version Notice, use the main branch (Python 3.12+), which will become 6.0. It is the branch you get by default:

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

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

You can switch between branches or checkout specific releases:

git checkout 5.0      # Stable branch
git checkout main     # Development branch (future 6.0)
git checkout 5.0.9    # Specific release tag
./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.

Shell Completion

ExaBGP provides dynamic shell completion generation for Bash, Zsh, and Fish to autocomplete commands and options.

⚠️ Note: This feature is newly implemented and not yet extensively tested. Feedback and bug reports are welcome.

Installation:

Install completion scripts for your shell using the built-in command:

# Install completion for current shell (auto-detects Bash/Zsh/Fish)
./sbin/exabgp shell install

# Or specify shell explicitly
./sbin/exabgp shell install bash
./sbin/exabgp shell install zsh
./sbin/exabgp shell install fish

# Uninstall completion (auto-detects shell)
./sbin/exabgp shell uninstall

# Or specify shell explicitly
./sbin/exabgp shell uninstall bash

The completion script will be generated dynamically and installed to your user's completion directory (e.g., ~/.local/share/bash-completion/completions/).

Verify completion is working:

exabgp <TAB>
# Should show: cli  configuration  decode  encode  env  healthcheck  migrate  run  schema  server  shell  version

Manual Generation (advanced):

Generate the completion script to stdout for manual installation:

# Generate bash completion
./sbin/exabgp shell completion bash > ~/.local/share/bash-completion/completions/exabgp
source ~/.local/share/bash-completion/completions/exabgp

# Generate zsh completion
mkdir -p ~/.zsh/completions
./sbin/exabgp shell completion zsh > ~/.zsh/completions/_exabgp
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
autoload -Uz compinit && compinit

# Generate fish completion
mkdir -p ~/.config/fish/completions
./sbin/exabgp shell completion fish > ~/.config/fish/completions/exabgp.fish

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.

ExaBGP 5.0.0 introduces new features including the silence-ack API command. The acknowledgment feature caused issues with simple programs that did not expect ACK messages. The silence-ack command resolves this problem by allowing external processes to disable acknowledgment messages.

ExaBGP 6.0.0 (not released yet, in development on main) will introduce significant improvements since 5.0.0:

⚠️ BREAKING CHANGE - asyncio engine:

The engine runs on asyncio - the homemade generator-based core engine was replaced by an async/await event loop, there is no option to switch back
Same behaviour - the full unit and functional test suites pass on both 5.0 and main
Why the change? Modern event loop integration and easier integration with other asyncio code
Python 3.12+ required - use the 5.0 branch if you run an older interpreter

🎯 New Features:

Shell completion - Install with exabgp shell install [bash|zsh|fish] for smart command completion
Enhanced CLI - Interactive mode with tab completion, JSON formatting, inline help (?)
Health monitoring - New API commands for ping and status checks
Python 3.12+ support - Updated compatibility and bug fixes

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 - the RFCs and drafts implemented
Migration Guide - Upgrading from 3.4 to 4.x
Related Projects - Community tools and integrations

💡 Examples

To understand ExaBGP configuration in practice, explore the 100+ 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.12+ required on main / future 6.0 (supports versions 3.12, 3.13, 3.14), Python 3.8+ on the 5.0 branch
Engine: asyncio on main, homemade generator-based reactor on 5.0
Compatibility: Focus on reliability over adopting latest Python features

Version 3.x supported Python 2 only. Version 4.x introduced Python 3 support while maintaining Python 2 compatibility (minimum: Python 3.6). Version 5.0 requires Python 3.8 or later. Version 6.0 requires Python 3.12 or later, enabling use of modern type annotation syntax, buffer protocol improvements, and other language features.

ExaBGP is nearly as old as Python 3: Python 3.0 was released in December 2008, the first ExaBGP commit is from September 2009. A lot has changed since then, and asyncio only reached the standard library with Python 3.4 in March 2014. The 5.0 branch still runs the homemade async core engine written years before that, while main hands the job to asyncio. Our primary goal remains ensuring reliability for current and new users.

Version Information

Stable: 5.0 branch, released as 5.0.9, Python 3.8+
Development: main branch, will become 6.0, nothing tagged yet, Python 3.12+
- Changes since 5.0: Python 3.12+ required, the engine runs on asyncio, some BGP-LS JSON keys renamed
- New features: interactive CLI with tab completion, shell completion, health monitoring API commands
- Note: the configuration syntax and API remain compatible, but until 6.0 is released, non-backward compatible changes are still possible

Both branches are supported. Use git checkout 5.0 if you want the released version, stay on main if you want the features being built for 6.0. See Version Notice.

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/unit/

Configuration parsing tests:

./qa/bin/test_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, reformatted for readability):

{
  "exabgp": "6.0.0",
  "time": 1785586660.872494,
  "host": "localhost",
  "pid": 10696,
  "ppid": 10691,
  "counter": 1,
  "type": "update",
  "neighbor": {
    "address": {
      "local": "127.0.0.1",
      "peer": "127.0.0.1"
    },
    "asn": {
      "local": 1,
      "peer": 1
    },
    "router-id": "1.2.3.4",
    "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 current versions (5.0+) 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 will backport critical fixes to stable releases.

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:

Report Issues: Use our issue tracker
Improve Documentation: Even small improvements are genuinely appreciated
Submit Pull Requests:
- Target the main branch for new features
- Target 5.0 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 -r qa/requirements.txt

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

Name		Name	Last commit message	Last commit date
Latest commit History 6,445 Commits
.claude		.claude
.forgejo/workflows		.forgejo/workflows
.github		.github
bin		bin
data		data
debian		debian
dev		dev
doc		doc
etc		etc
junk		junk
lab		lab
logo		logo
plan		plan
qa		qa
redhat		redhat
run		run
sbin		sbin
scripts		scripts
service/bgp-service-ip		service/bgp-service-ip
src/exabgp		src/exabgp
tests		tests
.coveragerc		.coveragerc
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.pylintrc		.pylintrc
.python-version		.python-version
ANALYSIS		ANALYSIS
CLAUDE.md		CLAUDE.md
CODING_STYLE.md		CODING_STYLE.md
CONTRIBUTING.md		CONTRIBUTING.md
CRUSH.md		CRUSH.md
Dockerfile		Dockerfile
Dockerfile.remote		Dockerfile.remote
LICENCE.txt		LICENCE.txt
README.md		README.md
SECTION_MIGRATION_PLAN.md		SECTION_MIGRATION_PLAN.md
env		env
gitignore		gitignore
mypy_status.md		mypy_status.md
patch		patch
pyproject.toml		pyproject.toml
release		release
requirements.txt		requirements.txt
review.md		review.md
setup.cfg		setup.cfg
setup.py		setup.py
uv.lock		uv.lock

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ExaBGP

Table of Contents

Use Cases

Features

Protocol Support

Architecture

Quick Start

Version Notice

Related Project: Ze

Installation

Docker

Zipapp

pip releases

GitHub releases

git (stable)

git (development)

OS packages

Pick and Choose

Shell Completion

Upgrade

Documentation

📚 Official Wiki Documentation

💡 Examples

🤝 Contributing to Documentation

Development

Requirements

Version Information

Testing

Debug Options

Message Decoding

Support

Contributing

Development Setup

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages