Skip to content

Building From Source

Thomas Mangin edited this page Oct 2, 2026 · 7 revisions

Building ExaBGP From Source

Compiling ExaBGP and Creating Distribution Packages

This guide covers building ExaBGP from source code, creating Debian (.deb) packages, and creating RPM packages. Most users should install via pip or package managers (see Installation Guide), but building from source is useful for development, testing unreleased versions, or packaging for internal distribution.


Table of Contents


When to Build From Source

Consider building from source if you:

  • ✅ Need unreleased features from main branch
  • ✅ Want to test bug fixes before release
  • ✅ Contribute to ExaBGP development
  • ✅ Create custom packages for internal distribution
  • ✅ Run ExaBGP on unsupported platforms
  • ✅ Need to apply custom patches

Use package manager instead if you:

  • ❌ Just want to use ExaBGP in production
  • ❌ Prefer stable, tested releases
  • ❌ Want automatic updates

Prerequisites

All Platforms

Python Version:

  • ExaBGP 6.0.0+ (main): Python 3.12+ required
  • ExaBGP 5.x (stable): Python 3.8+ required
  • ExaBGP 4.x: Python 3.6+ (also Python 2.7, deprecated)
  • Recommended for 6.0.0: Python 3.12 or 3.13

Required Tools:

# Git for source code
git --version

# Python development tools
python3 --version
python3 -m pip --version

Debian/Ubuntu

# Basic build tools
sudo apt-get update
sudo apt-get install -y git python3 python3-pip python3-dev python3-setuptools

# For building .deb packages
sudo apt-get install -y \
    git-core \
    devscripts \
    build-essential \
    lintian \
    python3-all \
    python3-setuptools \
    dh-python

RHEL/CentOS/Fedora

# Basic build tools
sudo dnf install -y git python3 python3-pip python3-devel python3-setuptools

# For building RPM packages
sudo dnf install -y \
    rpm-build \
    rpmdevtools \
    python3-devel \
    python3-setuptools

macOS

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python and git
brew install python git

Building from Git

Clone Repository

Latest development version (main branch):

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

Specific release (recommended for stability):

git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
git tag -l                    # List available tags
git checkout 5.0.13           # Checkout specific version

Specific branch:

git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
git checkout -b my-branch origin/some-feature-branch

Compiled Build (main only)

From a checkout of main, uv sync then ./qa/bin/build_mypyc compiles the message code and the RIB with mypyc into build/mypyc, for 1.4 to 2.1 times the speed on route processing. It needs a C compiler and the Python headers. See Compiled Build (mypyc).

Install from Source (Development Mode)

Editable install (for development):

# Install in development mode (changes reflect immediately)
python3 -m pip install -e .

# Verify installation
exabgp version
which exabgp  # Should show your git checkout path

Standard install:

# Install to system Python
sudo python3 setup.py install

# Or install to user directory (no sudo)
python3 setup.py install --user

# Verify
exabgp version

Install Dependencies

ExaBGP has NO runtime dependencies!

ExaBGP is designed to have zero external dependencies for maximum portability.

Development dependencies (optional, for testing):

# For running tests
python3 -m pip install pytest pytest-cov

# For code linting
python3 -m pip install ruff

Creating Debian Packages

Build .deb packages for Debian, Ubuntu, Mint, etc.

💡 Attribution: Based on community contributions. Debian packaging is maintained by the Debian Python team.

Prerequisites

sudo apt-get install -y \
    git-core \
    devscripts \
    build-essential \
    lintian \
    python3-all \
    python3-setuptools \
    dh-python

Build Process

Step 1: Clone and checkout version

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

# Checkout specific version (example: 5.0.13)
git checkout 5.0.13

Step 2: Retrieve Debian packaging files

# Get debian/ directory from packaging branch
git checkout origin/debian/sid -- debian

Step 3: Update changelog

# Update version in changelog
dch -v 5.0.13-1 "New upstream release"

# Or manually edit
editor debian/changelog

Step 4: Prepare build

# Remove incompatible settings (if needed)
rm -f debian/source/format

# Clean up any version-specific issues
# (Adjust based on your version)

Step 5: Build packages

# Build unsigned packages (for local use)
debuild -us -uc

# You may see warning about missing .orig tarball
# Answer 'y' to continue

# Build with signing (for distribution)
debuild -sa

Step 6: Install built packages

# Packages are created in parent directory
cd ..
ls -la *.deb

# Install packages
sudo dpkg -i exabgp_*.deb

# Fix dependencies if needed
sudo apt-get install -f

Debian Package Structure

Packages created:

  • exabgp_X.Y.Z-N_all.deb - Main ExaBGP package
  • exabgp-common_X.Y.Z-N_all.deb - Common files (if separate)

Installation locations:

  • Binary: /usr/sbin/exabgp
  • Python modules: /usr/lib/python3/dist-packages/exabgp/
  • Configuration: /etc/exabgp/
  • Systemd unit: /lib/systemd/system/exabgp.service
  • Documentation: /usr/share/doc/exabgp/

Creating RPM Packages

Build RPM packages for RHEL, CentOS, Fedora, etc.

💡 Attribution: EPEL packaging guidance by @garybuhrmaster (Issue #1166).

Prerequisites

# Install build tools
sudo dnf install -y rpm-build rpmdevtools python3-devel python3-setuptools

# Setup RPM build environment
rpmdev-setuptree

Using Existing SPEC File

For EPEL 9 (Fedora 36+, RHEL 9+):

💡 Quote from Gary Buhrmaster: "The packaging has been modified from the generic spec file on this site to use (what the RH python packagers call) 'modern' python build macros available in Fedora and EL9."

The ExaBGP SPEC file for Fedora/EPEL is maintained in Fedora dist-git:

Download and use:

# Get the SPEC file from Fedora dist-git
curl -O https://src.fedoraproject.org/rpms/python-exabgp/raw/epel9/f/python-exabgp.spec

# Download source tarball
spectool -g python-exabgp.spec

# Copy to rpmbuild
cp python-exabgp.spec ~/rpmbuild/SPECS/
cp exabgp-*.tar.gz ~/rpmbuild/SOURCES/

# Build RPM
cd ~/rpmbuild/SPECS
rpmbuild -ba python-exabgp.spec

Building from Git (Manual SPEC)

Step 1: Create source tarball

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

# Create tarball
git archive --format=tar.gz --prefix=exabgp-5.0.13/ \
    -o ~/rpmbuild/SOURCES/exabgp-5.0.13.tar.gz 5.0.13

Step 2: Create basic SPEC file

# Use Fedora SPEC as template (recommended)
# Or create minimal SPEC:
cat > ~/rpmbuild/SPECS/exabgp.spec << 'EOF'
%global srcname exabgp

Name:           python-%{srcname}
Version:        5.0.13
Release:        1%{?dist}
Summary:        BGP route injector

License:        BSD
URL:            https://github.com/Exa-Networks/exabgp
Source0:        %{srcname}-%{version}.tar.gz

BuildArch:      noarch
BuildRequires:  python3-devel
BuildRequires:  python3-setuptools

%description
ExaBGP is a BGP route injector.

%prep
%autosetup -n %{srcname}-%{version}

%build
%py3_build

%install
%py3_install

# Install systemd unit
install -D -m 644 etc/systemd/exabgp.service %{buildroot}%{_unitdir}/exabgp.service

%files
%license LICENCE.txt
%doc README.md doc/CHANGELOG.rst
%{_bindir}/exabgp
%{python3_sitelib}/%{srcname}/
%{python3_sitelib}/%{srcname}-*.egg-info/
%{_unitdir}/exabgp.service

%changelog
* $(date +"%a %b %d %Y") Your Name <your@email.com> - 5.0.13-1
- New upstream release
EOF

Step 3: Build RPM

cd ~/rpmbuild/SPECS
rpmbuild -ba exabgp.spec

# Check built packages
ls -la ~/rpmbuild/RPMS/noarch/
ls -la ~/rpmbuild/SRPMS/

Step 4: Install

sudo dnf install ~/rpmbuild/RPMS/noarch/python3-exabgp-*.rpm

RHEL/Fedora Package Structure

Package name: python3-exabgp

Installation locations:

  • Binary: /usr/bin/exabgp
  • Python modules: /usr/lib/python3.X/site-packages/exabgp/
  • Configuration: /etc/exabgp/
  • Systemd unit: /usr/lib/systemd/system/exabgp.service
  • Documentation: /usr/share/doc/python3-exabgp/

Testing Your Build

Basic Functionality Test

# Check version
exabgp version

# Validate configuration syntax (ExaBGP 6.0; "exabgp validate" in 5.x)
exabgp configuration validate /etc/exabgp/exabgp.conf

# Run in foreground (test mode)
env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.conf

# Should see the configuration loaded, then the connection attempts to each neighbor
# Press Ctrl+C to stop

Run Test Suite

cd /path/to/exabgp/source

# Install test dependencies
python3 -m pip install pytest pytest-cov

# Run all tests
python3 -m pytest

# Run the unit tests
python3 -m pytest tests/unit/

# Run with coverage
python3 -m pytest --cov=exabgp tests/

Integration Test

# Create a program which writes to STDERR (STDOUT carries commands to ExaBGP)
cat > /tmp/test-api.py << 'EOF'
#!/usr/bin/env python3
import sys
sys.stderr.write('ExaBGP API test\n')
sys.stderr.flush()
for line in sys.stdin:  # stay alive until ExaBGP closes the pipe
    pass
EOF
chmod +x /tmp/test-api.py

# Create minimal test config
cat > /tmp/test-exabgp.conf << 'EOF'
process monitor {
    run /tmp/test-api.py;
    encoder text;
}

neighbor 127.0.0.1 {
    router-id 10.0.0.1;
    local-address 127.0.0.1;
    local-as 65001;
    peer-as 65001;

    api {
        processes [ monitor ];
    }
}
EOF

# Run test
env exabgp.log.level=DEBUG exabgp /tmp/test-exabgp.conf

# Should see "ExaBGP API test" output

Development Workflow

Editable Install for Development

# Clone repo
git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install in editable mode
pip install -e .

# Now you can edit code and test immediately
# No reinstall needed - changes reflect immediately

Running from Source (No Install)

# Set PYTHONPATH to source directory
export PYTHONPATH=/path/to/exabgp/src:$PYTHONPATH

# Run directly
python3 -m exabgp version
# or, from the checkout, without setting PYTHONPATH
./sbin/exabgp version

Code Style and Linting

# Install the linter and formatter the project uses
pip install ruff

# Check code style
ruff check src

# Auto-format
ruff format src

Common Issues

Issue: Python Version Mismatch

Problem: SyntaxError or ModuleNotFoundError

Solution:

# Check Python version
python3 --version  # Must be 3.8+ for 5.x, 3.12+ for 6.0

# Use specific Python version
python3.12 -m pip install -e .
python3.12 -m exabgp version

Issue: Permission Denied on Port 179

Problem: [Errno 13] Permission denied when binding to port 179

Solution:

# Option 1: Run as root (not recommended)
sudo exabgp /etc/exabgp/exabgp.conf

# Option 2: Use capability (Linux); Linux ignores it on a Python script such as the one pip installs
sudo setcap cap_net_bind_service=+ep $(which exabgp)

# Option 3: Use high port for testing
# In config: neighbor 127.0.0.1 { local-address 127.0.0.1; listen 1790; connect 1790; }

Issue: Debian Build Fails with Missing .orig

Problem: expected exabgp_X.Y.Z.orig.tar.gz

Solution:

# Create .orig tarball
git archive --format=tar.gz --prefix=exabgp-5.0.13/ \
    -o ../exabgp_5.0.13.orig.tar.gz 5.0.13

# Then run debuild again
debuild -us -uc

Issue: RPM Build Fails with Missing Macros

Problem: Unknown tag: %py3_build

Solution:

# Install python3-rpm-macros
sudo dnf install python3-rpm-macros

# Fedora modern macros
sudo dnf install python3-rpm-generators

See Also


References


Clone this wiki locally