Skip to content

Directives Reference

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

Configuration Directives Reference

A-Z alphabetical reference for all ExaBGP configuration directives

📚 For complete configuration examples, see Configuration Syntax

Table of Contents

Overview

ExaBGP configuration uses hierarchical INI-style syntax.

Basic structure:

# Global settings
[exabgp.api]
ack = true

# Neighbor configuration
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;
    }

    api {
        processes [ announce-routes ];
    }
}

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

Global Directives

[exabgp.api]

API configuration section

[exabgp.api]
ack = true          # Enable command acknowledgment (5.x/main only)
encoder = text      # Default encoder: text or json

Values:

  • ack: true or false (default: true in 5.x/main, not available in 4.x)
  • encoder: text or json

See also:

[exabgp.daemon]

Daemon mode configuration

[exabgp.daemon]
daemonize = true    # Run as daemon
pid = /var/run/exabgp.pid
user = exabgp       # Drop privileges to this user

Values:

  • daemonize: true or false
  • pid: Path to PID file
  • user: Username to drop privileges to

[exabgp.log]

Logging configuration

[exabgp.log]
destination = syslog        # stdout, syslog, or file path
level = INFO                # DEBUG, INFO, WARNING, ERROR, CRITICAL
all = true                  # Log all messages
configuration = true        # Log configuration parsing
reactor = true              # Log event loop
processes = true            # Log process communication
network = true              # Log network events
packets = true              # Log BGP packets
message = true              # Log BGP messages
rib = true                  # Log RIB changes
timer = false               # Log timers
routes = false              # Log route changes

Log levels:

  • DEBUG: Detailed debug information
  • INFO: General information
  • WARNING: Warning messages
  • ERROR: Error messages
  • CRITICAL: Critical errors

Example:

[exabgp.log]
destination = /var/log/exabgp.log
level = INFO
packets = true
message = true

[exabgp.tcp]

TCP connection settings

[exabgp.tcp]
bind = ''           # Local IP to bind (empty = all)
port = 179          # BGP port

Neighbor Directives

neighbor

Define BGP neighbor

neighbor <peer-ip> {
    <directives>
}

Example:

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

router-id

BGP router ID

router-id <ip-address>;

Required: Yes

Example:

router-id 192.168.1.2;

Notes:

  • Must be unique per BGP speaker
  • Typically set to loopback IP or local address
  • Format: IPv4 address (even for IPv6-only sessions)

local-address

Source IP for BGP connection

local-address <ip-address>;

Required: Yes

Example:

local-address 192.168.1.2;

Notes:

  • Must be configured on local interface
  • Used as source IP for TCP connection
  • Can be IPv4 or IPv6

local-as

Local AS number

local-as <asn>;

Required: Yes

Format:

  • 2-byte ASN: 1-65535
  • 4-byte ASN: 1-4294967295 or X.Y notation

Examples:

local-as 65001;           # 2-byte ASN
local-as 4200000001;      # 4-byte ASN
local-as 65001.1;         # 4-byte ASN (asdot notation)

peer-as

Peer AS number

peer-as <asn>;

Required: Yes

Examples:

peer-as 65000;            # 2-byte ASN
peer-as 4200000000;       # 4-byte ASN

description

Neighbor description (comment)

description "<text>";

Example:

description "Core router - Primary peer";

hold-time

BGP hold time (seconds)

hold-time <seconds>;

Default: 180

Range: 3-65535 (0 = disable keepalives)

Example:

hold-time 90;

Notes:

  • Hold time negotiated with peer (lower value wins)
  • Keepalive interval = hold-time / 3

md5-password

TCP MD5 authentication

md5-password "<password>";

Example:

md5-password "secretpassword123";

Notes:

  • Must match peer configuration
  • Use quotes if password contains spaces

ttl-security

TTL security (Generalized TTL Security Mechanism)

ttl-security <hops>;

Example:

ttl-security 255;

Notes:

  • Requires packets with TTL = 255 - hops
  • Protects against remote attacks
  • Alternative to md5-password

group-updates

Group route updates in single BGP UPDATE

group-updates <true|false>;

Default: true

Example:

group-updates true;

Notes:

  • true: More efficient (fewer BGP UPDATEs)
  • false: One route per UPDATE

auto-flush

Automatically flush pending updates

auto-flush <true|false>;

Default: true

Example:

auto-flush true;

Family Directives

family

Enable address families

family {
    <afi> <safi>;
    <afi> <safi>;
}

Address families:

AFI SAFI Directive
ipv4 unicast ipv4 unicast;
ipv4 multicast ipv4 multicast;
ipv4 nlri-mpls ipv4 nlri-mpls;
ipv4 mpls-vpn ipv4 mpls-vpn;
ipv4 flowspec ipv4 flowspec;
ipv6 unicast ipv6 unicast;
ipv6 flowspec ipv6 flowspec;
l2vpn vpls l2vpn vpls;
l2vpn evpn l2vpn evpn;

Example:

neighbor 192.168.1.1 {
    family {
        ipv4 unicast;
        ipv6 unicast;
        ipv4 flowspec;
    }
}

See also:

API Directives

api

Enable API for dynamic route control

api {
    processes [ <process-names> ];
}

Example:

neighbor 192.168.1.1 {
    api {
        processes [ announce-routes healthcheck ];
    }
}

Notes:

  • Process names must match process blocks
  • Multiple processes can be specified

See also:

Process Directives

process

Define external process

process <name> {
    run <command>;
    encoder <text|json>;
}

Required fields:

  • run: Command to execute
  • encoder: Output format (text or json)

Example:

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

run

Command to execute for process

run <command> [arguments];

Example:

run /usr/bin/python3 /etc/exabgp/api/healthcheck.py;
run /etc/exabgp/api/announce.sh;

Notes:

  • Must be absolute path or in $PATH
  • Arguments can be specified
  • Process receives ExaBGP messages on STDIN

encoder

Output format for process

encoder <text|json>;

Values:

  • text: Human-readable text format
  • json: JSON format

Example:

encoder json;

See also:

Capability Directives

capability

BGP capabilities configuration

capability {
    <capability-name> <value>;
}

Available capabilities:

capability {
    asn4 enable;              # 4-byte ASN support
    route-refresh enable;     # Route refresh capability
    graceful-restart <time>;  # Graceful restart (seconds)
    add-path send;            # ADD-PATH send
    add-path receive;         # ADD-PATH receive
    multi-session enable;     # Multi-session support
}

Example:

neighbor 192.168.1.1 {
    capability {
        asn4 enable;
        route-refresh enable;
        graceful-restart 120;
    }
}

asn4

4-byte ASN capability

asn4 <enable|disable>;

Default: enable (if peer supports)

Example:

capability {
    asn4 enable;
}

route-refresh

Route refresh capability

route-refresh <enable|disable>;

Default: enable

Example:

capability {
    route-refresh enable;
}

graceful-restart

Graceful restart time

graceful-restart <seconds>;

Default: 120

Example:

capability {
    graceful-restart 180;
}

add-path

ADD-PATH capability

add-path <send|receive|send/receive|disable>;

Example:

capability {
    add-path send/receive;
}

Session Directives

connect

Connection retry time

connect <seconds>;

Default: 5

Example:

connect 30;  # Retry every 30 seconds

passive

Passive mode (don't initiate connection)

passive <true|false>;

Default: false

Example:

passive true;  # Wait for peer to connect

Static Route Directives

static

Static route announcements

neighbor 192.168.1.1 {
    static {
        route <prefix> {
            next-hop <ip>;
            <attributes>;
        }
    }
}

Example:

neighbor 192.168.1.1 {
    static {
        route 100.10.0.100/32 {
            next-hop self;
            community [ 65001:100 ];
            local-preference 200;
        }
    }
}

route

IPv4/IPv6 unicast route

route <prefix> {
    next-hop <ip|self>;
    <attributes>;
}

Attributes:

  • next-hop: Next-hop IP or self
  • community: BGP communities
  • extended-community: Extended communities
  • as-path: AS path
  • local-preference: Local preference
  • med: MED (Multi-Exit Discriminator)
  • origin: Origin (igp, egp, incomplete)

Example:

route 100.10.0.0/24 {
    next-hop self;
    community [ 65001:100 ];
    local-preference 150;
    med 50;
    origin igp;
}

flow

FlowSpec route

flow {
    route {
        match {
            <conditions>;
        }
        then {
            <actions>;
        }
    }
}

Example:

neighbor 192.168.1.1 {
    family {
        ipv4 flowspec;
    }

    flow {
        route {
            match {
                destination 100.10.0.0/24;
                destination-port =80;
                protocol =tcp;
            }
            then {
                discard;
            }
        }
    }
}

See also:

vpnv4 / vpnv6

L3VPN routes

vpnv4 <prefix> {
    next-hop <ip>;
    route-distinguisher <rd>;
    label <label>;
    extended-community [ <communities> ];
}

Example:

vpnv4 10.0.0.0/24 {
    next-hop 192.168.1.2;
    route-distinguisher 65001:100;
    label 16;
    extended-community [ target:65001:100 ];
}

Template Directives

template

Define reusable configuration template

template {
    neighbor <name> {
        <directives>;
    }
}

Example:

template {
    neighbor standard-peer {
        router-id 192.168.1.2;
        local-as 65001;
        family {
            ipv4 unicast;
        }
    }
}

# Use template
neighbor 192.168.1.1 {
    inherit standard-peer;
    peer-as 65000;
    local-address 192.168.1.2;
}

neighbor 192.168.1.3 {
    inherit standard-peer;
    peer-as 65002;
    local-address 192.168.1.2;
}

inherit

Inherit from template

inherit <template-name>;

Example:

neighbor 192.168.1.1 {
    inherit standard-peer;
    peer-as 65000;
}

Alphabetical Index

Directive Section Purpose
add-path Capability ADD-PATH capability
api API Enable API processes
asn4 Capability 4-byte ASN capability
auto-flush Neighbor Auto-flush updates
capability Capability BGP capabilities
connect Session Connection retry time
description Neighbor Neighbor description
encoder Process Process output format
[exabgp.api] Global API settings
[exabgp.daemon] Global Daemon settings
[exabgp.log] Global Logging settings
[exabgp.tcp] Global TCP settings
family Family Address families
flow Static FlowSpec routes
graceful-restart Capability Graceful restart time
group-updates Neighbor Group route updates
hold-time Neighbor BGP hold time
inherit Template Inherit template
local-address Neighbor Source IP
local-as Neighbor Local AS number
md5-password Neighbor TCP MD5 auth
neighbor Neighbor Define neighbor
passive Session Passive mode
peer-as Neighbor Peer AS number
process Process Define process
route Static Static route
route-refresh Capability Route refresh capability
router-id Neighbor BGP router ID
run Process Process command
static Static Static routes
template Template Define template
ttl-security Neighbor TTL security
vpnv4 Static L3VPN IPv4 route
vpnv6 Static L3VPN IPv6 route

Common Configuration Patterns

Basic BGP Peering

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;
    }
}

BGP with API

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;
    }

    api {
        processes [ announce-routes ];
    }
}

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

FlowSpec Controller

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 ];
    }
}

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

Multiple Address Families

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;
        ipv6 flowspec;
        l2vpn evpn;
    }

    api {
        processes [ controller ];
    }
}

process controller {
    run /etc/exabgp/api/controller.py;
    encoder json;
}

Static Routes with Attributes

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;
    }

    static {
        route 100.10.0.100/32 {
            next-hop self;
            community [ 65001:100 65001:200 ];
            local-preference 200;
            med 10;
        }

        route 100.10.0.0/24 {
            next-hop self;
            as-path [ 65001 65002 ];
            origin igp;
        }
    }
}

Using Templates

template {
    neighbor internal-peer {
        router-id 192.168.1.2;
        local-as 65001;
        family {
            ipv4 unicast;
            ipv6 unicast;
        }
        capability {
            graceful-restart 120;
        }
    }
}

neighbor 192.168.1.1 {
    inherit internal-peer;
    peer-as 65001;
    local-address 192.168.1.2;
    description "Core-1";
}

neighbor 192.168.1.3 {
    inherit internal-peer;
    peer-as 65001;
    local-address 192.168.1.2;
    description "Core-2";
}

Next Steps

Learn More

Address Families

Examples

Need help? Join the ExaBGP Slack or check GitHub Discussions →

👻 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