Migration Guide

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
• Migration Guides
• Breaking Changes Reference
• Quick Version Comparison
• Getting Help

---

Current Version Recommendations

Version	Status	Recommendation
5.x/main	Development	Use for testing new features. Same API and config as 4.x.
4.x	Stable (Recommended)	Production-ready. All documentation examples work as-is.
3.x	Deprecated	No longer maintained. Upgrade to 4.x immediately.

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

---

Migration Guides

ExaBGP 4.x → 5.x (Current Development)

Migration from 4.x to 5.x - Understanding the differences

No Breaking Changes: ExaBGP 4.x and 5.x/main are fully compatible.

• ✅ Configuration files: 100% compatible, no changes needed
• ✅ API commands: 100% compatible, same syntax
• ✅ ACK feature: Available in BOTH 4.x and 5.x (default=true in both)
• ✅ No migration required: Existing programs work on both versions
• 📖 Full Details: See 4.x → 5.x Comparison

Recommendation: Stay on 4.x for production unless you need specific features from main/5.x.

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:

• 3.x → 4.x Migration Guide - Step-by-step upgrade guide
• Version Differences - Detailed comparison

---

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

API Behavior (Same in Both Versions)

ExaBGP 4.x and 5.x/main (ACK enabled by default in both):

# API command (same syntax in both versions)
announce route 100.64.1.0/24 next-hop 192.0.2.1
# ExaBGP sends: done

# To disable ACK:
# Option 1: Environment variable (4.x and 5.x)
# Set exabgp.api.ack = false in environment

# Option 2: Runtime commands (5.x/main only)
# Send: disable-ack or silence-ack

Note: The ACK feature is available in both 4.x and 5.x with the same default behavior (enabled). ExaBGP 5.x/main adds runtime control commands.

Feature Comparison

Feature	3.x	4.x	5.x/main
ACK responses	❌ No	✅ Yes (default=true)	✅ Yes (default=true)
JSON encoder	Basic	Full	Full
FlowSpec	Limited	Full RFC 5575	Full RFC 5575 + RFC 8955
Configuration	Different	Current	Current
API compatibility	Different	✅ Stable	✅ Same as 4.x

---

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

• Quick Start Guide - Get started with ExaBGP 4.x
• First BGP Session - Version differences explained
• API Overview - API architecture and ACK feature
• Common Pitfalls - 25+ common mistakes and solutions

Community Support

• GitHub Issues: https://github.com/Exa-Networks/exabgp/issues
• Slack: https://exabgp.slack.com/
• Mailing List: See GitHub repo

---

See Also

• Installation Guide - Install/upgrade ExaBGP
• Configuration Syntax - Complete configuration reference
• API Overview - API architecture and features
• Debugging Guide - Troubleshooting migrations

---

👻 Ghost written by Claude (Anthropic AI)