exabgp migration

Pre-Alpha. This page describes behavior that may change.

This is the first page to read if you already run ExaBGP. Ze ships two tools that, between them, get most existing setups running with very little manual work: a config converter (ze config migrate) and a bridge plugin (ze exabgp plugin) that runs your existing process scripts unchanged. The order matters: convert the config first, then keep your scripts running through the bridge while you decide which ones to port to native Ze plugins.

Convert the config

ze config migrate --dry-run exabgp.conf       # Preview what changes
ze config migrate exabgp.conf -o ze.conf      # Write the converted file
ze config validate ze.conf                    # Verify against the YANG schema

The converter is a chain of named transformations. You can see the list with ze config migrate --list. Each one renames one piece of legacy ExaBGP syntax into its current Ze form. The most visible ones rename neighbor blocks to peer, lift root-level globs into template { match }, and rename template { neighbor } to template { group }. You can read the full list in the in-tree migration guide linked at the bottom.

One automatic change is worth knowing about. The converter adds prefix { maximum 10000; } to every address family it touches. ExaBGP does not have per-family prefix limits and Ze requires them (RFC 4486). 10,000 is a conservative starting point. Edit the value before you go anywhere near a full table peer.

What the converter cannot do

A few ExaBGP features are detected and warned about, but not converted. The non-standard multi-session capability and the ExaBGP-specific operational block are the main ones. Watchdog groups and some split configurations may need manual edits. None of these block migration. They produce warnings, the rest of the file converts, and you decide what to do with the gaps.

The neighbor qualifier syntax (neighbor <ip> local-as <asn> announce ...) for targeting one of several sessions to the same peer does not exist in Ze. Ze commands apply to every session matching the peer IP. If you depend on multi-session targeting, raise an issue.

Run your existing scripts through the bridge

You do not need to rewrite plugins to migrate. Wrap any existing ExaBGP process script with ze exabgp plugin and Ze will run it as if it were ExaBGP itself.

plugin {
    external my-script {
        run "ze exabgp plugin --family ipv4/unicast /opt/scripts/my-plugin.py"
        encoder json
    }
}

bgp {
    peer upstream {
        connection { remote { ip 10.0.0.1; } }
        session    { asn { remote 65001; } }
        process my-script {
            receive [ update state ]
        }
    }
}

The bridge translates Ze JSON events into ExaBGP JSON in one direction, and ExaBGP text commands into Ze commands in the other. Your script does not know it is talking to Ze. The bridge also injects a peer <addr> flush after each route command, so you do not see ExaBGP-style "I sent that update an instant ago" races.

A practical workflow

The shortest path that works is six steps.

1. ze config migrate --dry-run to see what will change.
2. ze config migrate -o new.conf to write the converted file.
3. Read every prefix { maximum } line and adjust to your real route counts.
4. ze config validate new.conf.
5. Update run directives so any script lines start with ze exabgp plugin.
6. Start Ze, watch the sessions come up, and only then start porting plugins.

Port plugins to native Ze when you actually need something the bridge does not give you: RPKI events, the cache commands, the commit workflow, or the lower-latency in-process Go SDK. The bridge has measurable overhead and an extra translation surface, but it is honest about what it does and it is the cheapest way to keep production moving while you migrate.

See also

• Quick start for the rest of the first-peer-up flow.
• BGP peers for the configuration reference once you are off ExaBGP syntax.
• ExaBGP Migration Walkthrough for a complete worked example.

Adapted from main/docs/guide/exabgp-migration.md, main/docs/config-migration.md, and main/docs/exabgp/exabgp-differences.md.