Skip to content

Migration Guide

Jump to bottom
Thomas Mangin edited this page Jan 19, 2026 · 4 revisions

Migration Guide

Comprehensive guide for upgrading between ExaBGP versions

ExaBGP has evolved through several major versions, each introducing important changes. This guide helps you navigate upgrades safely.

Table of Contents

Current Version Recommendations

Version Status Recommendation
6.0.0 (main) Development Latest features: async reactor, shell completion, enhanced CLI. Requires Python 3.12+.
5.x Stable LTS (Recommended) Production-ready. Long-Term Support. Requires Python 3.8+.
4.x Maintenance Critical fixes only. Upgrade to 5.x recommended.
3.x Deprecated No longer maintained. Upgrade immediately.

New users: Start with ExaBGP 5.x for production use.

Adventurous users: Try 6.0.0 (main) for latest features, but test thoroughly.

Migration Guides

ExaBGP 5.x → 6.0.0 (main branch)

Migration from 5.x to 6.x - Complete migration guide

Breaking Changes:

  • ❌ Python 3.12+ required (3.7-3.11 dropped)
  • ⚠️ Async reactor only (legacy reactor removed)
  • ⚠️ BGP-LS JSON changes (ip→prefix, sr-adj→sr-adjs, remote-router-id→remote-router-ids)

New Features:

  • ✅ Shell completion for Bash, Zsh, Fish
  • ✅ Enhanced CLI with tab completion and JSON pretty-printing
  • ✅ Health monitoring API (session ping, daemon status commands)
  • ✅ Migration tool (exabgp migrate conf, exabgp migrate api)
  • ✅ Bridge mode - Run legacy v4/v5 scripts unchanged with --exec

Bridge Mode (run legacy scripts unchanged):

# Legacy scripts work with 6.0.0 via bidirectional transformation
exabgp migrate api -f 4 -t main --exec /path/to/legacy-script.py

# Or wrap scripts automatically during config migration
exabgp migrate conf -f 4 -t main --wrap-api old-config.conf | exabgp server -

Resources:

ExaBGP 4.x → 5.x

Migration from 4.x to 5.x - Complete migration guide

Breaking Changes:

  • ❌ Python 3.8+ required (Python 2 removed)
  • ⚠️ AS-PATH JSON format changed (array → string)
  • ⚠️ BGP-LS JSON field names changed
  • ⚠️ Configuration syntax (route refresh→route-refresh, etc.)
  • ⚠️ Prefix-SID Type-2/4 removed

New Features:

  • ✅ SRv6 support
  • ✅ BGP-MUP support
  • ✅ ACK runtime control commands
  • ✅ Neighbor wildcards (neighbor *)

Resources:

ExaBGP 3.x → 4.x

Migration from 3.x to 4.x - Complete migration guide with breaking changes

Major Breaking Changes:

  • ⚠️ Configuration syntax changes (manual updates required)
  • ⚠️ JSON output format changes (parser updates needed)
  • ⚠️ ACK feature introduced (programs may need updates)
  • ⚠️ Command-line argument changes

This is the primary breaking change in ExaBGP's history. 3.x is deprecated and no longer maintained.

Resources:

Breaking Changes Reference

All Breaking Changes - Complete historical reference

Quick reference document listing ALL breaking changes across ExaBGP versions:

  • API protocol changes
  • Configuration syntax changes
  • Command-line interface changes
  • Behavioral changes
  • Deprecations and removals

This document is useful for:

  • Understanding version compatibility
  • Planning upgrades
  • Troubleshooting legacy configurations
  • Reviewing ExaBGP's evolution

Quick Version Comparison

Feature Comparison

Feature 3.x 4.x 5.x 6.0.0
Python version 2.7/3.6+ 2.7/3.6+ 3.8+ 3.12+
ACK responses ❌ No ✅ Yes ✅ Yes ✅ Yes
ACK runtime control ❌ No ❌ No ✅ Yes ✅ Yes
JSON encoder Basic Full Full Full
FlowSpec Limited Full Full + RFC 8955 Full + RFC 8955
SRv6 ❌ No ❌ No ✅ Yes ✅ Yes
BGP-MUP ❌ No ❌ No ✅ Yes ✅ Yes
Async reactor ❌ No ❌ No ❌ Optional ✅ Default
Shell completion ❌ No ❌ No ❌ No ✅ Yes
Enhanced CLI ❌ No ❌ No Basic ✅ Full
Migration tool - - - ✅ Yes
Bridge mode (--exec) - - - ✅ Yes

API Command Format

ExaBGP 5.x and earlier:

# Action-first format
announce route 100.64.1.0/24 next-hop 192.0.2.1
neighbor 192.0.2.1 announce route 10.0.0.0/24 next-hop self

ExaBGP 6.0.0 (also supports 5.x format):

# Target-first format (recommended)
peer * announce route 100.64.1.0/24 next-hop 192.0.2.1
peer 192.0.2.1 announce route 10.0.0.0/24 next-hop self

# New health monitoring
session ping
daemon status

Getting Help

Before Migrating

  1. Read the migration guide for your version upgrade path
  2. Review breaking changes that might affect your deployment
  3. Test in non-production environment first
  4. Backup configurations before upgrading

Migration Resources

Community Support

See Also

👻 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