# 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](#overview)
- [Naming Convention](#naming-convention)
- [Network & Connection (tcp.*)](#network--connection-tcp)
- [BGP Protocol (bgp.*)](#bgp-protocol-bgp)
- [Daemon Control (daemon.*)](#daemon-control-daemon)
- [Logging (log.*)](#logging-log)
- [API & Processes (api.*)](#api--processes-api)
- [Reactor Control (reactor.*)](#reactor-control-reactor)
- [Caching (cache.*)](#caching-cache)
- [Profiling & Debugging (profile.*, pdb.*, debug.*)](#profiling--debugging-profile-pdb-debug)
- [Docker and Container Usage](#docker-and-container-usage)
- [Examples](#examples)
- [See Also](#see-also)

---

## 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.

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

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

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

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

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

```bash
env exabgp.daemon.daemonize=true exabgp server config.conf
```

### daemon.pid
- **Default:** (empty)
- **Type:** string (file path)
- **Description:** Where to write the PID file.

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

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

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

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

```bash
# 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-Overview#command-acknowledgment-ack-feature).

### 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 ...`).

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

```bash
env exabgp.debug.timing=true exabgp server config.conf
```

---

## Docker and Container Usage

Environment variables are particularly useful in Docker/Kubernetes deployments:

**Docker Compose:**
```yaml
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:**
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: exabgp-env
data:
  exabgp.daemon.daemonize: "false"
  exabgp.log.level: "INFO"
  exabgp.api.encoder: "json"
```

---

## Examples

### Production Daemon

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

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

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

```bash
#!/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
- [Configuration Syntax](Configuration-Syntax) - Configuration file format
- [Directives Reference](Directives-Reference) - All configuration directives

### API
- [API Overview](API-Overview) - API programming guide
- [Production Best Practices](Production-Best-Practices) - Production deployment

### Operations
- [Debugging](Debugging) - Troubleshooting guide
- [Monitoring](Monitoring) - Production monitoring
- [Log Analysis](Log-Analysis) - Log file analysis

### Deployment
- [Docker](Docker) - Docker deployment
- [Kubernetes](Kubernetes) - Kubernetes integration

---