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.
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.
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 Link-Local Next Hop Needs the Capability
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")