# 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?](#what-is-a-breaking-change)
- [ExaBGP 6.0.0 (main branch)](#exabgp-600-main-branch)
- [ExaBGP 5.0.0 (Current Stable/LTS)](#exabgp-500-current-stablelts)
- [ExaBGP 4.x Series](#exabgp-4x-series)
- [ExaBGP 3.x → 4.x](#exabgp-3x--4x)
- [Summary Table](#summary-table)
- [Compatibility Matrix](#compatibility-matrix)

---

## 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**:
```json
{"bgp-ls": {"ip": "10.134.2.88"}}
```

**ExaBGP 6.0.0**:
```json
{"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**:
```json
{"bgp-ls": {"sr-adj": {...}, "sr-adj": {...}}}
```

**ExaBGP 6.0.0**:
```json
{"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**:
```json
{"bgp-ls": {"remote-router-id": "192.0.2.1", "remote-router-id": "2001:db8::1"}}
```

**ExaBGP 6.0.0**:
```json
{"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](From-5.x-to-6.x) 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**:
```json
{"attribute": {"as-path": [65001, 65002, 65003]}}
```

**ExaBGP 5.0.0**:
```json
{"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**:
```json
{"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](From-4.x-to-5.x) 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](First-BGP-Session#exabgp-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-5.x-to-6.x)**

---

### 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**:
- **[3.x → 4.x Migration Guide](From-3.4-to-4.x)** - Complete step-by-step guide
- [Version Differences](First-BGP-Session#exabgp-version-differences) - Detailed comparison

---

### 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-4.x-to-5.x)

---

### 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](From-3.4-to-4.x))
2. **4.x → 5.0.0**: Update Python, config, JSON parsers (see [4.x → 5.0.0 guide](From-4.x-to-5.x))

**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

- **GitHub Releases**: https://github.com/Exa-Networks/exabgp/releases
- **CHANGELOG**: Check repository CHANGELOG.rst
- **Slack**: https://exabgp.slack.com/
- **Mailing List**: See GitHub repo

---

## 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

- **[Migration Guide](Migration-Guide)** - Main migration entry page
- **[Migration from 5.x to 6.0.0](From-5.x-to-6.x)** - Complete 6.0.0 migration guide
- **[Migration from 4.x to 5.0.0](From-4.x-to-5.x)** - Complete 5.0.0 migration guide
- **[Version Differences](First-BGP-Session#exabgp-version-differences)** - Complete version comparison

### API Documentation

- **[API Overview](API-Overview)** - API architecture and ACK feature
- **[Common Pitfalls](Common-Pitfalls)** - Common mistakes (including version issues)

### Operations

- **[Debugging Guide](Debugging)** - Troubleshooting after upgrades
- **[Production Best Practices](Production-Best-Practices)** - Safe deployment strategies

---