Skip to content

Environment Variables

Jump to bottom
Thomas Mangin edited this page Mar 6, 2026 · 4 revisions

Environment Variables

ExaBGP can be configured using environment variables, providing an alternative to command-line arguments and allowing easy integration with containerized deployments.

Table of Contents

Overview

Environment variables control ExaBGP's runtime behavior without modifying configuration files. They are especially useful for:

  • Docker/Kubernetes deployments
  • CI/CD pipelines
  • Quick debugging sessions
  • Overriding defaults without editing config

Naming Convention

ExaBGP accepts two formats for environment variables:

Format Example Notes
Dot notation (canonical) exabgp.log.level=DEBUG Preferred in documentation
Underscore notation exabgp_log_level=DEBUG Shell-friendly alternative

Both formats work identically. The code checks both.

# These are equivalent:
env exabgp.log.level=DEBUG exabgp server config.conf
env exabgp_log_level=DEBUG exabgp server config.conf

Network & Connection (tcp.*)

tcp.attempts

  • Default: 0
  • Type: integer
  • Description: Maximum TCP connection attempts per peer before giving up (0 = unlimited).
Value Behavior
0 Daemon mode (default) — each peer retries indefinitely
N > 0 Limited retry mode — each peer gives up after N failed connection attempts 
# Production: run forever
env exabgp.tcp.attempts=0 exabgp server config.conf

# Testing: exit after 50 failures
env exabgp.tcp.attempts=50 exabgp server config.conf

tcp.bind

  • Default: (empty — disable listening)
  • Type: space-separated IP list
  • Description: Local IP addresses to bind to when listening for incoming BGP connections.
env exabgp.tcp.bind="127.0.0.1 ::1" exabgp server config.conf

tcp.port

  • Default: 179
  • Type: integer
  • Description: TCP port for incoming BGP connections. Ports below 1024 require root.
env exabgp.tcp.port=1179 exabgp server config.conf

tcp.delay

  • Default: 0
  • Type: integer
  • Description: Delay route announcements until the minutes in the hour is a modulo of this number. Used for synchronized startup across multiple instances.

tcp.once

  • Default: false
  • Type: boolean
  • Description: Only one TCP connection attempt per peer. Deprecated — use tcp.attempts=1 instead.

tcp.acl

  • Default: (empty)
  • Type: boolean
  • Description: EXPERIMENTAL — DO NOT USE. Unimplemented ACL feature.

BGP Protocol (bgp.*)

bgp.openwait

  • Default: 60
  • Type: integer (seconds)
  • Description: How many seconds to wait for a BGP OPEN message after TCP connection is established.
env exabgp.bgp.openwait=30 exabgp server config.conf

bgp.passive

  • Default: false
  • Type: boolean
  • Description: Ignore peer configuration and make all peers passive (only accept incoming connections, never initiate).

Daemon Control (daemon.*)

daemon.daemonize

  • Default: false
  • Type: boolean
  • Description: Run ExaBGP in the background as a daemon process.
env exabgp.daemon.daemonize=true exabgp server config.conf

daemon.pid

  • Default: (empty)
  • Type: string (file path)
  • Description: Where to write the PID file.
env exabgp.daemon.pid=/var/run/exabgp.pid exabgp server config.conf

daemon.user

  • Default: nobody
  • Type: string (username)
  • Description: User to drop privileges to after binding to ports.

daemon.drop

  • Default: true
  • Type: boolean
  • Description: Drop privileges before forking API processes.

daemon.umask

  • Default: 0137
  • Type: octal
  • Description: Daemon umask — governs permissions of log files and other created files.

Logging (log.*)

log.enable

  • Default: true
  • Type: boolean
  • Description: Enable logging to file or syslog.

log.level

  • Default: INFO
  • Type: string
  • Values: DEBUG, INFO, WARNING, ERROR, CRITICAL
  • Description: Minimum log level to display.
env exabgp.log.level=DEBUG exabgp server config.conf

log.destination

  • Default: stdout
  • Type: string
  • Description: Where to send log output.
Value Description
stdout Standard output (default)
stderr Standard error
syslog Local syslog
host:<location> Remote syslog server
<filename> File path 
env exabgp.log.destination=/var/log/exabgp.log exabgp server config.conf
env exabgp.log.destination=syslog exabgp server config.conf

log.short

  • Default: true
  • Type: boolean
  • Description: Use short log format (no timestamp, level, PID, or source prefix).

log.all

  • Default: false
  • Type: boolean
  • Description: Report debug information for everything (overrides individual log category settings below).

Log Categories (log.<category>)

Fine-grained control over which subsystems produce log output:

Variable Default Description
log.configuration true Configuration file parsing
log.reactor true Signal handling, reloads
log.daemon true PID changes, forking
log.processes true Forked process handling
log.network true TCP/IP, network state
log.statistics true Packet statistics
log.packets false BGP packets (verbose!)
log.rib false Local route changes
log.message false Route announcements on reload
log.timers false Keepalive timers
log.routes false Received routes
log.parser false BGP message parsing 
# Enable packet-level debugging
env exabgp.log.packets=true exabgp server config.conf

# Enable all log categories at once
env exabgp.log.all=true exabgp server config.conf

API & Processes (api.*)

api.ack

  • Default: true
  • Type: boolean
  • Description: Acknowledge API commands and report issues. When enabled, ExaBGP sends done or error responses after each command.
# Disable ACK for simple fire-and-forget scripts
env exabgp.api.ack=false exabgp server config.conf

Note: ACK can also be controlled at runtime with enable-ack, disable-ack, and silence-ack commands (5.x/6.x). See ACK Feature Documentation.

api.version

  • Default: 6
  • Type: integer (4 or 6)
  • Description: API format version. Version 6 uses structured JSON-only commands (peer * announce route ...). Version 4 is the legacy format with text/JSON (announce route ...).
# Use legacy v4 API format
env exabgp.api.version=4 exabgp server config.conf

api.encoder

  • Default: json
  • Type: string (json or text)
  • Description: EXPERIMENTAL — Default encoder for external API communication.

api.compact

  • Default: false
  • Type: boolean
  • Description: Use shorter JSON encoding for IPv4/IPv6 Unicast NLRI.

api.chunk

  • Default: 1
  • Type: integer
  • Description: Maximum lines to print before yielding in show routes API command.

api.respawn

  • Default: true
  • Type: boolean
  • Description: Automatically respawn API processes if they die.

api.terminate

  • Default: false
  • Type: boolean
  • Description: Terminate ExaBGP if any API process dies.

api.cli

  • Default: true
  • Type: boolean
  • Description: Create a named pipe for CLI access.

api.pipename

  • Default: exabgp
  • Type: string
  • Description: Name to use for the ExaBGP named pipe (CLI).

api.socketname

  • Default: exabgp
  • Type: string
  • Description: Name to use for the ExaBGP Unix socket.

Reactor Control (reactor.*)

reactor.speed

  • Default: 1.0
  • Type: float
  • Description: Reactor event loop speed multiplier. Lower values = faster loop. Use only if you understand the code.

Caching (cache.*)

cache.attributes

  • Default: true
  • Type: boolean
  • Description: Cache all BGP attributes (configuration and wire format) for faster parsing.

cache.nexthops

  • Default: true
  • Type: boolean
  • Description: Cache route next-hops. Deprecated: next-hops are always cached regardless of this setting.

Profiling & Debugging (profile., pdb., debug.*)

profile.enable

  • Default: false
  • Type: boolean
  • Description: Enable profiling of the code.

profile.file

  • Default: (empty)
  • Type: string (file path)
  • Description: Profiling result file. Empty means stdout. Does not overwrite existing files.

pdb.enable

  • Default: false
  • Type: boolean
  • Description: On program fault, start Python interactive debugger (pdb).

debug.pdb

  • Default: false
  • Type: boolean
  • Description: Enable Python debugger on errors.

debug.memory

  • Default: false
  • Type: boolean
  • Description: Enable memory debugging output.

debug.configuration

  • Default: false
  • Type: boolean
  • Description: Raise exceptions on configuration parsing errors (instead of warnings).

debug.selfcheck

  • Default: false
  • Type: boolean
  • Description: Perform self-check on the configuration file.

debug.route

  • Default: (empty)
  • Type: string
  • Description: Decode a specific route using the configuration.

debug.defensive

  • Default: false
  • Type: boolean
  • Description: Generate random faults in the code intentionally (for testing fault tolerance).

debug.rotate

  • Default: false
  • Type: boolean
  • Description: Rotate configuration files on reload (signal).

debug.timing

  • Default: false
  • Type: boolean
  • Description: Enable timing instrumentation for asyncio reactor performance analysis.

When enabled, logs warnings for slow operations:

  • Main loop iterations > 100ms
  • Peer message loop iterations > 50ms
  • Peer establishment > 5000ms
env exabgp.debug.timing=true exabgp server config.conf

Docker and Container Usage

Environment variables are particularly useful in Docker/Kubernetes deployments:

Docker Compose:

services:
  exabgp:
    image: exabgp/exabgp:latest
    environment:
      - exabgp.daemon.daemonize=false
      - exabgp.log.level=INFO
      - exabgp.log.destination=stdout
      - exabgp.api.ack=true
      - exabgp.api.encoder=json
    volumes:
      - ./exabgp.conf:/etc/exabgp/exabgp.conf

Kubernetes ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: exabgp-env
data:
  exabgp.daemon.daemonize: "false"
  exabgp.log.level: "INFO"
  exabgp.api.encoder: "json"

Examples

Production Daemon

#!/bin/bash
export exabgp.daemon.daemonize=true
export exabgp.daemon.pid=/var/run/exabgp.pid
export exabgp.daemon.user=exabgp

export exabgp.log.level=INFO
export exabgp.log.destination=/var/log/exabgp.log
export exabgp.log.routes=true

export exabgp.api.ack=true

exabgp server /etc/exabgp/exabgp.conf

Debug Mode

#!/bin/bash
export exabgp.daemon.daemonize=false
export exabgp.log.level=DEBUG
export exabgp.log.destination=stdout
export exabgp.log.packets=true
export exabgp.log.routes=true

exabgp server /etc/exabgp/exabgp.conf

Fire-and-Forget API

#!/bin/bash
export exabgp.daemon.daemonize=false
export exabgp.log.level=WARNING
export exabgp.api.ack=false

exabgp server /etc/exabgp/exabgp.conf

High-Performance Setup

#!/bin/bash
export exabgp.cache.attributes=true
export exabgp.reactor.speed=0.5
export exabgp.log.level=WARNING
export exabgp.log.routes=false

exabgp server /etc/exabgp/exabgp.conf

Quick Reference

All environment variables at a glance:

Variable Default Description
tcp.attempts 0 Per-peer connection attempt limit (0=unlimited)
tcp.bind (empty) Local bind addresses
tcp.port 179 BGP listen port
tcp.delay 0 Startup delay modulo
tcp.once false Single attempt (deprecated)
bgp.openwait 60 OPEN wait timeout (seconds)
bgp.passive false Passive-only mode
daemon.daemonize false Background mode
daemon.pid (empty) PID file path
daemon.user nobody Drop privileges to user
daemon.drop true Drop privileges
daemon.umask 0137 File creation mask
log.enable true Enable logging
log.level INFO Log level
log.destination stdout Log output target
log.short true Short log format
log.all false Enable all log categories
log.configuration true Log config parsing
log.reactor true Log reactor events
log.daemon true Log daemon events
log.processes true Log process events
log.network true Log network events
log.statistics true Log statistics
log.packets false Log BGP packets
log.rib false Log RIB changes
log.message false Log messages on reload
log.timers false Log keepalive timers
log.routes false Log received routes
log.parser false Log message parsing
api.ack true Command acknowledgment
api.version 6 API format version (4 or 6)
api.encoder json Default encoder
api.compact false Compact JSON
api.chunk 1 Show routes chunk size
api.respawn true Respawn dead processes
api.terminate false Exit on process death
api.cli true Enable CLI pipe
api.pipename exabgp CLI pipe name
api.socketname exabgp Unix socket name
reactor.speed 1.0 Event loop speed
cache.attributes true Cache attributes
cache.nexthops true Cache next-hops (deprecated)
profile.enable false Enable profiling
profile.file (empty) Profile output file
pdb.enable false PDB on fault
debug.pdb false PDB on error
debug.memory false Memory debugging
debug.configuration false Strict config parsing
debug.selfcheck false Config self-check
debug.route (empty) Route decode debug
debug.defensive false Random fault injection
debug.rotate false Rotate config on reload
debug.timing false Timing instrumentation

See Also

Configuration

API

Operations

Deployment

Home

Getting Started

Configuration

API

Address Families

Features

Use Cases

Tools

Operations

Reference

Integration

Migration

Community

External

Clone this wiki locally