# Quick Start Guide

**Get ExaBGP running in 5 minutes**

> **ℹ️ Version Notice**
>
> This guide covers **ExaBGP 6.0.0** (main branch). Python 3.12+ required.
>
> Upgrading from an older version? See [Migration Guides](../Migration/Migration-Guide).

---

## Table of Contents

- [What is ExaBGP?](#what-is-exabgp)
- [Important: What ExaBGP Does NOT Do](#important-what-exabgp-does-not-do)
- [Installation](#installation)
- [Your First BGP Session](#your-first-bgp-session)
- [Your First API Program](#your-first-api-program)
- [Next Steps](#next-steps)

---

## What is ExaBGP?

ExaBGP is a **pure BGP protocol implementation** that allows you to control BGP route announcements programmatically. It's the BGP swiss army knife of networking.

**🔥 Most Popular Use Case: Health-Check Based Routing**

ExaBGP's killer feature is **automatic route control based on service health**:
- Your application monitors its own health
- When healthy → announce route via BGP → receive traffic
- When failing → withdraw route via BGP → stop receiving traffic
- **No external monitoring needed** - the application controls its own routing
- **Automatic failover** - routers redirect traffic to healthy instances (5-15 seconds)

**Other common use cases:**
- **DDoS Mitigation** via FlowSpec (pioneered open-source FlowSpec)
- **Anycast Management** with automatic site failover
- **Load Balancing** using BGP ECMP across healthy instances
- **Traffic Engineering** and SDN integration
- **Network Automation** with application-driven routing

---

## Important: What ExaBGP Does NOT Do

> ⚠️ **Critical Concept**: ExaBGP does NOT manipulate the kernel routing table (RIB/FIB).

**ExaBGP is a pure BGP protocol implementation.** It speaks BGP to routers, but:
- ❌ Does NOT install routes in the kernel
- ❌ Does NOT forward packets
- ❌ Is NOT a router

**What it DOES:**
- ✅ Announces routes to BGP peers (routers install them)
- ✅ Receives routes from BGP peers (your program processes them)
- ✅ Provides a simple API (STDIN/STDOUT) for your programs to control BGP

**Think of it as:** Your application tells ExaBGP "announce this route" → ExaBGP tells the router → Router installs it and forwards traffic.

---

## Installation

### Option 1: pipx (Recommended)

```bash
pipx install exabgp
```

### Option 2: uv (fast, modern)

```bash
uv tool install exabgp
```

### Option 3: From Source (latest development)

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

### Verify Installation

```bash
exabgp version
```

---

## Your First BGP Session

Let's create a simple configuration that announces a route to a BGP peer.

### Step 1: Create Configuration File

Create `/etc/exabgp/exabgp.conf`:

```ini
# Minimal BGP configuration
neighbor 192.168.1.1 {
    router-id 192.168.1.2;
    local-address 192.168.1.2;
    local-as 65001;
    peer-as 65000;

    # Announce a static route
    static {
        route 100.10.0.0/24 next-hop 192.168.1.2;
    }
}
```

**What this does:**
- Peers with router `192.168.1.1` (AS 65000)
- Our router-id is `192.168.1.2` (AS 65001)
- Announces `100.10.0.0/24` to the peer
- The peer (router) will install this route and forward traffic to us

### Step 2: Run ExaBGP

```bash
exabgp /etc/exabgp/exabgp.conf
```

You should see:
```
INFO:     Welcome to ExaBGP
INFO:     Established connection to 192.168.1.1
```

**That's it!** Your first BGP session is established and the route is announced.

---

## Your First API Program

The real power of ExaBGP is the **API** - your programs control route announcements dynamically.

### Use Case: High Availability with Health Checks

Announce a service IP only when the service is healthy. If the service fails, withdraw the route automatically.

### Step 1: Create Health Check Script

Create `/etc/exabgp/healthcheck.py`:

```python
#!/usr/bin/env python3
"""
Health check script: Announce route only when service is healthy
"""
import sys
import time
import socket

SERVICE_IP = "100.10.0.100"
SERVICE_PORT = 80
CHECK_INTERVAL = 5


def is_service_healthy():
    """Check if service is listening on port"""
    try:
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        sock.settimeout(2)
        result = sock.connect_ex((SERVICE_IP, SERVICE_PORT))
        sock.close()
        return result == 0
    except:
        return False


# Wait for ExaBGP to be ready
time.sleep(2)

announced = False

while True:
    if is_service_healthy():
        if not announced:
            # Announce route - service is UP
            sys.stdout.write(f"announce route {SERVICE_IP}/32 next-hop 192.0.2.1\n")
            sys.stdout.flush()
            announced = True
            sys.stderr.write(f"[HEALTHCHECK] Service UP - announced {SERVICE_IP}/32\n")
    else:
        if announced:
            # Withdraw route - service is DOWN
            sys.stdout.write(f"withdraw route {SERVICE_IP}/32\n")
            sys.stdout.flush()
            announced = False
            sys.stderr.write(f"[HEALTHCHECK] Service DOWN - withdrawn {SERVICE_IP}/32\n")

    time.sleep(CHECK_INTERVAL)
```

Make it executable:
```bash
chmod +x /etc/exabgp/healthcheck.py
```

### Step 2: Update Configuration

Update `/etc/exabgp/exabgp.conf`:

```ini
neighbor 192.168.1.1 {
    router-id 192.168.1.2;
    local-address 192.168.1.2;
    local-as 65001;
    peer-as 65000;

    # API process - health check controls announcements
    api {
        processes [healthcheck];
    }
}

process healthcheck {
    run /etc/exabgp/healthcheck.py;
    encoder text;
}
```

### Step 3: Run ExaBGP

```bash
exabgp /etc/exabgp/exabgp.conf
```

**What happens:**
1. ExaBGP starts and launches `healthcheck.py`
2. Health check script checks if service is listening on port 80
3. If UP → announces `100.10.0.100/32` to router
4. If DOWN → withdraws `100.10.0.100/32` from router
5. Router automatically redirects traffic based on route presence

**Result:** Automatic high availability! If the service fails, the route is withdrawn and traffic goes elsewhere.

> **⭐ BETTER: Use Built-in Healthcheck Module (Zero Code Required!)**
>
> ExaBGP includes a **production-ready healthcheck module** - no custom script needed:
>
> ```ini
> process watch-service {
>     run python -m exabgp healthcheck \
>         --cmd "nc -z 100.10.0.100 80" \
>         --ip 100.10.0.100/32 \
>         --rise 3 \
>         --fall 2;
> }
> ```
>
> **Built-in features:**
> - ✅ Rise/fall dampening (avoid flapping)
> - ✅ Automatic IP address management
> - ✅ Syslog integration
> - ✅ Metric-based failover
> - ✅ Execution hooks for alerts
> - ✅ Configuration file support
>
> **See:** **[Built-in Healthcheck Module](Healthcheck-Module#built-in-healthcheck-module)** for complete documentation.
>
> **Custom scripts** (like above) are only needed for complex logic. For 90% of use cases, **use the built-in module**!

---

## How the API Works

ExaBGP uses a simple **STDIN/STDOUT** API:

```
┌──────────────┐                 ┌──────────┐
│ Your Program │ STDOUT ────────→│ ExaBGP   │
│              │                 │          │
│ Python/Bash/ │ STDIN  ←────────│ BGP      │
│ Any Language │                 │ Speaker  │
└──────────────┘                 └──────────┘
                                       │
                                       │ BGP Protocol
                                       ↓
                                 ┌──────────┐
                                 │ Router   │
                                 └──────────┘
```

**To announce a route:**
```python
print("announce route 100.10.0.0/24 next-hop 192.0.2.1")
```

**To withdraw a route:**
```python
print("withdraw route 100.10.0.0/24")
```

**To receive updates from router:**
```python
for line in sys.stdin:
    # Process BGP updates from router
    message = json.loads(line)
```

That's it. No complex libraries. Any language that can read/write STDIN/STDOUT can control BGP.

---

## Common Use Cases

### 1. DDoS Mitigation (FlowSpec)

Automatically block attack traffic by announcing FlowSpec rules:

```python
# Block SYN flood from 10.0.0.0/8 to port 80
print("announce flow route { "
      "match { source 10.0.0.0/8; destination-port =80; tcp-flags [ syn ]; } "
      "then { discard; } "
      "}")
```

The router immediately drops matching packets. **ExaBGP pioneered open-source FlowSpec** (now also in GoBGP, FRRouting, BIRD).

### 2. Anycast Service Announcement

Multiple servers announce the same IP. Router uses ECMP to distribute load:

```python
# Each server announces the same service IP
print("announce route 100.10.0.100/32 next-hop 192.0.2.1")
```

If one server fails (route withdrawn), traffic automatically goes to healthy servers.

### 3. Traffic Engineering

Control traffic paths with BGP communities and metrics:

```python
# Prefer this path (lower MED)
print("announce route 100.10.0.0/24 next-hop 192.0.2.1 med 100")

# Backup path (higher MED)
print("announce route 100.10.0.0/24 next-hop 192.0.2.1 med 200")
```

---

## Next Steps

### 📚 Learn More

- **[Installation Guide](Installation-Guide)** - Detailed installation for all platforms
- **[First BGP Session](First-BGP-Session)** - Step-by-step BGP fundamentals
- **[API Overview](API-Overview)** - Complete API documentation
- **[Configuration Syntax](Configuration-Syntax)** - Full configuration reference

### 🎯 Explore Use Cases

- **[DDoS Mitigation](DDoS-Mitigation)** - FlowSpec for automated DDoS response
- **[High Availability](Service-High-Availability)** - Health checks and anycast
- **[Load Balancing](Anycast-Management)** - BGP-based load distribution

### 🔧 Dive Deeper

- **[FlowSpec Overview](FlowSpec-Overview)** - Traffic filtering with BGP
- **[Text API Reference](Text-API-Reference)** - All API commands
- **[98 Configuration Examples](Examples-Index)** - Real-world configs

### 🌐 Community

- **GitHub**: https://github.com/Exa-Networks/exabgp
- **Slack**: https://exabgp.slack.com
- **Mailing List**: exabgp-users@googlegroups.com

---

## Production Deployments

ExaBGP is battle-tested at scale:

- **Facebook/Meta**: Katran L4 load balancer (billions of users)
- **Cloudflare**: DDoS mitigation and anycast
- **Charter Communications**: ISP routing automation
- **PowerDNS**: Anycast DNS high availability

See [Users](Production-Users) for more production stories.

---

## Quick Reference Card

### Basic Commands

```bash
# Install
pipx install exabgp

# Run with config
exabgp /etc/exabgp/exabgp.conf

# Run with debug
env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.conf

# Reload configuration (send SIGUSR1)
kill -USR1 $(pidof exabgp)

# Graceful restart (send SIGTERM)
kill -TERM $(pidof exabgp)
```

### API Commands (print to STDOUT)

```python
# IPv4 Unicast
print("announce route 100.10.0.0/24 next-hop 192.0.2.1")
print("withdraw route 100.10.0.0/24")

# IPv6 Unicast
print("announce route 2001:db8::/32 next-hop 2001:db8::1")

# FlowSpec
print("announce flow route { match { destination 100.10.0.0/24; } then { discard; } }")

# With attributes
print("announce route 100.10.0.0/24 next-hop 192.0.2.1 med 100 local-preference 200")
print("announce route 100.10.0.0/24 next-hop 192.0.2.1 community [65000:100]")

# Flush output (critical!)
sys.stdout.flush()
```

---

## Troubleshooting

### BGP Session Not Establishing

**Check:**
1. Router can reach `local-address`
2. `router-id` is set and unique
3. Firewall allows TCP port 179
4. AS numbers match router config

**Debug:**
```bash
env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.conf
```

### Routes Not Announced

**Check:**
1. Your program prints to STDOUT
2. You call `sys.stdout.flush()` after each print
3. ExaBGP log shows "announced route"
4. Router's BGP table shows the route

**Verify on router:**
```bash
# Cisco
show ip bgp neighbor 192.168.1.2 received-routes

# Juniper
show route receive-protocol bgp 192.168.1.2

# FRRouting
show ip bgp neighbor 192.168.1.2 received-routes
```

### API Program Not Starting

**Check:**
1. Script is executable (`chmod +x`)
2. Correct shebang (`#!/usr/bin/env python3`)
3. ExaBGP log shows "process started"

**Debug:**
```bash
# Run script manually
/etc/exabgp/healthcheck.py

# Check ExaBGP log
tail -f /var/log/exabgp.log
```

---

## Key Concepts Recap

✅ **ExaBGP is a BGP protocol speaker, NOT a router**
✅ **It does NOT install routes in the kernel**
✅ **Your program controls BGP via simple STDIN/STDOUT API**
✅ **Routers receive BGP updates and install routes**
✅ **Traffic flows based on router's routing decisions**

---

**Need help?** Check the [FAQ](FAQ) or ask on [Slack](https://exabgp.slack.com).

**Ready to learn more?** Continue to [Installation Guide](Installation-Guide) →

---