# Configuration Syntax

**Complete reference for ExaBGP configuration file format**

---

## Table of Contents

- [Overview](#overview)
- [File Structure](#file-structure)
- [Neighbor Configuration](#neighbor-configuration)
- [Process Configuration](#process-configuration)
- [Static Routes](#static-routes)
- [Address Families](#address-families)
- [API Configuration](#api-configuration)
- [Capabilities](#capabilities)
- [Templates and Groups](#templates-and-groups)
- [Environment Variables](#environment-variables)
- [Complete Examples](#complete-examples)

---

## 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:**
```ini
# Global settings via environment variables

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

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

---

## File Structure

### Minimal Configuration

```ini
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

```ini
# 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 flow;
    }

    # 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:**
```ini
router-id 192.168.1.2;
```
Unique identifier for this BGP speaker. Typically your local IP.

**local-address:**
```ini
local-address 192.168.1.2;
```
IP address to bind to. Must be reachable by peer.

**local-as:**
```ini
local-as 65001;
```
Your AS number (1-4294967295). Use 64512-65534 for private AS.

**peer-as:**
```ini
peer-as 65000;
```
Peer's AS number.
- If different from `local-as` → eBGP
- If same as `local-as` → iBGP

---

### Optional Parameters

**Description:**
```ini
description "Core Router Primary";
```

**Hold Time:**
```ini
hold-time 180;
```
BGP hold timer in seconds (default: 180). Session drops if no keepalive/update for this duration.

**MD5 Authentication:**
```ini
md5-password "secretpassword";
```
TCP MD5 authentication (RFC 2385).

**TTL Security:**
```ini
incoming-ttl 255;
```
Generalized TTL Security Mechanism (GTSM, RFC 5082). Packets with TTL < this value are dropped.

**Multihop:**
```ini
outgoing-ttl 3;
```
Set outgoing TTL (default: 1). Increase for non-directly-connected peers (eBGP multihop).

**Connect Retry:**
```ini
connect 30;
```
Connection retry timer in seconds (default: 30).

**Peer Address:**
```ini
peer-address 192.168.1.1;
```
Explicit peer address (normally inferred from neighbor IP).

**Local Port / Peer Port:**
```ini
local-port 179;
peer-port 179;
```
Custom BGP ports (default: 179).

---

### Multiple Neighbors

```ini
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

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

### Process Parameters

**run:**
```ini
run /etc/exabgp/api/announce.py;
```
Absolute path to program. Must be executable.

**encoder:**
```ini
encoder text;   # Text format
encoder json;   # JSON format
```
Message encoding format.

**receive:**
```ini
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:**
```ini
send {
    packets;              # Send raw BGP packets
    parsed;               # Send parsed updates
}
```

---

### Process with Environment

```ini
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

```ini
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:**
```ini
api {
    processes [ announce-routes, receive-routes, healthcheck ];
}
```

---

## Static Routes

Announce static routes without API.

### Basic Static Routes

```ini
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

```ini
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

```ini
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

```ini
neighbor 192.168.1.1 {
    # ... other config ...

    family {
        ipv4 unicast;
        ipv6 unicast;
    }
}
```

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

---

### FlowSpec

```ini
family {
    ipv4 flow;
    ipv6 flow;
}
```

Enables FlowSpec for DDoS mitigation and traffic filtering.

---

### L3VPN

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

Enables MPLS L3VPN (RFC 4364).

---

### EVPN

```ini
family {
    l2vpn evpn;
}
```

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

---

### BGP-LS

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

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

---

### VPLS

```ini
family {
    l2vpn vpls;
}
```

Enables Virtual Private LAN Service.

---

### Multiple Families

```ini
family {
    ipv4 unicast;
    ipv6 unicast;
    ipv4 flow;
    ipv6 flow;
    ipv4 mpls-vpn;
    l2vpn evpn;
}
```

---

## API Configuration

### Basic API

```ini
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)

```ini
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

```ini
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

```ini
capability {
    route-refresh;
}
```

Enables route refresh capability (RFC 2918).

---

### Graceful Restart

```ini
capability {
    graceful-restart;
}
```

Enables graceful restart (RFC 4724).

**With parameters:**
```ini
capability {
    graceful-restart 120;  # Restart time in seconds
}
```

---

### ADD-PATH

```ini
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

```ini
capability {
    asn4;
}
```

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

---

### Extended Message

```ini
capability {
    extended-message;
}
```

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

---

### Multi-Protocol Extensions

Automatically enabled when address families are configured.

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

---

## Templates and Groups

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

### Template Definition

```ini
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

```ini
# 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

```ini
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

```bash
# 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

```bash
# 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

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

# API encoder
export exabgp.api.encoder=json
```

### BGP Settings

```bash
# Disable BGP
export exabgp.bgp.openwait=60
```

### Using in Configuration File

```ini
# 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:**
```bash
env exabgp.log.level=DEBUG exabgp /etc/exabgp/exabgp.conf
```

---

## Complete Examples

### Example 1: Basic eBGP with Static Routes

```ini
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

```ini
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

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

    api {
        processes [ flowspec-controller ];
    }
}
```

---

### Example 4: Multi-Protocol BGP

```ini
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 flow;
        ipv4 mpls-vpn;
    }

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

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

---

### Example 5: Multiple Neighbors with Template

```ini
# 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

```bash
exabgp configuration validate /etc/exabgp/exabgp.conf
```

Expected output if valid:
```
OK
```

### Common Syntax Errors

**Missing semicolon:**
```ini
# Wrong
router-id 192.168.1.2

# Correct
router-id 192.168.1.2;
```

**Missing braces:**
```ini
# 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:**
```ini
# Wrong
local-address 192.168.1;

# Correct
local-address 192.168.1.2;
```

---

## See Also

- **[First BGP Session](First-BGP-Session)** - Step-by-step configuration guide
- **[Neighbor Configuration](Neighbor-Configuration)** - Detailed neighbor reference
- **[Environment Variables](Environment-Variables)** - All environment variables
- **[Templates and Inheritance](Templates-and-Inheritance)** - Advanced configuration patterns
- **[API Overview](API-Overview)** - Process and API configuration

---

**Ready to configure?** Start with [Quick Start Guide](Quick-Start) →

---