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

<table width="100%"> <tr valign="top"> <td>

Getting Started

• Use Cases
• Features
• Quick Start
• Version Notice

</td> <td>

Installation

• Docker
• Zipapp
• pip releases
• GitHub releases
• git (stable)
• git (development)
• OS packages

</td> <td>

Usage

• Upgrade
• Documentation
• Support
• Contributing

</td> <td>

Development

• Requirements
• Version Information
• Testing
• Debug Options
• Message Decoding

</td> </tr> </table>

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

For production use, we recommend the 5.0 branch until version 6.0 is officially released.

The main branch contains development work for the upcoming 6.0 release, which includes significant changes (async reactor default, Python 3.12+ requirement). Until 6.0 is released, use the stable 5.0 branch:

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

See Version Information for details on differences between versions.

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

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

git (stable)

For production use, clone and checkout the stable 5.0 branch:

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 testing upcoming features or debugging issues, use the main branch (development towards 6.0):

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

You can switch between branches or checkout specific releases:

git checkout 5.0      # Stable branch
git checkout main     # Development branch
git checkout 5.0.1    # 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  decode  env  healthcheck  run  server  shell  validate  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](https://github.com/Exa-Networks/exabgp/wiki/Migration-from-3.