Skip to content

api reference

Jump to bottom
Thomas Mangin edited this page Nov 10, 2025 · 1 revision

ExaBGP API Reference

API Overview

ExaBGP provides a powerful API for programmatic BGP control. External processes interact with ExaBGP via STDIN/STDOUT, making it simple to integrate with any programming language.

Core Architecture

How It Works

  1. Process Configuration: Define external programs in ExaBGP config
  2. STDIN/STDOUT Communication: Programs read from STDIN (BGP messages) and write to STDOUT (commands)
  3. ExaBGP Monitoring: ExaBGP monitors STDOUT for commands
  4. BGP Execution: Commands are parsed and executed as BGP operations

Supported Encoders

  • text: Human-readable format (legacy)
  • json: Structured JSON format (recommended for future use)

Configuration

Process Definition

process <name> {
    run /path/to/program;
    encoder json;          # or 'text'
}

neighbor <ip> {
    router-id <id>;
    local-address <ip>;
    local-as <asn>;
    peer-as <asn>;

    api {
        processes [<name>];
        receive {
            parsed;           # Receive parsed BGP messages
            update;          # Receive UPDATE messages
            notification;    # Receive NOTIFICATION messages
        }
    }
}

Encoder Selection

# JSON encoder (recommended)
process app {
    run python3 /usr/local/bin/app.py;
    encoder json;
}

# Text encoder (legacy)
process app {
    run python3 /usr/local/bin/app.py;
    encoder text;
}

API Commands

Route Announcement

Text Format

announce route <prefix> next-hop <ip> [attributes]

Examples:

announce route 100.10.0.0/24 next-hop self
announce route 192.0.2.0/24 next-hop 203.0.113.1
announce route 2001:db8::/32 next-hop self med 100
announce route 10.0.0.0/8 next-hop self as-path [65000 65001]
announce route 172.16.0.0/16 next-hop self community [65000:100]

JSON Format

{
  "exabgp": "4.0.0",
  "time": 1234567890,
  "host": "hostname",
  "pid": 12345,
  "ppid": 12344,
  "counter": 1,
  "type": "update",
  "neighbor": {
    "address": {"local": "10.0.0.1", "peer": "10.0.0.2"},
    "asn": {"local": 65000, "peer": 65001}
  },
  "message": {
    "update": {
      "announce": {
        "ipv4 unicast": {
          "203.0.113.1": [
            {"nlri": "192.0.2.0/24", "attribute": {...}}
          ]
        }
      }
    }
  }
}

Route Withdrawal

Text Format

withdraw route <prefix> [next-hop <ip>]

Examples:

withdraw route 100.10.0.0/24
withdraw route 192.0.2.0/24 next-hop self
withdraw route 2001:db8::/32

FlowSpec Announcement

Text Format

announce flow route {
    match {
        source <prefix>;
        destination <prefix>;
        port <operators> <values>;
        protocol <protocol>;
        # ... other match conditions
    }
    then {
        discard;
        # or rate-limit <value>;
        # or redirect <target>;
    }
}

Example:

announce flow route {
    match {
        source 192.0.2.0/24;
        destination-port =80;
    }
    then {
        rate-limit 9600;
    }
}

Control Commands

shutdown               # Terminate ExaBGP
reload                 # Reload configuration
restart                # Restart from scratch
version               # Show ExaBGP version

Information Commands

show adj-rib out      # Show advertised routes
show neighbor         # Show neighbor status
show neighbor summary # Show neighbor summary

Receiving BGP Messages

Configuration for Receiving

neighbor <ip> {
    api {
        processes [myapp];
        receive {
            parsed;        # Get parsed messages
            update;        # Get UPDATE messages
            notification;  # Get NOTIFICATION messages
            open;          # Get OPEN messages
            keepalive;     # Get KEEPALIVE messages
            refresh;       # Get ROUTE-REFRESH messages
        }
    }
}

JSON Message Format (Received)

UPDATE Message

{
  "exabgp": "4.0.0",
  "time": 1234567890,
  "host": "hostname",
  "pid": 12345,
  "type": "update",
  "neighbor": {
    "address": {"local": "10.0.0.1", "peer": "10.0.0.2"},
    "asn": {"local": 65000, "peer": 65001}
  },
  "message": {
    "update": {
      "announce": {
        "ipv4 unicast": {
          "203.0.113.1": [
            {
              "nlri": "192.0.2.0/24",
              "attribute": {
                "origin": "igp",
                "as-path": [65001, 65002],
                "med": 100,
                "local-preference": 200
              }
            }
          ]
        }
      }
    }
  }
}

NOTIFICATION Message

{
  "exabgp": "4.0.0",
  "time": 1234567890,
  "type": "notification",
  "neighbor": {
    "address": {"local": "10.0.0.1", "peer": "10.0.0.2"}
  },
  "message": {
    "notification": {
      "code": 6,
      "subcode": 2,
      "data": "cease administrative shutdown"
    }
  }
}

Python Integration Examples

Basic Route Announcement

#!/usr/bin/env python3
import sys
from time import sleep

messages = [
    'announce route 100.10.0.0/24 next-hop self',
    'announce route 200.20.0.0/24 next-hop self',
]

# Wait for ExaBGP to be ready
sleep(5)

# Send announcements
for message in messages:
    sys.stdout.write(message + '\n')
    sys.stdout.flush()

# Keep process running
while True:
    sleep(1)

Health Check Integration

#!/usr/bin/env python3
import sys
import socket
from time import sleep

def is_alive(address, port):
    """Test TCP connectivity"""
    s = socket.socket()
    try:
        s.connect((address, port))
        return True
    except socket.error:
        return False
    finally:
        s.close()

while True:
    if is_alive('10.0.0.100', 80):
        sys.stdout.write('announce route 100.10.0.0/24 next-hop self\n')
    else:
        sys.stdout.write('withdraw route 100.10.0.0/24 next-hop self\n')
    sys.stdout.flush()
    sleep(10)

JSON Message Handling

#!/usr/bin/env python3
import sys
import json

while True:
    line = sys.stdin.readline().strip()
    if not line:
        continue

    try:
        msg = json.loads(line)
        if msg.get('type') == 'update':
            # Process UPDATE message
            process_update(msg)
        elif msg.get('type') == 'notification':
            # Process NOTIFICATION
            process_notification(msg)
    except json.JSONDecodeError:
        sys.stderr.write(f"Invalid JSON: {line}\n")
        sys.stderr.flush()

Route Attributes

BGP Attributes in Text Format

announce route <prefix> next-hop <ip> \
    origin <igp|egp|incomplete> \
    as-path [<asn> <asn> ...] \
    med <value> \
    local-preference <value> \
    community [<asn>:<value> ...] \
    extended-community [target:<asn>:<value> ...] \
    large-community [<asn>:<value1>:<value2> ...]

Example:

announce route 10.0.0.0/8 next-hop self \
    origin igp \
    as-path [65000 65001] \
    med 100 \
    local-preference 200 \
    community [65000:100 65000:200] \
    extended-community [target:65000:1]

Common Attributes

Attribute Description Example
next-hop Next hop IP next-hop self or next-hop 192.0.2.1
origin Route origin origin igp
as-path AS path as-path [65000 65001]
med Multi-exit discriminator med 100
local-preference Local preference local-preference 200
community Standard community community [65000:100]
extended-community Extended community extended-community [target:65000:1]
large-community Large community large-community [65000:100:200]

Advanced Features

VPLS/L2VPN Announcements

announce vpls <endpoint> <offset> <size> <RD> \
    label <value> \
    route-distinguisher <rd>

BGP-LS Announcements

Support for BGP Link-State (RFC 7752) for SDN integration.

Operational Messages

announce operational afi <afi> safi <safi> advisory <string>

Error Handling

Common Issues

  1. Command Not Found: Ensure command syntax is correct
  2. Invalid Next-Hop: Verify next-hop is reachable
  3. Process Died: Check process logs in stderr
  4. JSON Parse Error: Validate JSON syntax

Debugging

Enable debugging in ExaBGP config:

[exabgp.api]
encoder = json

[exabgp.log]
all = true
destination = /var/log/exabgp.log

Performance Considerations

Best Practices

  1. Batch Operations: Group multiple announcements together
  2. Flush Output: Always flush stdout after writing
  3. Error Handling: Check stderr for ExaBGP errors
  4. State Management: Track announced routes in your application
  5. Graceful Shutdown: Withdraw routes before process exit

Scalability

  • ExaBGP can handle thousands of routes
  • Process communication via pipes is efficient
  • Multiple processes can be configured per neighbor
  • JSON encoding has minimal overhead

References

🏠 Home

🚀 Getting Started

🔧 API

🛡️ Use Cases

🌐 Address Families

⚙️ Configuration

🔍 Operations

📚 Reference

🔄 Migration

🌍 Community

🔗 External

👻 Ghost written by Claude (Anthropic AI)

Clone this wiki locally