# Installation Guide

**Complete installation instructions for all platforms**

---

## Table of Contents

- [Prerequisites](#prerequisites)
- [Installation Methods](#installation-methods)
  - [pipx (Recommended)](#pipx-recommended)
  - [From Source](#from-source)
  - [Package Managers](#package-managers)
  - [Docker](#docker)
- [Platform-Specific Instructions](#platform-specific-instructions)
  - [Linux](#linux)
  - [macOS](#macos)
  - [BSD](#bsd)
  - [Windows](#windows)
- [Verification](#verification)
- [Configuration File Locations](#configuration-file-locations)
- [Troubleshooting](#troubleshooting)
- [Next Steps](#next-steps)

---

## Prerequisites

### System Requirements

- **Python**:
  - ExaBGP 6.0.0+ (main): Python 3.12 or later (3.13, 3.14 tested)
  - ExaBGP 5.x: 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
  - ⚠️ Python 3.7-3.11 dropped in ExaBGP 6.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

### pipx (Recommended)

Installs ExaBGP in an isolated environment with its own Python. Recommended for most users.

```bash
pipx install exabgp
```

Upgrade:
```bash
pipx upgrade exabgp
```

### uv (Fast, Modern)

```bash
uv tool install exabgp
```

### pip

```bash
pip install exabgp
```

Install for current user only (no sudo):
```bash
pip install --user exabgp
```

The binary will be in `~/.local/bin/exabgp` — ensure this is in your PATH:
```bash
export PATH=$PATH:~/.local/bin
```

---

### From Source

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

> 📚 **Comprehensive Guide**: See [Building From Source](Building-From-Source) for complete instructions on building ExaBGP from source, creating Debian/RPM packages, and development workflow.

#### Quick Start — Clone and Install

```bash
git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
pip install -e .
```

#### Development with uv (recommended)

```bash
git clone https://github.com/Exa-Networks/exabgp.git
cd exabgp
uv sync
```

#### Install Specific Branch

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

**For more advanced options:**
- Creating .deb packages → [Building From Source](Building-From-Source#creating-debian-packages)
- Creating RPM packages → [Building From Source](Building-From-Source#creating-rpm-packages)
- Development workflow → [Building From Source](Building-From-Source#development-workflow)

#### Run Without Installing

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

---

### Package Managers

#### Debian/Ubuntu

**Official Debian/Ubuntu packages:**

```bash
sudo apt-get update
sudo apt-get install exabgp
```

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

**Check version:**
```bash
apt-cache policy exabgp
```

#### Red Hat/CentOS/Fedora

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

> 💡 **Attribution**: EPEL packaging guidance provided by [@garybuhrmaster](https://github.com/garybuhrmaster) in [Issue #1166](https://github.com/Exa-Networks/exabgp/issues/1166).

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

```bash
# 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:
- **EPEL 9**: https://src.fedoraproject.org/rpms/python-exabgp/tree/epel9
- **Fedora Rawhide**: https://src.fedoraproject.org/rpms/python-exabgp/tree/rawhide

> 💡 **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):**

```bash
# 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 pip install exabgp
```

**Or use pip (all versions):**
```bash
sudo dnf install python3-pip
sudo pip install exabgp
```

#### Arch Linux

**AUR package:**

```bash
yay -S exabgp
# or
paru -S exabgp
```

#### FreeBSD

**Ports:**

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

**Packages:**

```bash
pkg install py39-exabgp
```

#### macOS (Homebrew)

**Note:** No official Homebrew formula exists. Use pip:

```bash
brew install python3
pip install exabgp
```

---

### Docker

Official Docker images for containerized deployments via GitHub Container Registry.

#### Pull Image

```bash
# ExaBGP 6.0.0+ (main branch) - Latest development
docker pull ghcr.io/exa-networks/exabgp:latest

# ExaBGP 5.x - Stable LTS
docker pull ghcr.io/exa-networks/exabgp:5.0.0
```

**Specific version:**
```bash
docker pull ghcr.io/exa-networks/exabgp:5.0.0
docker pull ghcr.io/exa-networks/exabgp:4.2.25
```

#### Run Container

```bash
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 \
  ghcr.io/exa-networks/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`:

```yaml
version: '3'
services:
  exabgp:
    image: ghcr.io/exa-networks/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:
```bash
docker-compose up -d
```

---

## Platform-Specific Instructions

### Linux

#### System-wide Installation

```bash
sudo pip install exabgp
```

#### Create System User (recommended for production)

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

#### Systemd Service

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

```ini
[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:
```bash
sudo systemctl daemon-reload
sudo systemctl enable exabgp
sudo systemctl start exabgp
sudo systemctl status exabgp
```

---

### macOS

#### Install Python 3

```bash
brew install python3
```

#### Install ExaBGP

```bash
pip install exabgp
```

#### launchd Service

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

```xml
<?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:
```bash
launchctl load ~/Library/LaunchAgents/com.exabgp.daemon.plist
```

---

### BSD

#### FreeBSD

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

# Or packages
pkg install py39-exabgp
```

#### OpenBSD

```bash
pkg_add py3-pip
pip install exabgp
```

#### rc.d Service (FreeBSD/OpenBSD)

Create `/etc/rc.d/exabgp`:

```bash
#!/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

```powershell
pip install exabgp
```

#### Run ExaBGP

```powershell
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:

```powershell
nssm install ExaBGP "C:\Python39\Scripts\exabgp.exe" "C:\exabgp\exabgp.conf"
nssm start ExaBGP
```

---

## Verification

### Check Version

```bash
exabgp version
```

Expected output:
```
ExaBGP 5.0.0
# or for main branch:
ExaBGP 6.0.0
```

### Check Installation Path

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

pip show exabgp
# Shows installation location and version
```

### Test Configuration Syntax

```bash
# ExaBGP 5.x
exabgp validate /etc/exabgp/exabgp.conf

# ExaBGP 6.x
exabgp configuration validate /etc/exabgp/exabgp.conf

# Check exit code
echo $?
# 0 = valid configuration (no output)
# 1 = invalid configuration (error messages printed to stderr)
```

**Note:** The `validate` command produces no output on success, only sets exit code to 0. Errors are printed to stderr.

**ExaBGP 4.x:** Use `exabgp --test /etc/exabgp/exabgp.conf`

### Install Shell Completion (ExaBGP 6.0.0+)

ExaBGP 6.0.0 includes dynamic shell completion for Bash, Zsh, and Fish:

```bash
# Auto-detect shell and install
exabgp shell install

# Or specify shell explicitly
exabgp shell install bash
exabgp shell install zsh
exabgp shell install fish

# Manual installation
exabgp shell completion bash > ~/.local/share/bash-completion/completions/exabgp
```

After installation, restart your shell or source the completion file.

### Test Built-in Healthcheck Module

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

```bash
exabgp healthcheck --help
```

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

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

See [Healthcheck Module](Healthcheck-Module) for complete documentation.

### Run in Debug Mode

```bash
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

```bash
# 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:**
```bash
# 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:**
```bash
# 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
```bash
pip install --user exabgp
```

**Solution 2:** Use sudo (not recommended for production)
```bash
sudo pip install exabgp
```

---

### ExaBGP Not in PATH

**Error:**
```
-bash: exabgp: command not found
```

**Solution:**

Find where pip installed exabgp:
```bash
pip show -f exabgp | grep Location
```

Add to PATH:
```bash
# For --user installation
export PATH=$PATH:~/.local/bin

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

---

### Old Version Installed

**Check version:**
```bash
exabgp version
```

**Upgrade:**
```bash
pip install --upgrade exabgp
```

**Force reinstall:**
```bash
pip install --force-reinstall exabgp
```

---

### ImportError or Missing Modules

**Error:**
```
ImportError: No module named 'exabgp'
```

**Solution:**

Check Python version:
```bash
python3 --version  # Must be 3.8+ for 5.x, 3.12+ for 6.0.0
```

Reinstall:
```bash
pip uninstall exabgp
pip install exabgp
```

Verify installation:
```bash
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)
```bash
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)
```bash
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

```bash
pip uninstall exabgp
```

### Source Installation

```bash
cd /path/to/exabgp
pip uninstall exabgp
```

### Package Manager

```bash
# Debian/Ubuntu
sudo apt-get remove exabgp

# FreeBSD
pkg delete exabgp
```

### Remove Configuration

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

---

## Next Steps

Now that ExaBGP is installed, continue to:

- **[Quick Start](Quick-Start)** - Get running in 5 minutes
- **[Healthcheck Module](Healthcheck-Module)** - ⭐ Production-ready health checks (zero code!)
- **[First BGP Session](First-BGP-Session)** - Detailed BGP fundamentals
- **[Configuration Syntax](Configuration-Syntax)** - Complete configuration reference
- **[API Overview](API-Overview)** - Learn the API

---

## Additional Resources

- **GitHub**: https://github.com/Exa-Networks/exabgp
- **PyPI**: https://pypi.org/project/exabgp/
- **Container Registry**: https://ghcr.io/exa-networks/exabgp
- **Documentation**: [Home](Home)
- **Migration Guide**: [5.x → 6.0.0 Migration](../Migration/From-5.x-to-6.x)

---

**Installation complete?** Continue to [Quick Start Guide](Quick-Start) →

---