Skip to content

Breaking Changes

Jump to bottom
Thomas Mangin edited this page Nov 17, 2025 · 9 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 5.0.0 (Current Stable)

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
  • 4.x: tcp.once true
  • 5.0.0: tcp.attempts 1 (tcp.once removed)

Who is affected: Configuration files using these directives

Migration required: Update configuration syntax

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 (latest stable) → 5.x (if needed)

Resources:

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

Note: ExaBGP 3.x is deprecated and no longer maintained. All users should upgrade to 4.x.

Summary Table

All Breaking Changes by Version

Version Change Type Severity Workaround Available?
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 main (dev)
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.0.0 (Text API) ❌ No ✅ Yes ✅ Yes ✅ Yes
ExaBGP 5.0.0 (JSON API) ❌ No ❌ No (AS-PATH incompatible) ✅ Yes ✅ Yes

Important: JSON API programs from 4.x will NOT work on 5.0.0 without updates (AS-PATH format changed). Text API programs are compatible.

Configuration File Compatibility

Config Written For Works on 3.x Works on 4.x Works on 5.0.0 Works on main (dev)
ExaBGP 3.x ✅ Yes ❌ No ❌ No ❌ No
ExaBGP 4.x ❌ No ✅ Yes ⚠️ Mostly (minor syntax changes) ⚠️ Mostly (minor syntax changes)
ExaBGP 5.0.0 ❌ No ⚠️ Mostly (reverse compat) ✅ Yes ✅ Yes

Important: 4.x configs work on 5.0.0 with minor updates: route refresh → route-refresh, not-a-fragment → !is-fragment, tcp.once → tcp.attempts

Migration Paths

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, tcp.attempts)
  3. Update JSON API parsers (AS-PATH, BGP-LS field names)
  4. Check for deprecated features (Prefix-SID Type-2/4, tcp.once)
  5. Test thoroughly in staging environment
  6. 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 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

  • 5.0.0: LTS (Long-Term Support) - new features, bug fixes, security updates
  • 4.x branch: Maintenance mode - critical fixes only, no new features
  • main branch: Development branch, may introduce changes before next release
  • Major versions: Reserved for breaking changes (5.0.0 introduced breaking changes, next: 6.x if needed)

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

Configuration

API

Address Families

Features

Use Cases

Tools

Operations

Reference

Integration

Migration

Community

External

Clone this wiki locally