Guide

Route Injection

Ze supports injecting routes at runtime through text, hex, or base64 encoded UPDATE commands. Routes can be sent from the CLI, from external plugins, or from process scripts.

Injecting into the Local RIB

request bgp rib inject inserts a synthetic candidate into Ze's BGP RIB without requiring a live BGP session. If the route wins best-path selection, it continues through the system RIB and configured FIB backends.

ze cli -c "request bgp rib inject 192.0.2.10 ipv4/unicast 198.51.100.0/24 origin igp nexthop 127.0.0.1 med 42"
ze cli -c "show bgp rib best prefix 198.51.100.0/24"
ze cli -c "show rib"

Withdraw the same candidate with the matching synthetic peer, family, and prefix:

ze cli -c "request bgp rib withdraw 192.0.2.10 ipv4/unicast 198.51.100.0/24"

The bgp-rib and rib plugins provide best-path and system-RIB selection. On Linux, the fib-kernel plugin programs selected routes through netlink.

IPv6 next hops and extended next hop

An injected IPv6 route carries its IPv6 next hop in MP_REACH_NLRI. An injected IPv4 unicast route can also use an IPv6 next hop when the destination peer negotiated Extended Next Hop, the RFC 8950 capability historically defined by RFC 5549.

ze cli -c "request bgp rib inject 192.0.2.10 ipv4/unicast 198.51.100.0/24 origin igp nexthop 2001:db8::1"
ze cli -c "show bgp rib best prefix 198.51.100.0/24"

Ze stores the MP_REACH attribute with the synthetic candidate and recovers the next hop when selecting and forwarding it. show bgp rib best and show bgp rib received both display the recovered next hop: the attribute renderer falls back to the stored MP_REACH_NLRI whenever the legacy IPv4-only NEXT_HOP attribute (type 3) is absent, which is the case for every IPv6 next hop, native or extended.

Ze terminal lab

Follow a route from BGP RIB to Linux FIB

Inject one route, inspect BGP best-path selection, and verify Linux installed it with Ze's route protocol ID. Validation also proves withdrawal removes it.

Reproducible
Ze 26.10.0952 secondsLinux namespace labTerminalZe recorder Plain-text transcript
Read the demonstration transcript
$ ze cli -c 'request bgp rib inject 192.0.2.10 ipv4/unicast 198.51.100.0/24 origin igp nexthop 127.0.0.1 med 42'
$ ze cli -c 'show bgp rib best prefix 198.51.100.0/24 | no-more'
198.51.100.0/24
$ ip -details route show exact 198.51.100.0/24
198.51.100.0/24 ... proto 250

The route enters Ze's BGP RIB, wins best-path selection, reaches the protocol-independent system RIB, and is programmed into Linux with Ze's route protocol ID. The validator withdraws it and confirms kernel removal.

Text Format

Human-readable format with flat attribute declarations:

ze cli -c "send bgp upstream1 update text \
    origin igp \
    nhop 192.168.1.1 \
    local-preference 200 \
    as-path [ 65001 65002 ] \
    community [ 65000:100 no-export ] \
    nlri add 10.0.0.0/24 10.0.1.0/24"

Attribute Keywords

Attributes are flat: keyword followed by value. No set/add/del on attributes. add and del are NLRI-only operations (announce vs. withdraw).

Attribute Syntax Delete
origin origin igp / egp / incomplete --
nhop nhop 192.168.1.1 or nhop self --
med med 100 --
local-preference local-preference 200 --
as-path as-path [ 65000 65001 ] --
community community [ 65000:100 no-export ] --
large-community large-community [ 65000:1:1 ] --
extended-community extended-community [ rt:65000:100 ] --

Well-Known Communities

All IANA-registered well-known communities are accepted by name:

Name Value Reference
✕ 0xFFFFFF01 RFC 1997
✕ 0xFFFFFF02 RFC 1997
✕ 0xFFFFFF03 RFC 1997
nopeer 0xFFFFFF04 RFC 3765
graceful-shutdown 0xFFFF0000 RFC 8326
accept-own 0xFFFF0001 RFC 7611
route-filter-translated-v4 0xFFFF0002 IANA
route-filter-v4 0xFFFF0003 IANA
route-filter-translated-v6 0xFFFF0004 IANA
route-filter-v6 0xFFFF0005 IANA
llgr-stale 0xFFFF0006 RFC 9494
✕ 0xFFFF0007 RFC 9494
accept-own-nexthop 0xFFFF0008 IANA
standby-pe 0xFFFF0009 RFC 9026
blackhole 0xFFFF029A RFC 7999

Underscore variants (e.g., no_export, graceful_shutdown) and the shorthand gshut are also accepted. Tab completion in the config editor suggests all names.

Colon-Less FlowSpec Actions

Most extended communities carry their value after a colon, so extended-community splits on the first one. Three FlowSpec traffic actions (RFC 8955 Section 7) carry their whole meaning in the name and have no colon. They are accepted as written, in update text and in config alike, from one keyword table both parsers read.

Keyword Encoding Meaning
discard type 0x80, subtype 0x06, traffic-rate 0 Drop matching traffic
copy-to-nexthop type 0x08, subtype 0x00, value 1 Copy and redirect to next hop
redirect-to-nexthop-draft type 0x08, subtype 0x00, value 0 Redirect to next hop, pre-IETF draft
ze cli -c "send bgp upstream update text \
    origin igp nhop self \
    extended-community [ discard ] \
    mp ipv4/flow add <flowspec-nlri>"

copy-to-nexthop and redirect-to-nexthop-draft differ in one bit of the last octet, which is the copy semantic. An unknown keyword is refused with an error naming the keywords Ze accepts, derived from the table.

One Encoder Per FlowSpec Action

The actions that DO carry a value -- traffic-rate, traffic-action, traffic-marking, rt-redirect and redirect-to-IP -- are built in one place as well. Config, update text and the FlowSpec NLRI plugin call the same constructors, so the three surfaces accept the same values and put the same octets on the wire. Three copies of this vocabulary disagreed before: one wrote an out-of-range DSCP into the reserved bits, one dropped a zero-valued action, and one refused a 4-octet AS in a redirect the others encoded.

Next-Hop Self

nhop self resolves to the local address of each destination peer at wire time.

A next hop in fe80::/10 produces a 16-octet Next Hop field holding one link-local address. RFC 2545 Section 3 has no such form, and draft-ietf-idr-linklocal-capability defines it behind capability 77, so ze sends it only toward a peer whose session negotiated that capability. For IPv4 NLRI the draft's Section 5 asks for the capability AND RFC 8950 Extended Next Hop Encoding.

On any other session the route is left out of the announcement toward that peer and the skip is logged, which is what Section 4 asks for when no conformant next hop is left: "the BGP route MUST not be advertised to its peer". Enable it with session capability link-local-nexthop enable on the peer or its group, together with session link-local <fe80::...> on the peer or the group: ze refuses the capability without that address, at commit and at startup, because the draft requires a directly connected route's next hop to include ze's own Link-Local.

A Peer Never Receives Its Own Address as Next Hop

RFC 4271 Section 5.1.3: "A route originated by a BGP speaker SHALL NOT be advertised to a peer using an address of that peer as NEXT_HOP." Ze asks that question of the built body, after the export filter chain, on every rail that originates a next hop: configured static routes, default-originate, the RIB op-queue drain, the announce batch, and the RFC 9494 stale re-advertise.

The route is withheld from that one peer, and the refusal logs the peer, the next hop and the section. Ze does not rewrite the address: rewriting would invent a next hop nobody configured. Other peers matched by the same selector still receive the route. A relayed route refused this way is withdrawn from the withheld peer instead, together with the withdrawals in the same UPDATE, so the peer drops any earlier copy.

The same question is asked of a relayed route, where the address arrives as the third-party next hop Section 5.1.3 case 2 permits.

A Default Route Ze Cannot Build

default-originate sends 0.0.0.0/0 or ::/0 with the session's local address as next hop. An IPv4 default route whose only local address is IPv6, on a session that did not negotiate Extended Next Hop (RFC 8950), has no NEXT_HOP Ze can write, and RFC 4271 Section 5 makes NEXT_HOP mandatory for an UPDATE that carries NLRI. Ze then sends nothing for that family and logs a warning, default-originate: route refused, not sent, naming the peer, the prefix, the family, the next hop and the error. The line is limited to one per second for each peer; suppressed-since-last counts the refusals the limit swallowed. Give the peer an IPv4 local ip, or negotiate Extended Next Hop.

A Withdrawal Needs a Session That Advertised Something

RFC 4271 Section 4.3 identifies a withdrawn route "in the context of the BGP speaker - BGP speaker connection to which it has been previously advertised", so a session that has advertised nothing has no route for a withdrawal to name. Ze writes no UPDATE to such a peer, and the command names it:

warning: withdraw ipv4/unicast: withdrawal withheld: this session has advertised
no route to the peer: ipv4/unicast, peers 192.0.2.10

The command still answers done. Once the session has carried one UPDATE that makes any destination reachable, a configured route and a relayed one included, every later withdrawal is written, whether or not the peer holds the route named.

A script migrated from ExaBGP meets the same rule there, where it comes from include_withdraw.

An ExaBGP Script's Burst Nets Before the Wire

An ExaBGP API script that writes several commands in ONE write reads back the frames of the NET of that write, not one frame per line. ze's bridge takes the same unit: a withdrawal cancels an announce of the same route earlier in the same write, an announce cancels nothing, and the withdrawals of a write leave before its announces.

Two commands written in two separate writes never cancel each other, whatever the interval between them. See docs/architecture/exabgp-bridge.md.

NLRI Operations

The section keyword names the UPDATE section the routes travel in. nlri takes no family: it is IPv4 unicast in the NLRI and Withdrawn Routes fields. mp <family> is every other family, in MP_REACH_NLRI and MP_UNREACH_NLRI. add announces and del withdraws:

nlri add 10.0.0.0/24 10.0.1.0/24                 # Announce IPv4 unicast prefixes
nlri del 10.0.2.0/24                             # Withdraw an IPv4 unicast prefix
nlri eor                                         # IPv4 unicast End-of-RIB marker
mp ipv6/unicast add 2001:db8::/32                # Announce an IPv6 unicast prefix
mp ipv6/unicast eor                              # IPv6 unicast End-of-RIB marker

IPv4 unicast with an IPv6 next hop travels in MP_REACH_NLRI (RFC 8950), so it is written next-hop <ipv6-address> mp ipv4/unicast add <prefix>. The removed form nlri <family> is refused, and the error names the form to write.

Multiple families in one command:

nlri add 10.0.0.0/24 \
mp ipv6/unicast add 2001:db8::/32

Hex Format

Wire-encoded bytes for debugging or replay:

ze cli -c "send bgp upstream1 update hex \
    attr set 40010100400200400304c0a80101 \
    nhop set c0a80101 \
    nlri ipv4/unicast add 180a0000"

nhop set is separate from attr set: the attribute block's NEXT_HOP does not set the announce command's next-hop policy. Supply nhop set for a family that needs a next hop, even when the raw block already includes it.

Base64 Format

Compact encoding for scripts:

ze cli -c "send bgp upstream1 update b64 \
    attr set QAEBAA== \
    nhop set wKgBAQ== \
    nlri ipv4/unicast add GAoAAA=="

Peer Selector

Routes are sent to peers matching the selector:

Selector Example Description
* peer * All peers
Name peer upstream1 By configured peer name
IP address peer 10.0.0.1 Exact peer IP
Glob peer 192.168.*.* Pattern match
Exclusion peer !10.0.0.1 All except this peer

The separate send bgp <selector> raw <hex|b64> <data> [type <type>] diagnostic command also obeys export-final admission. Both full-packet and UPDATE-body forms suppress announcements when an EBGP destination has no export policy; IBGP absence still accepts. Raw explicit withdrawals and EOR remain available under rejection, unlike the managed-command session prerequisite above, and a mixed UPDATE retains only its explicit withdrawals. Complete non-UPDATE control packets are unaffected. Opaque diagnostics, including uncertain framing or trailing packets, require an accepting export final; otherwise no bytes are sent. With acceptance, raw AS_SET testing and opaque flush-then-retire behavior remain unchanged. A successful raw command response does not prove policy admitted bytes.

Commit Workflow

A named commit collects WITHDRAWALS and sends them together:

ze cli -c "request commit start my-batch"
ze cli -c "request commit withdraw my-batch route 10.0.0.0/24"
ze cli -c "request commit withdraw my-batch route 10.0.1.0/24"
ze cli -c "request commit end my-batch"    # Both withdrawals sent together

A named commit cannot collect an ANNOUNCEMENT. Nothing queues one: (*Transaction).QueueAnnounce has no non-test caller, so a send bgp ... update text ... add between commit start and commit end announces immediately and does not join the commit. This page showed that workflow until 2026-09-05 (plan/journal/unwired-feature.md).

end and eor answer one row per matched peer, under peers, stating what that peer took. A peer that took less than the commit queued carries a reasons entry saying why, and makes the command answer error naming it, because this rail drops the work for a peer whose session is not established:

ze cli -c "request commit end my-batch | table"

From Plugins

External plugins send the same newline-framed YANG RPC command over the plugin hub. The wire protocol is language-independent; the repository no longer ships a Python launcher or helper.

Go plugins use the SDK method:

p.UpdateRoute(ctx, "*", "update text nhop 10.0.0.1 nlri add 10.0.0.0/24")