Skip to content

Breaking Changes

Jump to bottom
Thomas Mangin edited this page Nov 15, 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.x/main (Development)

No Breaking Changes

ExaBGP main/5.x has NO breaking changes compared to 4.x.

  • ✅ Configuration files: 100% compatible
  • ✅ API commands: 100% compatible
  • ✅ ACK feature: Available in BOTH 4.x and 5.x (default=true in both)
  • ✅ No migration required

Key point: The ACK feature is not a 5.x-only feature. It has been available in ExaBGP 4.x since at least version 4.0/4.1 with the same default (enabled).

See ExaBGP 4.x vs 5.x/main for details on the differences (which are primarily code quality improvements, not breaking changes).

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?
5.x (No breaking changes) - - -
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.x/main
ExaBGP 3.x ✅ Yes ⚠️ Maybe ⚠️ Maybe
ExaBGP 4.x ❌ No ✅ Yes ✅ Yes
ExaBGP 5.x/main ❌ No ✅ Yes ✅ Yes

Note: 4.x and 5.x/main have identical API behavior. Programs work on both.

Configuration File Compatibility

Config Written For Works on 3.x Works on 4.x Works on 5.x/main
ExaBGP 3.x ✅ Yes ❌ No ❌ No
ExaBGP 4.x ❌ No ✅ Yes ✅ Yes
ExaBGP 5.x/main ❌ No ✅ Yes ✅ Yes

Note: Configuration files and API programs for 4.x and 5.x/main are 100% compatible.

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.x/main

No migration needed. 4.x and 5.x/main are fully compatible.

  1. Install 5.x/main
  2. Use your existing configuration (100% compatible)
  3. Use your existing API programs (100% compatible)

Note: 5.x/main is a development branch. For production, stay on 4.x (stable).

Resources: ExaBGP 4.x vs 5.x/main

From 3.x to 5.x/main (Direct Upgrade)

Not recommended. Use two-step migration:

  1. 3.x → 4.x: Update config, test thoroughly
  2. 4.x → 5.x/main: No changes needed (optional)

Why two steps?

  • 3.x → 4.x has breaking changes (config syntax)
  • Better to isolate issues
  • 4.x is stable and recommended for production anyway

Recommended: Upgrade to 4.x and stay there for production use.

Future Breaking Changes

ExaBGP Development Policy

  • 4.x branch: Stable, no breaking changes planned
  • 5.x/main branch: Development branch, may introduce changes
  • Major versions: Reserved for 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 allowed 3.x → 4.x → 5.x
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

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