Skip to content

Directives Reference

Jump to bottom
Thomas Mangin edited this page Mar 6, 2026 · 9 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:

# 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 Settings (Environment Variables)

Note: In ExaBGP 6.x, global settings are configured via environment variables, not an exabgp.env file (which was removed). See Environment Variables for the complete reference.

Common settings:

# API settings
env exabgp.api.ack=true exabgp server config.conf
env exabgp.api.version=6 exabgp server config.conf

# Reactor settings
env exabgp.reactor.speed=1.0 exabgp server config.conf

# Logging
env exabgp.log.level=DEBUG exabgp server config.conf

See also:

[exabgp.daemon]

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 (asplain 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

incoming-ttl

TTL security (Generalized TTL Security Mechanism)

incoming-ttl <hops>;

Example:

incoming-ttl 255;

Notes:

  • Requires packets with minimum TTL (GTSM - RFC 5082)
  • IPv4 uses IP_MINTTL, IPv6 uses IPV6_MINHOPCOUNT
  • Protects against remote attacks on directly connected peers
  • Cannot be combined with outgoing-ttl

outgoing-ttl

Set TTL on outgoing BGP packets (multihop)

outgoing-ttl <hops>;

Example:

outgoing-ttl 5;

Notes:

  • Required for eBGP peers not directly connected (multihop)
  • Sets the IP TTL (IPv4) or hop limit (IPv6) on outgoing packets
  • Cannot be combined with incoming-ttl
  • Replaces the deprecated multihop keyword from ExaBGP 4.x

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 flow ipv4 flow;
ipv4 flow-vpn ipv4 flow-vpn;
ipv6 unicast ipv6 unicast;
ipv6 flow ipv6 flow;
ipv6 flow-vpn ipv6 flow-vpn;
l2vpn vpls l2vpn vpls;
l2vpn evpn l2vpn evpn;

Example:

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

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

    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
incoming-ttl Neighbor TTL security (GTSM)
outgoing-ttl Neighbor Multihop TTL
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 flow;
    }

    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 flow;
        ipv6 flow;
        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 →

Home

Getting Started

Configuration

API

Address Families

Features

Use Cases

Tools

Operations

Reference

Integration

Migration

Community

External

Clone this wiki locally