Skip to content

Breaking Changes

Jump to bottom
Thomas Mangin edited this page Feb 2, 2026 · 8 revisions

Breaking Changes Reference

Complete reference of breaking changes across ExaBGP versions

This document lists all breaking changes in ExaBGP's history to help you understand version compatibility and plan upgrades.

Table of Contents

What is a Breaking Change?

A breaking change is a modification that requires users to update their:

  • API programs (code changes)
  • Configuration files (syntax changes)
  • Command-line scripts (argument changes)
  • Integration workflows (behavioral changes)

Not breaking:

  • Bug fixes
  • New features (when opt-in)
  • Performance improvements
  • Internal refactoring

ExaBGP 6.0.0 (main branch)

Version: ExaBGP 5.x → 6.0.0 Release: Development (main branch) Severity: 🟡 MEDIUM - Breaking changes, but migration tools available

⚠️ Breaking Changes in 6.0.0

ExaBGP 6.0.0 brings modernization with the async reactor and Python 3.12+ requirement.

1. Python Version Requirements (CRITICAL)

ExaBGP 5.x:

  • ✅ Python 3.8+ minimum

ExaBGP 6.0.0:

  • ❌ Python 3.7-3.11 dropped
  • ✅ Python 3.12+ minimum
  • ✅ Python 3.13 and 3.14 supported

Who is affected: Everyone running Python < 3.12

Migration required: Upgrade Python before upgrading ExaBGP

2. Async Reactor Now Default (LOW IMPACT)

ExaBGP 5.x:

  • Generator-based reactor (default)

ExaBGP 6.0.0:

  • Async/await-based reactor (default and only mode)
  • No separate legacy reactor toggle option
  • Generators still work inside the async reactor (backward compatible)

Who is affected: All users (most won't notice any difference)

Migration required: Test workloads. Generator-based callbacks continue to work unchanged.

3. BGP-LS JSON API Changes (HIGH IMPACT)

IP Reachability TLV

ExaBGP 5.x:

{"bgp-ls": {"ip": "10.134.2.88"}}

ExaBGP 6.0.0:

{"bgp-ls": {"prefix": "10.134.2.88/30"}}

Changes:

  • Key renamed from ip to prefix
  • Now includes prefix length in CIDR notation
Adjacency SID

ExaBGP 5.x:

{"bgp-ls": {"sr-adj": {...}, "sr-adj": {...}}}

ExaBGP 6.0.0:

{"bgp-ls": {"sr-adjs": [{...}, {...}]}}

Changes:

  • Key renamed from sr-adj to sr-adjs
  • Now outputs as array of objects (valid JSON)
Remote Router ID

ExaBGP 5.x:

{"bgp-ls": {"remote-router-id": "192.0.2.1", "remote-router-id": "2001:db8::1"}}

ExaBGP 6.0.0:

{"bgp-ls": {"remote-router-ids": ["192.0.2.1", "2001:db8::1"]}}

Changes:

  • Key renamed from remote-router-id to remote-router-ids
  • IPv4 and IPv6 merged into single array (valid JSON)

Who is affected: Programs using JSON encoder with BGP-LS

Migration required: Update field names in parsers

New Features (Non-Breaking)

While not breaking changes, 6.0.0 adds major features:

  • ✅ Async Reactor - Modern async/await event loop
  • ✅ Shell Completion - Bash, Zsh, Fish support
  • ✅ Enhanced CLI - Tab completion, JSON pretty-printing
  • ✅ Health Monitoring - ping and status API commands
  • ✅ Migration Tool - exabgp migrate for automatic conversion
  • ✅ Type Annotations - Better IDE support

See 5.x → 6.0.0 Migration Guide for complete details.

ExaBGP 5.0.0 (Current Stable/LTS)

Version: ExaBGP 4.x → 5.0.0 Release: November 2024 Severity: 🔴 HIGH - Multiple breaking changes requiring careful migration

⚠️ Breaking Changes in 5.0.0

ExaBGP 5.0.0 introduces SIGNIFICANT breaking changes compared to 4.x. This is the largest release in ExaBGP history (871 commits, 920 files changed).

1. Python Version Requirements (CRITICAL)

ExaBGP 4.x:

  • Python 2.7 (deprecated but supported)
  • Python 3.6+

ExaBGP 5.0.0:

  • ❌ Python 2.x completely removed
  • ❌ Python 3.6-3.7 no longer supported
  • ✅ Python 3.8+ minimum (3.9+ recommended)
  • ✅ Python 3.13 tested and supported

Who is affected: Everyone running Python < 3.8

Migration required: Upgrade Python before upgrading ExaBGP

2. JSON API Format Changes (HIGH IMPACT)

AS-PATH Format Changed

ExaBGP 4.x:

{"attribute": {"as-path": [65001, 65002, 65003]}}

ExaBGP 5.0.0:

{"attribute": {"as-path": "[ 65001 65002 65003 ]"}}

Important: The string format encodes AS_PATH segment types with different brackets:

  • ( ) = AS_SEQUENCE (most common - ordered list of ASNs)
  • [ ] = AS_SET (unordered set of ASNs, used in aggregation)
  • {( )} = CONFED_SEQUENCE (confederation sequence)
  • {[ ]} = CONFED_SET (confederation set)

Example with multiple segment types:

{"attribute": {"as-path": "[ 65001 65002 ] ( 65003 65004 )"}}

This represents an AS_SET followed by an AS_SEQUENCE.

Who is affected: Programs using JSON encoder and parsing AS-PATH

Migration required: Update JSON parsers to:

  1. Handle AS-PATH as string instead of array
  2. Parse bracket types to identify segment types (if needed for your use case)
BGP-LS Field Names Changed

ExaBGP 4.x:

  • sr_capability_flags (underscore)
  • interface-address (singular)
  • neighbor-address (singular)

ExaBGP 5.0.0:

  • sr-capability-flags (hyphen)
  • interface-addresses (plural)
  • neighbor-addresses (plural)

Who is affected: Programs using JSON encoder with BGP-LS

Migration required: Update field names in parsers

3. Configuration Syntax Changes (MEDIUM IMPACT)

Route Refresh Command
  • 4.x: route refresh (space)
  • 5.0.0: route-refresh (hyphenated)
FlowSpec Fragment Syntax
  • 4.x: not-a-fragment
  • 5.0.0: !is-fragment
TCP Connection Attempts

⚠️ Note: tcp.attempts is an internal/debugging option, not recommended for production use.

  • 4.x: Environment variable exabgp.tcp.once=true
  • 5.0.0: Environment variable exabgp.tcp.attempts=1 (tcp.once removed)

Who is affected: Users setting the exabgp.tcp.once environment variable

Migration required: Update environment variable from exabgp.tcp.once to exabgp.tcp.attempts

Correct usage: Set as environment variable (export exabgp.tcp.attempts=1) or in INI config [exabgp.tcp] section. NOT as a neighbor-level tcp { } block.

4. Deprecated Features Removed (MEDIUM IMPACT)

Prefix-SID Type-2 and Type-4

ExaBGP 4.x:

  • Type-1 (Label-Index) ✅
  • Type-2 (deprecated) ⚠️
  • Type-3 (Originator SRGB) ✅
  • Type-4 (deprecated) ⚠️

ExaBGP 5.0.0:

  • Type-1 (Label-Index) ✅
  • Type-2 REMOVED ❌
  • Type-3 (Originator SRGB) ✅
  • Type-4 REMOVED ❌
  • Type-5 (SRv6 Locator) ✅ NEW
  • Type-6 (SRv6 Endpoint) ✅ NEW

Who is affected: Users of Prefix-SID Type-2 or Type-4

Migration required: Migrate to Type-1, Type-3, Type-5, or Type-6

Hostname Capability

ExaBGP 4.x: Sent by default ExaBGP 5.0.0: NOT sent by default (must explicitly enable)

Who is affected: Users relying on hostname capability

Migration required: Add explicit capability { hostname enable; }

Syslog Facility

ExaBGP 4.x: Facility syslog ExaBGP 5.0.0: Facility daemon

Who is affected: Syslog parsers and filters

Migration required: Update syslog configuration

New Features (Non-Breaking)

While not breaking changes, 5.0.0 adds major features:

  • ✅ SRv6 - Complete Segment Routing over IPv6
  • ✅ BGP-MUP - Mobile User Plane SAFI
  • ✅ RFC 9072 - Extended Optional Parameters Length
  • ✅ ACK Runtime Control - disable-ack, enable-ack, silence-ack commands
  • ✅ Neighbor Wildcards - neighbor * announce ...
  • ✅ Security Fixes - TOCTOU vulnerability fixed
  • ✅ Official Docker Images - ghcr.io/exa-networks/exabgp:5.0.0

See 4.x → 5.0.0 Migration Guide for complete details.

ExaBGP 4.x Series

No Breaking Changes

ExaBGP 4.x has maintained API and configuration compatibility throughout the 4.0 → 4.2.x series.

Stable versions:

  • 4.0.x → 4.1.x → 4.2.x (All compatible)
  • No breaking changes in API
  • No breaking changes in configuration syntax
  • Safe to upgrade within 4.x series

Minor changes (non-breaking):

  • New features added (opt-in)
  • Bug fixes
  • Performance improvements
  • New address family support (EVPN, BGP-LS, etc.)

ExaBGP 3.x → 4.x

Version: ExaBGP 3.4.x → 4.0.0 Release: ~2017 Severity: 🟡 MODERATE - Configuration and some API changes

Configuration Syntax Changes

ExaBGP 4.x introduced configuration syntax changes requiring file updates.

Impact: Configuration files need manual updates when upgrading from 3.x

Who Is Affected

✅ Affected:

  • Configuration files from 3.x
  • Some API command syntax
  • JSON output format consumers

❌ Not affected:

  • New deployments starting with 4.x
  • Programs written for 4.x+

Command-Line Changes

Command-line arguments and behavior changed between 3.x and 4.x.

Impact: Shell scripts invoking ExaBGP may need updates

JSON Format Changes

JSON encoder output format changed between 3.x and 4.x.

Impact: Programs parsing JSON output need updates

Who Is Affected

✅ Affected:

  • Programs using encoder json
  • Scripts parsing ExaBGP JSON output
  • Monitoring integrations reading JSON

Migration Strategy

Upgrade path: 3.x → 4.2.x → 5.x (LTS - recommended)

Resources:

  • Version Differences - Detailed version comparison
  • Configuration examples in /etc/exabgp/ directory use 4.x/5.x syntax

Note: ExaBGP 3.x is deprecated and no longer maintained. All users should upgrade to 5.x (LTS).

Summary Table

All Breaking Changes by Version

Version Change Type Severity Workaround Available?
5.x→6.0.0 Python 3.12+ required Runtime 🔴 Critical ❌ No (upgrade Python)
5.x→6.0.0 Async reactor default Runtime 🟢 Low ✅ Yes (generators still work)
5.x→6.0.0 BGP-LS ip → prefix API Output 🔴 High ❌ No (parser updates)
5.x→6.0.0 BGP-LS sr-adj → sr-adjs API Output 🔴 High ❌ No (parser updates)
5.x→6.0.0 BGP-LS remote-router-id → remote-router-ids API Output 🔴 High ❌ No (parser updates)
4.x→5.0.0 Python 3.8+ required Runtime 🔴 Critical ❌ No (upgrade Python)
4.x→5.0.0 AS-PATH JSON format API Output 🔴 High ❌ No (parser updates)
4.x→5.0.0 BGP-LS field names API Output 🔴 High ❌ No (parser updates)
4.x→5.0.0 Config syntax changes Config 🟡 Medium ❌ No (manual updates)
4.x→5.0.0 Prefix-SID Type-2/4 removed Protocol 🟡 Medium ⚠️ Yes (use Type-1/3/5/6)
4.x (No breaking changes) - - -
3.x→4.x Configuration syntax Config 🟡 Moderate ❌ No (manual migration)
3.x→4.x CLI arguments CLI 🟡 Moderate ❌ No (script updates)
3.x→4.x JSON format API Output 🟡 Moderate ❌ No (parser updates)

Compatibility Matrix

API Program Compatibility

API Program Written For Runs on 3.x Runs on 4.x Runs on 5.0.0 Runs on 6.0.0
ExaBGP 3.x ✅ Yes ⚠️ Maybe ⚠️ Maybe ⚠️ Maybe
ExaBGP 4.x (Text API) ❌ No ✅ Yes ✅ Yes ✅ Yes
ExaBGP 4.x (JSON API) ❌ No ✅ Yes ❌ No (AS-PATH changed) ❌ No (AS-PATH changed)
ExaBGP 5.x (Text API) ❌ No ✅ Yes ✅ Yes ✅ Yes
ExaBGP 5.x (JSON API) ❌ No ❌ No ✅ Yes ⚠️ BGP-LS changed
ExaBGP 6.0.0 (Text API) ❌ No ✅ Yes ✅ Yes ✅ Yes
ExaBGP 6.0.0 (JSON API) ❌ No ❌ No ⚠️ BGP-LS incompatible ✅ Yes

Important:

  • JSON API programs from 4.x will NOT work on 5.0.0+ without updates (AS-PATH format changed)
  • JSON API programs from 5.x using BGP-LS will NOT work on 6.0.0 without updates (field names changed)
  • Text API programs are compatible across versions

Configuration File Compatibility

Config Written For Works on 3.x Works on 4.x Works on 5.0.0 Works on 6.0.0
ExaBGP 3.x ✅ Yes ❌ No ❌ No ❌ No
ExaBGP 4.x ❌ No ✅ Yes ⚠️ Mostly ⚠️ Mostly
ExaBGP 5.x ❌ No ⚠️ Mostly ✅ Yes ✅ Yes
ExaBGP 6.0.0 ❌ No ⚠️ Mostly ✅ Yes ✅ Yes

Important:

  • 4.x configs work on 5.0.0+ with minor updates: route refresh → route-refresh, not-a-fragment → !is-fragment
  • 5.x configs work on 6.0.0 without changes
  • Use exabgp migrate conf to automatically convert configurations

Migration Paths

From 5.x to 6.0.0

Migration recommended for new features. 6.0.0 has some breaking changes.

  1. Verify Python version (must be 3.12+)
  2. Run migration tool (exabgp migrate conf -f 5 -t main)
  3. Update BGP-LS JSON parsers (if using BGP-LS with JSON)
  4. Test async reactor (only mode in 6.0.0)
  5. Test thoroughly in staging environment
  6. Deploy to production with rollback plan

Estimated effort:

  • Text API only: 30 minutes (test async reactor)
  • JSON API (no BGP-LS): 30 minutes
  • JSON API (with BGP-LS): 2-4 hours (parser updates)

Resources: ExaBGP 5.x → 6.0.0 Migration Guide

From 3.x to 4.x

  1. Update configuration files (manual syntax changes required)
  2. Test in non-production environment
  3. Update API programs if using JSON parser
  4. Update shell scripts if using CLI
  5. Deploy to production

Resources:

From 4.x to 5.0.0

Migration required. 5.0.0 has breaking changes from 4.x.

  1. Verify Python version (must be 3.8+)
  2. Update configuration syntax (route-refresh, FlowSpec)
  3. Update JSON API parsers (AS-PATH, BGP-LS field names)
  4. Check for deprecated features (Prefix-SID Type-2/4)
  5. Update environment variables (exabgp.tcp.once → exabgp.tcp.attempts, if used)
  6. Test thoroughly in staging environment
  7. Deploy to production with rollback plan

Estimated effort:

  • Text API only: 1-2 hours (config updates)
  • JSON API: 4-8 hours (config + parser updates)

Resources: ExaBGP 4.x → 5.0.0 Migration Guide

From 3.x to 6.0.0 (Direct Upgrade)

Not recommended. Use multi-step migration:

  1. 3.x → 4.x: Update config, test thoroughly
  2. 4.x → 5.x: Update Python to 3.8+, JSON parsers
  3. 5.x → 6.0.0: Update Python to 3.12+, BGP-LS parsers

Why multi-step?

  • Multiple breaking changes across versions
  • Better to isolate issues and test separately
  • Easier rollback if problems occur

From 3.x to 5.0.0 (Direct Upgrade)

Not recommended. Use two-step migration:

  1. 3.x → 4.x: Update config, test thoroughly (see 3.x → 4.x guide)
  2. 4.x → 5.0.0: Update Python, config, JSON parsers (see 4.x → 5.0.0 guide)

Why two steps?

  • Both upgrades have breaking changes
  • Better to isolate issues and test separately
  • Easier rollback if problems occur

Recommended: Upgrade directly to 5.0.0 (new LTS) or via 4.x for staged migration.

Future Breaking Changes

ExaBGP Development Policy

  • 6.0.0 (main branch): Development branch with latest features
  • 5.0.0: LTS (Long-Term Support) - stable, production recommended
  • 4.x branch: Maintenance mode - critical fixes only, no new features
  • Major versions: Reserved for breaking changes

How to Stay Updated

Testing for Breaking Changes

Before Upgrading Production

Checklist:

  1. Read release notes for your target version
  2. Check this document for breaking changes
  3. Test in isolated environment:
    • Configuration file loads without errors
    • BGP sessions establish correctly
    • API programs work as expected
    • No unexpected behavior changes
  4. Run parallel (new version alongside old, if possible)
  5. Monitor logs for errors after upgrade
  6. Have rollback plan ready

Rollback Testing

Before upgrading production:

  1. Document current version: exabgp --version
  2. Backup configuration files
  3. Test downgrade procedure in non-production
  4. Verify rollback works end-to-end
  5. Document rollback steps for operations team

Version Terminology

Term Meaning Example
Major version Breaking changes possible 3.x → 4.x → 5.0.0
Minor version New features, backwards-compatible 4.0 → 4.1 → 4.2
Patch version Bug fixes only 4.2.0 → 4.2.1 → 4.2.22 or 5.0.0 → 5.0.1

ExaBGP follows semantic versioning principles:

  • Major version bump = breaking changes
  • Minor version bump = new features (compatible)
  • Patch version bump = bug fixes (compatible)

See Also

Migration Guides

API Documentation

Operations

👻 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