Skip to content

Configuration Syntax

Jump to bottom
Thomas Mangin edited this page Nov 13, 2025 · 4 revisions

Configuration Syntax

Complete reference for ExaBGP configuration file format

Table of Contents

Overview

ExaBGP uses a structured configuration file (typically /etc/exabgp/exabgp.conf).

Format:

  • INI-like syntax with nested blocks
  • Case-sensitive
  • Comments start with #
  • Blocks use { } braces
  • Semicolons ; optional but recommended

Basic structure:

# Global settings via environment variables

# Neighbor definitions
neighbor <ip> {
    # BGP session parameters
}

# Process definitions
process <name> {
    # API process parameters
}

File Structure

Minimal Configuration

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

Full Structure

# Process definitions (global)
process announce-routes {
    run /etc/exabgp/api/announce.py;
    encoder text;
}

process receive-routes {
    run /etc/exabgp/api/receive.py;
    encoder json;
    receive {
        parsed;
        updates;
    }
}

# Neighbor definitions
neighbor 192.168.1.1 {
    # Identification
    router-id 192.168.1.2;
    local-address 192.168.1.2;
    local-as 65001;
    peer-as 65000;

    # Optional parameters
    description "Core Router 1";
    md5-password "secret";
    hold-time 180;

    # Address families
    family {
        ipv4 unicast;
        ipv6 unicast;
        ipv4 flowspec;
    }

    # Capabilities
    capability {
        route-refresh;
        graceful-restart;
        add-path send/receive;
    }

    # API
    api {
        processes [ announce-routes, receive-routes ];
    }

    # Static routes
    static {
        route 100.10.0.0/24 next-hop self;
    }
}

Neighbor Configuration

Required Parameters

router-id:

router-id 192.168.1.2;

Unique identifier for this BGP speaker. Typically your local IP.

local-address:

local-address 192.168.1.2;

IP address to bind to. Must be reachable by peer.

local-as:

local-as 65001;

Your AS number (1-4294967295). Use 64512-65534 for private AS.

peer-as:

peer-as 65000;

Peer's AS number.

  • If different from local-as → eBGP
  • If same as local-as → iBGP

Optional Parameters

Description:

description "Core Router Primary";

Hold Time:

hold-time 180;

BGP hold timer in seconds (default: 180). Session drops if no keepalive/update for this duration.

MD5 Authentication:

md5-password "secretpassword";

TCP MD5 authentication (RFC 2385).

TTL Security:

ttl-security 255;

Generalized TTL Security Mechanism (GTSM, RFC 5082). Packets with TTL < this value are dropped.

Multihop:

multihop 3;

Allow eBGP multihop (default: 1). Increase TTL for non-directly-connected peers.

Connect Retry:

connect 30;

Connection retry timer in seconds (default: 30).

Peer Address:

peer-address 192.168.1.1;

Explicit peer address (normally inferred from neighbor IP).

Local Port / Peer Port:

local-port 179;
peer-port 179;

Custom BGP ports (default: 179).

Multiple Neighbors

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

neighbor 192.168.2.1 {
    router-id 192.168.1.2;
    local-address 192.168.1.2;
    local-as 65001;
    peer-as 65002;
}

Important: router-id must be unique globally, but can be same across neighbors (it's YOUR id).

Process Configuration

Defines API programs that ExaBGP will run.

Basic Process

process announce-routes {
    run /etc/exabgp/api/announce.py;
    encoder text;
}

Process Parameters

run:

run /etc/exabgp/api/announce.py;

Absolute path to program. Must be executable.

encoder:

encoder text;   # Text format
encoder json;   # JSON format

Message encoding format.

receive:

receive {
    parsed;               # Receive parsed BGP messages
    updates;              # Receive route updates only
    neighbor-changes;     # Receive session state changes
    notifications;        # Receive BGP notifications
    opens;                # Receive OPEN messages
    keepalives;           # Receive keepalives
    refresh;              # Receive route refresh
}

send:

send {
    packets;              # Send raw BGP packets
    parsed;               # Send parsed updates
}

Process with Environment

process announce-routes {
    run /etc/exabgp/api/announce.py;
    encoder text;
    env {
        SERVICE_IP = "100.10.0.100";
        SERVICE_PORT = "80";
    }
}

Environment variables available to the process.

Using Process in Neighbor

process my-process {
    run /etc/exabgp/api/my-script.py;
    encoder text;
}

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

    api {
        processes [ my-process ];
    }
}

Multiple processes:

api {
    processes [ announce-routes, receive-routes, healthcheck ];
}

Static Routes

Announce static routes without API.

Basic Static Routes

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

    static {
        route 100.10.0.0/24 next-hop self;
        route 100.20.0.0/24 next-hop self;
        route 100.30.0.0/24 next-hop self;
    }
}

Static Routes with Attributes

static {
    # With MED
    route 100.10.0.0/24 {
        next-hop self;
        med 100;
    }

    # With communities
    route 100.20.0.0/24 {
        next-hop self;
        community [ 65001:100 65001:200 ];
    }

    # With local-preference (iBGP)
    route 100.30.0.0/24 {
        next-hop self;
        local-preference 200;
    }

    # With AS path prepending
    route 100.40.0.0/24 {
        next-hop self;
        as-path [ 65001 65001 65001 ];
    }
}

IPv6 Static Routes

static {
    route 2001:db8::/32 next-hop self;
    route 2001:db8:100::/48 {
        next-hop self;
        med 50;
    }
}

Address Families

Configure which address families are enabled for the session.

IPv4/IPv6 Unicast

neighbor 192.168.1.1 {
    # ... other config ...

    family {
        ipv4 unicast;
        ipv6 unicast;
    }
}

Default: If family is not specified, only ipv4 unicast is enabled.

FlowSpec

family {
    ipv4 flowspec;
    ipv6 flowspec;
}

Enables FlowSpec for DDoS mitigation and traffic filtering.

L3VPN

family {
    ipv4 mpls-vpn;
    ipv6 mpls-vpn;
}

Enables MPLS L3VPN (RFC 4364).

EVPN

family {
    l2vpn evpn;
}

Enables Ethernet VPN (RFC 7432) for data center fabrics.

BGP-LS

family {
    ipv4 link-state;
    ipv6 link-state;
}

Enables BGP Link-State (RFC 7752) for topology collection.

VPLS

family {
    l2vpn vpls;
}

Enables Virtual Private LAN Service.

Multiple Families

family {
    ipv4 unicast;
    ipv6 unicast;
    ipv4 flowspec;
    ipv6 flowspec;
    ipv4 mpls-vpn;
    l2vpn evpn;
}

API Configuration

Basic API

process my-program {
    run /etc/exabgp/api/program.py;
    encoder text;
}

neighbor 192.168.1.1 {
    # ... other config ...

    api {
        processes [ my-program ];
    }
}

Receiving Updates (JSON)

process receive-updates {
    run /etc/exabgp/api/receive.py;
    encoder json;
    receive {
        parsed;    # Receive all parsed BGP messages
        updates;   # Filter: only route updates
    }
}

neighbor 192.168.1.1 {
    # ... other config ...

    family {
        ipv4 unicast;
    }

    api {
        processes [ receive-updates ];
    }
}

Important: Must enable family to receive routes for that family.

Multiple Processes

process announce {
    run /etc/exabgp/api/announce.py;
    encoder text;
}

process receive {
    run /etc/exabgp/api/receive.py;
    encoder json;
    receive {
        parsed;
        updates;
    }
}

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

neighbor 192.168.1.1 {
    # ... other config ...

    api {
        processes [ announce, receive, healthcheck ];
    }
}

Capabilities

BGP capabilities negotiated during session establishment.

Route Refresh

capability {
    route-refresh;
}

Enables route refresh capability (RFC 2918).

Graceful Restart

capability {
    graceful-restart;
}

Enables graceful restart (RFC 4724).

With parameters:

capability {
    graceful-restart 120;  # Restart time in seconds
}

ADD-PATH

capability {
    add-path send/receive;  # Send and receive multiple paths
}

Options:

  • send - Send multiple paths
  • receive - Receive multiple paths
  • send/receive - Both

Enables ADD-PATH (RFC 7911) for receiving multiple paths to same destination.

Four-Byte ASN

capability {
    asn4;
}

Enables four-byte AS numbers (RFC 6793). Automatically negotiated if local-as or peer-as > 65535.

Extended Message

capability {
    extended-message;
}

Enables extended message size (RFC 8654) for large BGP messages.

Multi-Protocol Extensions

Automatically enabled when address families are configured.

family {
    ipv4 unicast;
    ipv6 unicast;
}
# Multi-protocol capability automatically negotiated

Templates and Groups

Reduce configuration duplication with templates (ExaBGP 4.x+).

Template Definition

template {
    neighbor basic-peer {
        router-id 192.168.1.2;
        local-address 192.168.1.2;
        local-as 65001;

        family {
            ipv4 unicast;
            ipv6 unicast;
        }

        capability {
            route-refresh;
            graceful-restart;
        }
    }
}

Using Template

# Inherit from template
neighbor 192.168.1.1 {
    inherit basic-peer;
    peer-as 65000;
    description "Core Router 1";
}

neighbor 192.168.2.1 {
    inherit basic-peer;
    peer-as 65000;
    description "Core Router 2";
}

Groups

group internal-peers {
    router-id 192.168.1.2;
    local-address 192.168.1.2;
    local-as 65001;

    family {
        ipv4 unicast;
    }

    # Neighbors in this group
    neighbor 192.168.1.3 {
        peer-as 65001;  # iBGP
        description "iBGP Peer 1";
    }

    neighbor 192.168.1.4 {
        peer-as 65001;  # iBGP
        description "iBGP Peer 2";
    }
}

Environment Variables

ExaBGP behavior can be configured with environment variables.

Logging

# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
export exabgp.log.level=DEBUG

# Log destination
export exabgp.log.destination=/var/log/exabgp.log

# Enable specific loggers
export exabgp.log.parser=true
export exabgp.log.network=true
export exabgp.log.routes=true

Daemon Mode

# Run as daemon
export exabgp.daemon.daemonize=true

# PID file
export exabgp.daemon.pid=/var/run/exabgp.pid

# User to drop privileges to
export exabgp.daemon.user=exabgp

API Settings

# ACL for API commands (allow specific IPs)
export exabgp.api.ack=true

# API encoder
export exabgp.api.encoder=json

BGP Settings

# Disable BGP
export exabgp.bgp.openwait=60

Using in Configuration File

# Not directly in config file - use process env instead
process announce {
    run /etc/exabgp/api/announce.py;
    encoder text;
    env {
        CUSTOM_VAR = "value";
    }
}

Or set before running:

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

Complete Examples

Example 1: Basic eBGP with Static Routes

neighbor 192.168.1.1 {
    description "ISP Router";
    router-id 192.168.1.2;
    local-address 192.168.1.2;
    local-as 65001;
    peer-as 65000;

    static {
        route 100.10.0.0/24 next-hop self;
        route 100.20.0.0/24 next-hop self;
    }
}

Example 2: iBGP with API

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

neighbor 192.168.1.3 {
    description "iBGP Peer";
    router-id 192.168.1.2;
    local-address 192.168.1.2;
    local-as 65001;
    peer-as 65001;  # Same AS = iBGP

    family {
        ipv4 unicast;
    }

    capability {
        route-refresh;
    }

    api {
        processes [ healthcheck ];
    }
}

Example 3: FlowSpec for DDoS Mitigation

process flowspec-controller {
    run /etc/exabgp/api/ddos_blocker.py;
    encoder text;
}

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

    family {
        ipv4 flowspec;
    }

    api {
        processes [ flowspec-controller ];
    }
}

Example 4: Multi-Protocol BGP

process announce-all {
    run /etc/exabgp/api/announce.py;
    encoder text;
}

process receive-all {
    run /etc/exabgp/api/receive.py;
    encoder json;
    receive {
        parsed;
        updates;
    }
}

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

    family {
        ipv4 unicast;
        ipv6 unicast;
        ipv4 flowspec;
        ipv4 mpls-vpn;
    }

    capability {
        route-refresh;
        graceful-restart;
        add-path send/receive;
    }

    api {
        processes [ announce-all, receive-all ];
    }
}

Example 5: Multiple Neighbors with Template

# Process definitions
process announce {
    run /etc/exabgp/api/announce.py;
    encoder text;
}

# Template
template {
    neighbor common-config {
        router-id 192.168.1.2;
        local-address 192.168.1.2;
        local-as 65001;

        family {
            ipv4 unicast;
        }

        capability {
            route-refresh;
        }

        api {
            processes [ announce ];
        }
    }
}

# Neighbors using template
neighbor 192.168.1.1 {
    inherit common-config;
    peer-as 65000;
    description "Core Router 1";
}

neighbor 192.168.2.1 {
    inherit common-config;
    peer-as 65002;
    description "Core Router 2";
}

neighbor 192.168.3.1 {
    inherit common-config;
    peer-as 65003;
    description "Edge Router";
    md5-password "secret123";
}

Validation

Test Configuration Syntax

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

Expected output if valid:

OK

Common Syntax Errors

Missing semicolon:

# Wrong
router-id 192.168.1.2

# Correct
router-id 192.168.1.2;

Missing braces:

# Wrong
neighbor 192.168.1.1
    router-id 192.168.1.2;

# Correct
neighbor 192.168.1.1 {
    router-id 192.168.1.2;
}

Invalid IP format:

# Wrong
local-address 192.168.1;

# Correct
local-address 192.168.1.2;

See Also

Ready to configure? Start with 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