Skip to content

Installation Guide

Jump to bottom
Thomas Mangin edited this page Nov 15, 2025 · 7 revisions

Installation Guide

Complete installation instructions for all platforms

Table of Contents

Prerequisites

System Requirements

  • Python:
    • ExaBGP 5.0.0+: Python 3.8 or later (3.9+ recommended, 3.13 tested)
    • ExaBGP 4.x: Python 3.6 or later (also supports Python 2.7, deprecated)
    • ⚠️ Python 2 completely removed in ExaBGP 5.0.0
  • OS: Linux, macOS, *BSD, Windows
  • Memory: Minimum 512MB RAM (1GB+ for production)
  • Disk: 50MB for installation
  • Network: BGP peer must be reachable

Python Packages (automatically installed)

ExaBGP has minimal dependencies - pure Python implementation with no required external libraries.

Installation Methods

pip (Recommended)

The simplest and recommended method for most users.

Install Latest Stable Version

pip3 install exabgp

Install Specific Version

pip3 install exabgp==4.2.25

Upgrade Existing Installation

pip3 install --upgrade exabgp

Install for Current User Only (no sudo)

pip3 install --user exabgp

The binary will be in ~/.local/bin/exabgp - ensure this is in your PATH:

export PATH=$PATH:~/.local/bin

From Source

For development, testing, or running the latest unreleased features.

📚 Comprehensive Guide: See Building From Source for complete instructions on building ExaBGP from source, creating Debian/RPM packages, and development workflow.

Quick Start - Clone and Install

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

Install in Development Mode

pip3 install -e .

This creates a symbolic link, so code changes take effect immediately without reinstalling.

Install Specific Branch

git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
git checkout 5.0  # Or any branch/tag
pip3 install -e .

For more advanced options:

Run Without Installing

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

Set environment variable for this method:

export PYTHONPATH=/path/to/exabgp/lib

Package Managers

Debian/Ubuntu

Official Debian/Ubuntu packages:

sudo apt-get update
sudo apt-get install exabgp

Note: Distribution packages may be outdated. Use pip for latest version.

Check version:

apt-cache policy exabgp

Red Hat/CentOS/Fedora

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

💡 Attribution: EPEL packaging guidance provided by @garybuhrmaster in Issue #1166.

A recent version of ExaBGP 4.2.21+ is available in EPEL 9 (Enterprise Linux 9):

# Enable EPEL repository
sudo dnf install epel-release

# Install from EPEL (currently in updates-testing)
sudo dnf --refresh --enablerepo=epel-testing install exabgp

# Once stable, will be available as:
# sudo dnf install exabgp

About EPEL packaging:

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, along with various other RH distro specific adjustments (all distros have slight differences in packaging preferences)."

The SPEC file and packaging details are available in Fedora dist-git:

💡 Maintainer Note: The Fedora ExaBGP packager (Gary Buhrmaster) intends to keep the EPEL9 version in sync with the latest ExaBGP releases until/unless dependencies cannot be met.

Legacy RHEL/CentOS (using yum):

# Enable EPEL
sudo yum install epel-release

# Install ExaBGP
sudo yum install exabgp

# If not available in EPEL, use pip
sudo yum install python3-pip
sudo pip3 install exabgp

Or use pip (all versions):

sudo dnf install python3-pip
sudo pip3 install exabgp

Arch Linux

AUR package:

yay -S exabgp
# or
paru -S exabgp

FreeBSD

Ports:

cd /usr/ports/net/exabgp
make install clean

Packages:

pkg install py39-exabgp

macOS (Homebrew)

Note: No official Homebrew formula exists. Use pip:

brew install python3
pip3 install exabgp

Docker

Official Docker images for containerized deployments.

Pull Image

docker pull exa networks/exabgp:latest

Specific version:

docker pull exanetworks/exabgp:4.2.25

Run Container

docker run -it --rm \
  -v /path/to/exabgp.conf:/etc/exabgp/exabgp.conf:ro \
  -v /path/to/api-scripts:/etc/exabgp/api:ro \
  --network host \
  exanetworks/exabgp:latest \
  exabgp /etc/exabgp/exabgp.conf

Explanation:

  • -v /path/to/exabgp.conf:/etc/exabgp/exabgp.conf:ro - Mount config (read-only)
  • -v /path/to/api-scripts:/etc/exabgp/api:ro - Mount API scripts
  • --network host - Use host networking for BGP (TCP 179)

Docker Compose

Create docker-compose.yml:

version: '3'
services:
  exabgp:
    image: exanetworks/exabgp:latest
    container_name: exabgp
    network_mode: host
    volumes:
      - ./exabgp.conf:/etc/exabgp/exabgp.conf:ro
      - ./api:/etc/exabgp/api:ro
    command: exabgp /etc/exabgp/exabgp.conf
    restart: unless-stopped

Run:

docker-compose up -d

Platform-Specific Instructions

Linux

System-wide Installation

sudo pip3 install exabgp

Create System User (recommended for production)

sudo useradd -r -s /bin/false -c "ExaBGP" exabgp

Systemd Service

Create /etc/systemd/system/exabgp.service:

[Unit]
Description=ExaBGP BGP Speaker
After=network.target

[Service]
Type=simple
User=exabgp
Group=exabgp
ExecStart=/usr/local/bin/exabgp /etc/exabgp/exabgp.conf
ExecReload=/bin/kill -USR1 $MAINPID
Restart=on-failure
RestartSec=5

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/run/exabgp

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable exabgp
sudo systemctl start exabgp
sudo systemctl status exabgp

macOS

Install Python 3

brew install python3

Install ExaBGP

pip3 install exabgp

launchd Service

Create ~/Library/LaunchAgents/com.exabgp.daemon.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.exabgp.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/exabgp</string>
        <string>/usr/local/etc/exabgp/exabgp.conf</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/exabgp.log</string>
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/exabgp.log</string>
</dict>
</plist>

Load service:

launchctl load ~/Library/LaunchAgents/com.exabgp.daemon.plist

BSD

FreeBSD

# Using ports
cd /usr/ports/net/exabgp
make install clean

# Or packages
pkg install py39-exabgp

OpenBSD

pkg_add py3-pip
pip3 install exabgp

rc.d Service (FreeBSD/OpenBSD)

Create /etc/rc.d/exabgp:

#!/bin/sh
#
# PROVIDE: exabgp
# REQUIRE: NETWORKING
# KEYWORD: shutdown

. /etc/rc.subr

name="exabgp"
rcvar=exabgp_enable
command="/usr/local/bin/exabgp"
command_args="/usr/local/etc/exabgp/exabgp.conf"
pidfile="/var/run/${name}.pid"

load_rc_config $name
run_rc_command "$1"

Enable in /etc/rc.conf:

exabgp_enable="YES"

Windows

Install Python 3

Download and install Python from https://www.python.org/downloads/

Important: Check "Add Python to PATH" during installation.

Install ExaBGP

pip install exabgp

Run ExaBGP

exabgp C:\exabgp\exabgp.conf

Windows Service (NSSM)

Use NSSM (Non-Sucking Service Manager) to run ExaBGP as a service:

  1. Download NSSM: https://nssm.cc/download
  2. Install service:
nssm install ExaBGP "C:\Python39\Scripts\exabgp.exe" "C:\exabgp\exabgp.conf"
nssm start ExaBGP

Verification

Check Version

exabgp --version

Expected output:

ExaBGP 4.2.25

Check Installation Path

which exabgp
# Linux/macOS: /usr/local/bin/exabgp or ~/.local/bin/exabgp

pip3 show exabgp
# Shows installation location and version

Test Configuration Syntax

exabgp --test /etc/exabgp/exabgp.conf

Expected output if valid:

OK

Test Built-in Healthcheck Module

ExaBGP includes a production-ready healthcheck module (zero code required!):

exabgp healthcheck --help

You should see available options for health checks, IP management, metrics, and execution hooks.

Example health check test:

# Test a simple health check command
exabgp healthcheck --cmd "curl -sf http://localhost" --ip 10.0.0.1/32 --interval 5

See Healthcheck Module for complete documentation.

Run in Debug Mode

env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.conf

You should see detailed log output showing ExaBGP starting up.

Configuration File Locations

Standard Locations

Linux:

  • /etc/exabgp/exabgp.conf - Main configuration
  • /etc/exabgp/api/ - API scripts
  • /var/log/exabgp.log - Log file

macOS:

  • /usr/local/etc/exabgp/exabgp.conf
  • /usr/local/var/log/exabgp.log

FreeBSD:

  • /usr/local/etc/exabgp/exabgp.conf
  • /var/log/exabgp.log

Create Directories

# Linux
sudo mkdir -p /etc/exabgp/api
sudo mkdir -p /var/log/exabgp
sudo chown -R exabgp:exabgp /etc/exabgp /var/log/exabgp

# macOS
sudo mkdir -p /usr/local/etc/exabgp/api
sudo mkdir -p /usr/local/var/log

Troubleshooting

Python 3 Not Found

Error:

-bash: python3: command not found

Solution:

# Debian/Ubuntu
sudo apt-get install python3 python3-pip

# Red Hat/CentOS
sudo yum install python3 python3-pip

# macOS
brew install python3

pip Not Found

Error:

-bash: pip3: command not found

Solution:

# Debian/Ubuntu
sudo apt-get install python3-pip

# Red Hat/CentOS
sudo yum install python3-pip

# Using Python
python3 -m ensurepip --upgrade

Permission Denied

Error:

ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied

Solution 1: Install for current user only

pip3 install --user exabgp

Solution 2: Use sudo (not recommended for production)

sudo pip3 install exabgp

ExaBGP Not in PATH

Error:

-bash: exabgp: command not found

Solution:

Find where pip installed exabgp:

pip3 show -f exabgp | grep Location

Add to PATH:

# For --user installation
export PATH=$PATH:~/.local/bin

# Make permanent
echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
source ~/.bashrc

Old Version Installed

Check version:

exabgp --version

Upgrade:

pip3 install --upgrade exabgp

Force reinstall:

pip3 install --force-reinstall exabgp

ImportError or Missing Modules

Error:

ImportError: No module named 'exabgp'

Solution:

Check Python version:

python3 --version  # Must be 3.7+

Reinstall:

pip3 uninstall exabgp
pip3 install exabgp

Verify installation:

python3 -c "import exabgp; print(exabgp.__version__)"

BGP Port 179 Permission Denied

Error:

Permission denied: Could not bind to port 179

Explanation: Port 179 requires root/administrator privileges.

Solution 1: Run ExaBGP as root (not recommended)

sudo exabgp /etc/exabgp/exabgp.conf

Solution 2: Use systemd/service manager (recommended)

The systemd service runs as exabgp user but has capability to bind to port 179.

Solution 3: Use port > 1024

Configure your BGP peer to connect to ExaBGP on a high port instead of 179. Not all routers support this.

Solution 4: Grant capability (Linux)

sudo setcap 'cap_net_bind_service=+ep' $(which exabgp)

This allows exabgp binary to bind to privileged ports without running as root.

Uninstallation

pip Installation

pip3 uninstall exabgp

Source Installation

cd /path/to/exabgp
pip3 uninstall exabgp

Package Manager

# Debian/Ubuntu
sudo apt-get remove exabgp

# FreeBSD
pkg delete exabgp

Remove Configuration

sudo rm -rf /etc/exabgp
sudo rm -rf /var/log/exabgp

Next Steps

Now that ExaBGP is installed, continue to:

Additional Resources

Installation complete? Continue to Quick Start Guide →

👻 Ghost written by Claude (Anthropic AI)

🏠 Home

🚀 Getting Started

🔧 API

🛡️ Use Cases

🌐 Address Families

⚙️ Configuration

🔍 Operations

📚 Reference

🔄 Migration

🌍 Community

🔗 External

👻 Ghost written by Claude (Anthropic AI)

Clone this wiki locally