rustbgpd

gRPC API Reference

This reference documents rustbgpd's gRPC API.

This reference documents rustbgpd's gRPC API. rustbgpd exposes twelve native rustbgpd.v1 gRPC services (Global, Config, Neighbor, Policy, PeerGroup, Rib, BFD, RPKI, Event, Injection, Control, Evpn) plus the gnmi.gNMI OpenConfig service over one or more configured listeners. The gNMI surface is read-only telemetry (Capabilities / Get / Subscribe) plus an operator-tier Set subset — transaction-backed create/update/delete for static numbered BGP neighbors, peer-group catalog entries, dynamic-neighbor prefixes, and the commit-confirmed extension through ADR-0076. Unsupported Set paths return UNIMPLEMENTED. The default listener is a local Unix domain socket at /var/lib/rustbgpd/grpc.sock.

For same-host administration, prefer UDS:

grpcurl -plaintext -unix /var/lib/rustbgpd/grpc.sock \
  -import-path . -proto proto/rustbgpd.proto \
  rustbgpd.v1.GlobalService/GetGlobal

The remaining examples below use grpcurl against an explicit local TCP listener for readability. Those examples require grpc_tcp to be enabled, and under the default tier authorization a TCP listener must authenticate — bearer token plus a role-mapped principal, or native mTLS:

[global.telemetry.grpc_tcp]
address = "127.0.0.1:50051"
token_file = "/etc/rustbgpd/grpc.token"
principal = "automation.example"

[security.grpc.roles]
"automation.example" = "operator"

For readability the examples omit the accompanying -H "authorization: bearer <token>" metadata header.

The proto definition lives at proto/rustbgpd.proto. Each tagged release also publishes that file as a release asset; see pinning the proto to a release.

For a worked client in a general-purpose language — stub generation, mTLS with composed bearer-token call credentials, per-call deadlines, and the authorization tiers each call needs — see examples/python-client/.

The project-wide API remains alpha outside the explicit native-gRPC methods listed in the narrow v1 route-server / route-reflector / controller contract. That machine inventory pins method names, streaming modes, and top-level request/response messages; a service or RPC existing in this reference does not by itself make it v1-stable.

Pinning the proto to a release

A controller that generates stubs should pin them to the daemon release it targets instead of hand-vendoring a copy that drifts. Each tagged release publishes the exact tagged proto/rustbgpd.proto as the rustbgpd.proto asset, with rustbgpd.proto.sha256 beside it:

TAG=vX.Y.Z  # the rustbgpd release you target
base=https://github.com/lance0/rustbgpd/releases/download/$TAG
curl -fsSLO "$base/rustbgpd.proto" &&
  curl -fsSLO "$base/rustbgpd.proto.sha256" &&
  sha256sum -c rustbgpd.proto.sha256 &&
  python -m grpc_tools.protoc -I . --python_out=. --grpc_python_out=. rustbgpd.proto

Each command runs only if the previous one succeeded, so a failed download or a checksum mismatch never regenerates stubs.

Commit the tag, and the checksum if you like, next to the generated code. Moving to a new release means changing TAG, verifying again and regenerating. A release that predates the asset has none; take its file with git show $TAG:proto/rustbgpd.proto from a clone instead.

Publishing the file does not promote anything into v1. Alpha messages, fields and RPCs in it stay alpha; the v1 contract still defines the stable subset.

Service overview

ServiceRPCsPurpose
GlobalServiceGetGlobalDaemon identity
ConfigServiceDiffRuntimeConfig, PlanConfigTransaction, StreamPlanConfigTransaction, StreamApplyConfigTransaction, ApplyConfigTransaction, ConfirmConfigTransaction, AbortConfigTransaction, GetConfigTransactionStatus, GetLastSighupReload, GetEffectiveConfig, ListConfigHistory, PreviewConfigRollback, RollbackConfigTransactionCandidate-vs-live config diff, effective running config with defaults resolved (selected default-empty policy lists omitted) and secrets redacted, plus the v1 config-transaction lifecycle: validate/plan, commit/apply (incl. commit-confirmed), confirm, abort, status, and the bounded recorded config history with Junos-style rollback N through the same transaction executor; outside-v1 reads include the latest SIGHUP receipt, while streams provide bounded large-candidate plan and apply ingress
NeighborServiceAddNeighbor, DeleteNeighbor, ListNeighbors, GetNeighborState, EnableNeighbor, DisableNeighbor, SoftResetIn, RefreshOutbound, ReplayOutbound, ResetNeighbor, SetGracefulShutdown, AddDynamicNeighbor, DeleteDynamicNeighbor, ListDynamicNeighborsPeer lifecycle, inbound soft reset, single-peer outbound re-advertisement, administrative session reset, RFC 8326 graceful-shutdown toggle, and dynamic-neighbor CRUD — AddDynamicNeighbor / DeleteDynamicNeighbor add and remove [[dynamic_neighbors]] prefix ranges at runtime (queued to the config file), ListDynamicNeighbors for visibility
PolicyServiceListPolicies, GetPolicy, SetPolicy, DeletePolicy, ListNeighborSets, GetNeighborSet, SetNeighborSet, DeleteNeighborSet, GetGlobalPolicyChains, GetNeighborPolicyChains, SetGlobalImportChain, SetGlobalExportChain, ClearGlobalImportChain, ClearGlobalExportChain, SetNeighborImportChain, SetNeighborExportChain, ClearNeighborImportChain, ClearNeighborExportChain, ExplainImportPolicy, ListRejectedRoutes, TestPolicy, ComparePolicy, GetPolicyStats, GetValidationPolicyPosture, ListConditionalAdvertisementsNamed policy CRUD, neighbor sets, global/per-neighbor chain attachment, import-policy diagnostics, read-only candidate-policy dry runs, live counters, bounded invalid-validation disposition posture, and conditional-advertisement state
PeerGroupServiceListPeerGroups, GetPeerGroup, SetPeerGroup, DeletePeerGroup, SetNeighborPeerGroup, ClearNeighborPeerGroupPeer-group CRUD and neighbor membership assignment
RibServiceListReceivedRoutes, ListBestRoutes, ListAdvertisedRoutes, ExplainAdvertisedRoute, ExplainBestPath, LookupBestPath, ListFlowSpecRoutes, ListEvpnRoutes, ListReceivedEvpnRoutes, ListAdvertisedEvpnRoutes, ExplainEvpnRoute, ListBgpLsRoutes, ListTopologyNodes, ListTopologyLinks, ListOrrTopologyNodes, ListOrrTopologyLinks, ListOrrStatus, ListVpnRoutes, ListRtcRoutes, ListLabeledRoutes, ListVpnRibRoutes, ListLabeledRibRoutes, ListRtcRibRoutes, ListBgpLsRibRoutes, ListBestEvpnRoutes, ListBlackholeDiscards, ListFibRoutes, ListFibTables, SetFibTable, DeleteFibTable, ListRouteEventsQuery-only RIB route surfaces (incl. EVPN, BGP-LS, VPNv4/v6, RT-Constrain, and labeled-unicast), the RFC 9107 ORR / BGP-LS topology read surface (ListTopologyNodes / ListTopologyLinks / ListOrrStatus), BLACKHOLE discard status, paginated FIB status, runtime FIB-table CRUD, exact explain plus outside-v1 global LPM, and recent route-event history; live route streaming is owned by EventService.WatchEvents
BfdServiceGetBfdSessionsBFD session inspection (single-hop and multihop) for configured static neighbors, interface-only bindings and dynamic-range sessions
RpkiServiceValidateRouteOrigin, ListCaches, LookupAspa, VerifyAsPathBounded point validation and configured RTR-cache accepted-epoch inventory, plus the outside-v1 ASPA diagnostics: a bounded merged-provider lookup for one customer ASN and a literal AS_PATH verification with an explicit local role and neighbor ASN
EventServiceWatchEvents, ListEvpnEvents, ListSessionEvents, ListPolicyEventsUnified live stream for route, session lifecycle, BGP NOTIFICATION metadata, policy mutation, EVPN route events, BFD session events, and FIB / BLACKHOLE dataplane status-row summary events, with stream_lagged warnings for bounded-source backpressure; plus bounded after-the-fact EVPN, session-lifecycle, and policy-mutation history. Per-MAC EVPN dataplane categories remain follow-up work
InjectionServiceAddPath, DeletePath, ListPathExportDispositions, BatchListPathExportDispositions, ListFlowSpecExportDispositions, BatchListFlowSpecExportDispositions, AddFlowSpec, DeleteFlowSpec, AddLeasedPath, AddLeasedFlowSpec, RenewLease, ListInjectionLeases, ListLeasedKeys, IssueMutationWindow, AddGuardedFlowSpec, DeleteGuardedFlowSpec, RenewGuardedLease, MarkReplayComplete, AddEvpnRoute, DeleteEvpnRouteProgrammatic route, FlowSpec, and EVPN injection, with optional owner leases, guarded FlowSpec mutations and a controller replay-complete signal
ControlServiceCheckLiveness, GetHealth, GetMetrics, Shutdown, TriggerMrtDumpHealth, metrics, lifecycle, MRT dumps
EvpnServiceGetEvpnRuntime, ListEvpnInstances, ListEvpnNexthops, ListEthernetSegments, ListIpVrfs, ListManagedNetdevs, GetIpVrf, ListDuplicateMacQuarantines, ClearDuplicateMacQuarantine, SetEthernetSegmentDrain, ApplyEvpnRuntimeLocal EVPN VTEP instance state, ADR-0059 FDB-nexthop ownership, ADR-0083/0085 Ethernet Segment multi-homing diagnose state, symmetric IRB (Type-5 / L3VNI) IP-VRF readiness / route counters, ADR-0091 managed-netdev lifecycle/status, duplicate-MAC quarantine status and clear, ADR-0084 Ethernet Segment drain for access-circuit maintenance, and ADR-0063 runtime model status / apply
gnmi.gNMICapabilities, Get, Set, SubscribeOpenConfig BGP telemetry subset (Get / Subscribe) plus a transaction-backed Set subset (static numbered-neighbor create/update/delete, peer-group config, and dynamic-neighbor-prefix entries, with commit-confirmed via ADR-0076; unsupported paths UNIMPLEMENTED; see gNMI); served on UDS and mTLS TCP listeners

Authentication and TLS

The daemon supports three deployment patterns for the gRPC surface:

PatternConfigAuth
Unix domain socket[global.telemetry.grpc_uds] with path + modeFile-system permissions on the socket path
Plaintext TCP + bearer token[global.telemetry.grpc_tcp] with address and optional token_fileBearer token in the authorization: bearer <value> metadata header (when token_file is set)
mTLS TCP[global.telemetry.grpc_tcp] with tls_cert_file + tls_key_file + tls_client_ca_fileClient certificate signed by the configured CA

The mTLS path is the recommended default for any non-loopback gRPC listener. All three TLS fields are required together; partial configuration is rejected at Config::load. There is no "TLS-without-mTLS" half-mode by design — when TLS is enabled the daemon presents the server certificate, requires every client to present a certificate signed by tls_client_ca_file, and rejects unverified clients at the TLS layer before any gRPC handler runs.

Config loading checks file readability and PEM framing. Both --check and --check --strict also run startup credential staging: they parse the server certificate, private key, and client CA bundle and check the cert/key match without binding listeners. After staging replacement files at the configured paths, run rustbgpd --check --strict /etc/rustbgpd/config.toml before SIGHUP or restart. This checks the files at that moment; it does not prove client trust or hostname matching, or cover subsequent file changes. A positive tls_expiry_warning_seconds adds expiry warnings from that staged generation; the default 0 disables those warnings. See native gRPC certificate expiry for metrics, successful-client metadata logs, and bundle-date limits.

Native mTLS accepts TLS 1.2 and TLS 1.3 using the rustls/ring default cipher suites; protocol versions and cipher suites have no configuration overrides. A client whose certificate is trusted can complete TLS without a mapped principal, but its RPCs receive PERMISSION_DENIED from role authorization.

Valid credential bytes behind unchanged TLS paths rotate on SIGHUP. Adding or removing TLS, changing a configured TLS path, or changing TLS/auth mode remains restart-required; runtime config pins that drift to the live values until the daemon is restarted.

Native gNMI is available on the local UDS listener and on TCP listeners only when mTLS is configured. Plaintext or bearer-token-only TCP listeners serve the native rustbgpd.v1 API but do not register gnmi.gNMI. See gnmi.md for the operator-facing OpenConfig path list and gnmic examples.

# mTLS client example with grpcurl
grpcurl \
  -cacert /etc/rustbgpd/server-ca.pem \
  -cert /etc/operator/client.pem -key /etc/operator/client.key \
  -import-path . -proto proto/rustbgpd.proto \
  rustbgpd.example.net:50051 \
  rustbgpd.v1.GlobalService/GetGlobal
# mTLS gNMI client example with gnmic
gnmic \
  --address rustbgpd.example.net:50051 \
  --tls-ca /etc/rustbgpd/server-ca.pem \
  --tls-cert /etc/operator/client.pem \
  --tls-key /etc/operator/client.key \
  --tls-server-name rustbgpd.example.net \
  capabilities

A listener with max_tier = "sensitive_read" rejects mutating RPCs (neighbor add/delete, route injection, policy changes, peer-group changes, shutdown, MRT trigger) with PERMISSION_DENIED. Use this on a dedicated monitoring listener that exposes the read surface without the mutating control plane.

Each configured listener sets its own max_tier; omitting it serves every tier. A listener capped at sensitive_read allows query and watch RPCs but rejects all mutating RPCs with PERMISSION_DENIED. read is a liveness-only ceiling: the only read-tier method is ControlService/CheckLiveness, so monitoring clients that query or watch daemon state need sensitive_read.

Listener Access Matrix

A listener ceiling is a listener-level authorization boundary. It does not create per-user roles: every client accepted by that listener gets the same capped surface. Use a separate listener with a higher max_tier for automation that needs to mutate daemon state.

docs/reference/grpc-method-inventory.md, docs/reference/grpc-method-inventory.json, and crates/api/src/authz.rs classify every RPC into read, sensitive_read, mutating, or operator_only for ADR-0064. The JSON file is the machine-readable export for auditors and generated clients; the Rust authz tests verify it against the source-of-truth matrix. The runtime records tier decisions for every RPC via structured grpc_authz logs and bgp_grpc_authz_decisions_total{tier,result,authn,listener_max_tier}, where tier is the method's tier and listener_max_tier is the serving listener's max_tier ceiling. Listener max_tier caps are always enforced. The same runtime layer also enforces the authenticated principal's configured role ceiling before the handler runs — unconditionally: "tier" has been the default since v0.24.0 and is the only mode since v0.63.0. The former "legacy" migration mode (roles recorded as audit context but never enforced) was removed; a config that still sets it is rejected at boot, --check, and reload with a migration message. Forwarded calls emit result-aware labels such as result="handler_ok" or result="handler_invalid_argument" after the handler returns. Rejected calls use bounded pre-handler labels: result="listener_tier_denied" means the method was rejected before the handler ran, and result="authn_failed" means an over-cap bearer-token request failed authentication before tier details were disclosed. Tier-mode denials use result="principal_unmapped" when the authenticated principal has no role entry and result="role_tier_denied" when the principal's role is below the method tier. Credential-bearing request summaries are masked before entering grpc_authz logs; DiffRuntimeConfigRequest.candidate_toml, PlanConfigTransactionRequest.candidate_toml, and ApplyConfigTransactionRequest.candidate_toml are always summarized as redacted metadata. StreamPlanConfigTransaction logs only framing version, bounded counts, token presence, and outcome; StreamApplyConfigTransaction adds only expected-token and confirm-handle presence — never candidate bytes, digest, plan token, path, or spool name. Transaction apply comments are not logged verbatim, and SetPeerGroup logs MD5 state without the MD5 value. Operators declare [security.grpc.roles] and set explicit listener principal labels for bearer-token TCP and explicitly named UDS listeners; those labels are the principal strings looked up in [security.grpc.roles]. An owner-only UDS without a principal retains its implicit local-operator role even when a bearer token is required. Token-protected UDS listeners use authn="bearer_token"; permissions-only UDS listeners use uds for an explicit principal or uds_owner for the implicit identity. Their parent directories must meet the UDS path requirements. Native mTLS listeners derive the audit principal from the client certificate using ADR-0064 precedence: rustbgpd: URI SAN, then email SAN, then Subject CN. Extracted principal values must fit the bounded audit label form and must not contain embedded control characters; unsupported values fall back to mtls-unresolved, which cannot be mapped in [security.grpc.roles] and is therefore denied.

Tier enforcement is the default since v0.24.0 and mandatory since v0.63.0. When upgrading from an older release, stage [security.grpc.roles] plus explicit listener principals and validate the candidate config with rustbgpd --check. The implicit default UDS listener needs no staging: it is owner-only, so its clients are authorized as the implicit local-operator principal at operator tier without a roles entry — a config whose only management surface is a local socket needs no [security.grpc] block at all. Only group/world-accessible UDS sockets require an explicit principal mapped in [security.grpc.roles]. enforcement = "legacy" was removed in v0.63.0 and from the typed schema in v0.65; the exact retired value still receives a migration diagnostic. Earlier editions of this document projected a two-minor/90-day compatibility floor (approximately 2026-10-09) as the earliest eligibility for removal; that guidance is superseded. The removal landed earlier as an explicit owner decision under the project's pre-1.0 alpha stability posture (see README/ROADMAP on version stability), taken once the implicit local-operator identity removed the migration burden for local-only deployments: for them the migration is deleting the [security.grpc] block. A stuck operator keeps a named-principal setup working with three lines — enforcement = "tier" plus a [security.grpc.roles] entry mapping the listener's principal; the rejection message carries the exact paste block. docs/reference/security.md covers deployment hardening for this surface, and ADR-0064 records the tier model itself and which of its slices remain open. Operational collection, retention, query examples, and resource-abuse guardrails for grpc_authz logs and the related Prometheus metrics live in docs/reference/operations.md.

ServiceRead-only RPCsMutating RPCs rejected on read_only
GlobalServiceGetGlobal—
ConfigServiceDiffRuntimeConfig, PlanConfigTransaction, StreamPlanConfigTransaction, GetConfigTransactionStatus, GetLastSighupReload, GetEffectiveConfig, ListConfigHistory, PreviewConfigRollbackStreamApplyConfigTransaction, ApplyConfigTransaction (pure [[fib_tables]], pure [[dynamic_neighbors]], static [[neighbors]] add/delete/modify, catalog-only policy/neighbor-set/peer-group/global-chain changes, pure live policy-chain impact for static neighbors and accepted dynamic peers, or peer-group/session reshape impact for static members and live dynamic sessions; mixed or unsupported candidates rejected without mutation), ConfirmConfigTransaction, AbortConfigTransaction, RollbackConfigTransaction
NeighborServiceListNeighbors, GetNeighborState, ListDynamicNeighborsAddNeighbor, DeleteNeighbor, EnableNeighbor, DisableNeighbor, SoftResetIn, RefreshOutbound, ReplayOutbound, ResetNeighbor, AddDynamicNeighbor, DeleteDynamicNeighbor, SetGracefulShutdown
PolicyServiceListPolicies, GetPolicy, ListNeighborSets, GetNeighborSet, GetGlobalPolicyChains, GetNeighborPolicyChains, ExplainImportPolicy, ListRejectedRoutes, TestPolicy, ComparePolicy, GetPolicyStats, GetValidationPolicyPosture, ListConditionalAdvertisementsSetPolicy, DeletePolicy, SetNeighborSet, DeleteNeighborSet, SetGlobalImportChain, SetGlobalExportChain, ClearGlobalImportChain, ClearGlobalExportChain, SetNeighborImportChain, SetNeighborExportChain, ClearNeighborImportChain, ClearNeighborExportChain
PeerGroupServiceListPeerGroups, GetPeerGroupSetPeerGroup, DeletePeerGroup, SetNeighborPeerGroup, ClearNeighborPeerGroup
RibServiceAll read/list/explain RPCs (incl. ListFibTables)SetFibTable, DeleteFibTable
EventServiceAll RPCsNone
EvpnServiceGetEvpnRuntime, ListEvpnInstances, ListEvpnNexthops, ListEthernetSegments, ListIpVrfs, ListManagedNetdevs, GetIpVrf, ListDuplicateMacQuarantinesClearDuplicateMacQuarantine, SetEthernetSegmentDrain, ApplyEvpnRuntime
BfdServiceGetBfdSessionsNone
RpkiServiceValidateRouteOrigin, ListCaches, LookupAspa, VerifyAsPathNone
gnmi.gNMICapabilities, Get, SubscribeSet (operator-only; transaction-backed OpenConfig subset — static numbered-neighbor neighbor-address/peer-as/description/peer-group create/update/delete, peer-group catalog entries, dynamic-neighbor prefixes, and the commit-confirmed extension via ADR-0076; unsupported paths return UNIMPLEMENTED)
InjectionServiceListInjectionLeases, ListLeasedKeys, ListPathExportDispositions, BatchListPathExportDispositions, ListFlowSpecExportDispositions, BatchListFlowSpecExportDispositionsAddPath, DeletePath, AddFlowSpec, DeleteFlowSpec, AddLeasedPath, AddLeasedFlowSpec, RenewLease, IssueMutationWindow, AddGuardedFlowSpec, DeleteGuardedFlowSpec, RenewGuardedLease, MarkReplayComplete, AddEvpnRoute, DeleteEvpnRoute
ControlServiceCheckLiveness, GetHealth, GetMetricsShutdown, TriggerMrtDump

Error Taxonomy

The API uses gRPC status codes consistently across services:

CodeMeaning
UNAUTHENTICATEDListener authentication failed: missing bearer token, non-ASCII authorization metadata, or a token mismatch
PERMISSION_DENIEDThe request reached a read-only listener but called a mutating RPC, the RPC method tier exceeds the listener max_tier ceiling, the principal is unmapped in tier mode, or the principal's role is below the method tier
INVALID_ARGUMENTClient-supplied request data is malformed, missing, out of range, uses an unsupported enum value, or combines incompatible filters
NOT_FOUNDA named or targeted resource does not exist: peer, policy, neighbor set, peer group, IP-VRF, route-event target, or injected route
ALREADY_EXISTSA create request targets an existing resource, such as duplicate neighbor creation or an exact-duplicate dynamic-neighbor range
FAILED_PRECONDITIONThe request is valid but the daemon is not in a state where it can complete it, such as MRT export being disabled or a policy object still being referenced
DEADLINE_EXCEEDEDA bounded actor or session read did not complete before its operation deadline; this does not mean the targeted runtime state is absent
UNAVAILABLEA required actor or session task exited, or a required actor, command channel, or persistence queue is unavailable, closed, or back-pressured
UNIMPLEMENTEDThe RPC is reserved in the protobuf but runtime support has not shipped yet, the connected daemon predates the RPC, or a gNMI path or extension is outside the supported subset
INTERNALAn internal daemon actor, metrics encoder, or RIB boundary failed unexpectedly after the request passed validation

For neighbor, peer-group, and policy runtime-config mutations, a failure after transient runtime changes whose forward effects are fully compensated preserves the original gRPC status code and appends the original message after this exact prefix: runtime effects were fully compensated; retry may repeat transient runtime changes:. When an original message is present, exactly one ASCII space separates it from that prefix; an empty original message adds no trailing space. Their trailing metadata also includes rustbgpd-runtime-config-outcome: fully-compensated. The staged persistent candidate is discarded, so the runtime and TOML remain at their prior state. The marker is a retry warning: repeating the request can repeat those transient runtime changes even though the reported attempt left no final-state change. For ApplyEvpnRuntime, see its failure status table.

Operator-read deadlines

Read budgets depend on the operation; there is no server-wide read timeout.

Read pathExisting backend wait budget
Peer-manager operator reads2 s per request to the peer manager, including channel admission and reply
ListNeighbors / GetNeighborState RIB summariesA separate 2 s for the RIB summary admission and reply, after the peer-manager read; this is not one 2 s end-to-end RPC budget
GetPolicyStatsOne absolute 2 s deadline shared by peer validation, export, import and dataset waits; no stage resets it. Every stage reads a published roster (peer manager or RIB manager) and waits only for a Pending session publication or a busy counter or dataset error lock
GetHealthOne 200 ms internal core-probe budget shared by peer-manager and RIB snapshot queries; a missed deadline returns UNAVAILABLE and other snapshot failures return INTERNAL
General RIB listing and RIB explain readsNo fixed server-side timeout in the shared RIB read helper; callers set their own deadlines and cancel abandoned reads

General RIB reads can wait behind policy-transition consistency fences. A raw gRPC caller with no deadline can remain waiting for that fence to clear. The CLI bounds ordinary unary reads, including these RIB reads, at 30 s; methods with separate documented budgets retain those allowances. Custom clients should supply their own deadline. Cancellation releases the waiting reply and is checked by actor work; it does not preempt a synchronous work unit already executing. Route work retains priority. These backend budgets do not promise end-to-end response latency, including synchronous response construction, transport and client scheduling. The separate measured end-to-end soak acceptance gates remain unchanged.

Scoped neighbor identity

An IPv6 link-local neighbor (fe80::/10) is identified by its address and its interface, because one link-local address can exist on several links (RFC 4007). Numbered neighbors are identified by address alone, exactly as before.

Responses. A peer_address that names the source or target neighbor of a route, route event, export disposition, explanation, dataplane row, BFD session or policy statistics row stays a bare IP literal. A sibling interface field carries the scope, and the pair identifies the neighbor; the interface is empty for a numbered neighbor:

MessageInterface fields
Route (received, best, advertised and explain rows)peer_interface
RouteEventpeer_interface, previous_peer_interface, target_peer_interface
EvpnRouteEventpeer_interface, previous_peer_interface
RouteSourceIdentitypeer_interface
ExplainAdvertisedRouteResponsepeer_interface (target), route_peer_interface (selected route's source)
OrrExplainCandidatepeer_interface
ExplainBestPathResponsepeer_interface
PathExportDispositionEntrypeer_interface
ExplainImportPolicyResponse, ImportExplainMatch, ListRejectedRoutesResponsepeer_interface
SessionEvent, NotificationEvent, PolicyEventpeer_interface
FibRouteStatus, BlackholeDiscard, DataplaneRouteEventpeer_interface
BfdSession, BfdSessionEventpeer_interface
PolicyChainStatspeer_interface (empty on the global row)
TestPolicyDiff, TestPolicyRejectedRoutepeer_interface (beside peer)
TcpAoKeyStatepeer_interface (the owning neighbor's interface for a link-local key address)
BgpProtocolError, ResourceLimitError (reserved ErrorDetail shapes, not populated today)peer_interface

Route rows and route events report the interface recorded when the route was learned or the event was recorded, not the current neighbor inventory. The record lives in a per-process table of session contexts; if that table ever fills (65,535 distinct neighbor ASN, role and interface combinations), the daemon logs a warning once and routes from sessions established afterwards report an empty peer_interface even for a link-local peer_address, so a scoped selector does not find them until the daemon restarts. Routes retained across a Graceful Restart and the history of a deleted neighbor keep the interface they had. A BgpEvent envelope's peer_address, previous_peer_address and target_peer_address are bare IP literals in every category; the interfaces are in its payload (RouteEvent, SessionEvent, NotificationEvent, PolicyEvent, BfdSessionEvent, DataplaneRouteEvent or EvpnRouteEvent) and are not repeated on the envelope. Session, notification, policy and BFD events and BFD sessions report the interface of the neighbor they name. FIB and blackhole rows, FIB route events and TestPolicy samples take the interface recorded with the route they describe, and FIB owned state keeps it across a daemon restart. PolicyChainStats rows report the interface of the neighbor whose chain they count. Export rows take that interface from the chain's own neighbor handle, so neighbors sharing a link-local address keep their counters under their own scope.

EVPN route events retain both peers' interfaces when recorded, including after a neighbor moves or is deleted. Scoped event filters match that recorded identity; dataplane and BFD filters use the interface in their payload. EVPN, VPN, labeled, RTC, BGP-LS and FlowSpec route entries still report a bare address with no interface. Those entries do not distinguish neighbors sharing an address; use a scoped peer view when selecting one neighbor.

Selectors. Every request field that selects a neighbor by address requires the scope of a link-local address: fe80::1%eth0 in the address field, or the bare address plus the request's structured interface field where it has one (the NeighborService requests and RouteSourceIdentity.peer_interface).

SelectorResult
192.0.2.1, 2001:db8::1Unchanged
fe80::1%eth0, or fe80::1 with interface eth0Selects the neighbor on eth0
fe80::1 with no interfaceINVALID_ARGUMENT; the message names the scoped neighbors configured on that address
192.0.2.1%eth0, 2001:db8::1%eth0, or a numbered address with an interfaceINVALID_ARGUMENT: a scope is valid only on a link-local address
fe80::1%, a name that is not a Linux interface name, or fe80::1%eth0 with interface eth1INVALID_ARGUMENT
fe80::1%eth1 when the configured neighbor on fe80::1 uses eth0NOT_FOUND, naming the configured scope

A bare link-local selector is refused however many neighbors use the address, so adding a second neighbor never changes what an existing selector means. RFC 4007 §11.6 lets an implementation assume a default zone for an address written without one; rustbgpd deliberately does not. Requiring the scope is this API's contract, not a standards requirement.

The scope is part of a page token's identity. A token issued for fe80::1%eth0 is refused for fe80::1%eth1 or for a numbered selector.

History reads (ListRouteEvents, ListSessionEvents, ListPolicyEvents and ListEvpnEvents) validate the selector's syntax and explicit link-local scope, then match recorded event identities. The selected neighbor need not remain in the current roster, even when another interface now uses its address.


gnmi.gNMI

OpenConfig BGP telemetry surface (ADR-0070). The supported subset is deliberately narrow: Capabilities, Get, and Subscribe (ONCE, POLL, STREAM SAMPLE, and STREAM ON_CHANGE — the last is scoped to the neighbor session-state leaf and follows the live session-event stream) for global and neighbor state under the default network instance. Set is operator-only and supports the first durable config subset: static, numbered BGP neighbor create/update/delete for neighbor-address, peer-as, description, and peer-group, peer-group catalog entries, and dynamic-neighbor prefixes, plus graceful-restart config leaves. Supported Set edits are translated into full candidate TOML and fed through PlanConfigTransaction / ApplyConfigTransaction; the standard gNMI commit-confirmed extension maps to the same confirm / abort lifecycle as native config transactions. Unsupported paths return UNIMPLEMENTED instead of bypassing the transaction model. See gnmi.md for the full ON_CHANGE v1 scope (initial sync, reconnect-no-replay, lag → DATA_LOSS) and Set path matrix.

Get and Subscribe accept at most 16 paths per request (INVALID_ARGUMENT beyond). A Get, or a Subscribe snapshot or tick, whose paths would render more than 65,536 leaf updates returns RESOURCE_EXHAUSTED before rendering; a stream whose roster grows past the bound ends with that status. See gnmi.md for how paths are counted.

Network gNMI is served only on mTLS TCP listeners. The UDS listener also exposes the service as a local-only extension.

For the full supported path list, setup guidance, troubleshooting table, and tested gnmic commands, see gnmi.md.

gnmic \
  --address rustbgpd.example.net:50051 \
  --tls-ca /etc/rustbgpd/server-ca.pem \
  --tls-cert /etc/operator/client.pem \
  --tls-key /etc/operator/client.key \
  --tls-server-name rustbgpd.example.net \
  get \
  --encoding json_ietf \
  --type STATE \
  --path '/network-instances/network-instance[name=DEFAULT]/protocols/protocol[identifier=BGP][name=BGP]/bgp/global/state'

GlobalService

Daemon identity and configuration.

RPCDescription
GetGlobalReturns ASN, router ID, listen port, host TCP-AO capability probe status and detail, and the Unix-epoch-seconds timestamp of the last successfully accepted full policy generation
# Get daemon identity
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.GlobalService/GetGlobal

policy_generation_loaded_timestamp_seconds is the Unix epoch second at which the daemon last accepted a complete policy generation — initial load, SIGHUP, or a config transaction. It is 0 until the first generation is accepted, and a rejected load never advances it (the prior generation stays live and the timestamp freezes), so a caller can prove a reload was accepted rather than merely attempted. It is the same value the bgp_policy_generation_loaded_timestamp_seconds Prometheus gauge exports; see "Policy artifact freshness" in operations.md for the staleness alert expressions.

tcp_ao_support is a read-only Linux capability probe for RFC 5925 TCP-AO. It reports whether the host kernel accepts the TCP-AO socket primitive that rustbgpd uses for static-neighbor and dynamic-prefix startup key installation. If a tcp_ao key is configured on a host where the primitive fails, listener setup aborts startup, and active-open setup rejects that connect attempt without falling back to unauthenticated TCP. Dynamic-range keys are config-file-only: runtime range CRUD rejects protected ranges and overlaps. SIGHUP can append a non-preferred successor generation; selection, deprecation, deletion, and protected-owner CRUD are not exposed. tcp_ao_detail carries human-readable probe detail alongside it, populated only when tcp_ao_support is TCP_AO_SUPPORT_UNSUPPORTED or TCP_AO_SUPPORT_PROBE_FAILED, and empty otherwise.

NeighborState.authentication reports the effective protected transport as PLAINTEXT, MD5, or TCP_AO. For direct dynamic-prefix TCP-AO sessions, that identity comes from the validated accepted socket rather than a synthesized per-neighbor key configuration. When socket inspection succeeds for a connected TCP-AO session, NeighborState.tcp_ao contains current/RNext KeyIDs, Linux verification/error counters, and an ordered keys inventory. Each key row is deliberately redacted: it contains only peer/prefix, directional IDs, algorithm, current/RNext and local rollover flags, optional Linux VRF L3-master ifindex, and per-key counters. The VRF ifindex is not an IPv6 link-local scope ID; absence means the MKT is VRF-unbound, not default-VRF bound. The inventory never contains key material, key length, a hash, or a fingerprint. The daemon refreshes TCP_AO_INFO and TCP_AO_GET_KEYS from the live socket for each neighbor state query, publishes them only as one internally consistent result, and clears it on disconnect or inspection failure; it never serves an older healthy snapshot as a fallback. The counters are cumulative for the lifetime of that TCP socket, so any non-zero error counter keeps the socket DEGRADED until reconnect. NeighborState.tcp_ao_health is NOT_APPLICABLE for plaintext and MD5 peers, UNAVAILABLE when TCP-AO protects the session but there is no socket snapshot (including disconnect, inspection failure, or persistent INFO/inventory inconsistency), HEALTHY when the published snapshot has both current/RNext key-validity flags mapped to a nonempty, internally consistent live inventory, neither active key is deprecated, and no error counters, and DEGRADED when either key-validity flag is absent, an active key is deprecated, or any bad, key-not-found, unsigned-required, or dropped-ICMP counter is non-zero. An inconsistent INFO/inventory pair is never published as degraded state.

For TCP-AO peers, NeighborState.tcp_ao_desired_generation, tcp_ao_applied_generation, tcp_ao_rotation_phase, and tcp_ao_rotation_error expose the secret-free ordered-rotation state. A phase of add_only_failed retains the prior selectable keys and is retryable with another SIGHUP. During add_only, protected accepts may carry either the globally applied generation or the exactly proved desired generation. During add_only_failed, only the applied generation may enter the peer manager; fully installed but uncommitted children remain fail-closed. A partial listener mutation may reject affected passive accepts until retry or restart. During selecting and awaiting_peer, the applied or exactly adjacent desired generation may enter; selection_failed admits only the applied generation. awaiting_peer is a one-shot result, not actor polling: the next identical SIGHUP re-observes the same generation. Selection sets only local RNext, never Linux Current, and predecessor deprecation metadata commits only after the whole affected session cohort has observed verified successor traffic beyond its per-socket pre-selection baseline. During deleting, the applied or exactly adjacent desired generation may enter; a desired-generation accept is projected from the coordinator's retained immutable survivor inventory. delete_failed admits only the applied generation. Deletion removes only deprecated MKTs that are neither Current nor RNext; an ambiguous partial session mutation discards the complete changed cohort before the failure is exposed.

authentication is part of the v1 contract. The TCP-AO inspection and rotation fields (tcp_ao, tcp_ao_health, the two generation fields, tcp_ao_rotation_phase and tcp_ao_rotation_error) follow the alpha TCP-AO lifecycle and are explicitly unstable.

NeighborState.effective_distribution_mode reports the live RIB selection surface. When multiple mechanisms apply, its primary-label precedence is ADD_PATH > PER_CLIENT_BEST > ORR > SINGLE_BEST. It is UNKNOWN when the peer has no active outbound registration; UNSPECIFIED remains the backward-compatible value returned by older servers. This field is independent of the diagnostic update_group label, which is explicitly unstable: its group:N identifier is process-local and its private-path reasons may change. Compare membership with update_group_comparison (rbgp neighbor ADDR --compare NEIGHBOR). A peer eligible for both per-client-best and ORR reports PER_CLIENT_BEST because it is the primary label; that value does not mean its configured ORR vantage is inactive.

NeighborState.selection_deferral is empty on a cold start. During a planned, marker-backed RFC 4724 restart it reports one row per frozen address-family gate: its canonical family label (for example ipv4_unicast; empty from an older daemon) alongside the numeric afi/safi, whether the gate is active, this peer's waiter state and stamped session, the process-wide blocking-waiter count, and remaining time. waiter_session_id is a process-local stamp and is explicitly unstable. Dormant rows have active: false, no release reason and zero remaining time; they are not holding selection. Released rows are retained for the daemon lifetime with reason all_eor, collision_refresh, all_excluded, or timer, so an operator can distinguish complete convergence from timer-driven release. Only eligible sessions re-established since restart hold selection; a configured neighbor that stays down does not. See the startup selection amendment.

NeighborState.paths_limits is sorted by numeric AFI then SAFI. Optional effective_send_limit is presence-aware: presence means active, with zero unlimited and non-zero finite; absence means inactive. The superseded raw sentinel field number and name (effective_send_max, field 5) are reserved.

NeighborState.slow_peer is true while the peer is flagged slow: the session is Established and alive but its outbound queue has stayed above the configured backlog threshold for the configured duration (slow_peer_threshold_pct / slow_peer_duration in the neighbor config). It clears when the queue drains and on session teardown, and mirrors the bgp_peer_slow{peer} gauge. See the "Slow peers" section in OPERATIONS.md for interpretation.

NeighborState.bmp_identity_excluded is true while the neighbor's session reports nothing to BMP: another BMP-monitored neighbor held its link-local address when it was admitted, and every collector sets on_identity_conflict = "exclude". It lasts for the session's peer and mirrors bgp_bmp_identity_excluded_neighbors; see the configuration reference's BMP identity conflicts.

NeighborState.rejected_routes_retained is the actor-authoritative size of that exact peer session's bounded retained-reject store. Presence distinguishes a current fresh snapshot, including an explicit zero, from an older daemon or a stale peer-session query; clients must not turn absence into zero. Inventory consumers can therefore obtain every peer's count in one ListNeighbors request without scanning routes or issuing ListRejectedRoutes per peer.

NeighborState.reconnect_in_seconds is the whole-second wait, rounded up, until this session's next automatic reconnect attempt while it sits in Idle after an unplanned teardown; 0 means no reconnect is pending. Each response recomputes it from the live timer, so it is a sample rather than a countdown a client can decrement. Consecutive NOTIFICATION-driven returns to Idle lengthen the wait from the peer's connect-retry base up to a fixed ceiling, so a rising value distinguishes a peer that keeps failing the OPEN exchange from one waiting out an ordinary retry. Presence is explicit: a current daemon always sends the field, including the zero, so absence means only that the daemon predates it and must never be read as "no reconnect pending". rbgp neighbor omits the field rather than rendering the zero.

NeighborState.negotiation_available and negotiated_session expose the actor-authoritative capability outcome of the current Established session: hold time, cached local IP address, negotiated keepalive cadence, remote router ID, four-octet AS, negotiated families, graceful-restart coverage, the peer's Route Refresh / Enhanced Route Refresh / Extended Message capabilities, and the resulting outbound message-size ceiling. Presence of negotiation_available distinguishes an older daemon that does not expose negotiation state from a current daemon reporting no Established session; negotiated_session is absent while the session is down, during OpenConfirm, or when the actor query is stale. The scalars inside it are optional so genuinely negotiated false/zero values stay distinct from fields an older daemon never sent during a rolling upgrade. local_address is copied from the Established session's cached export profile; it is never substituted with the remote peer address or queried from the socket during an API request. keepalive_interval_seconds is the negotiated send cadence and remains present as zero when negotiated hold time is zero. Both fields and the enclosing negotiated state are absent for down or stale responses; older daemons may send the enclosing state while omitting these two additive fields. Neither field is a live countdown.

NeighborState.rfc8212_import_policy and rfc8212_export_policy report the RFC 8212 explicit-policy status of each direction (ADR-0112); a one-sided configuration is never collapsed into a single "policy present" answer. PRESENT means enforcement applies and explicit operator policy is installed. MISSING means enforcement applies and the reserved internal deny is installed on that direction of this peer — no route crosses it, in any negotiated family. NOT_REQUIRED covers process-wide disabled enforcement and iBGP sessions. Clients must render UNSPECIFIED (a daemon that predates the field) and any unrecognized future value as "unknown", never as NOT_REQUIRED.

NeighborState.inbound_prefix_limits reports ADR-0108 inbound max-prefix capacity, one InboundPrefixLimitState per finite configured bound in enforcement order. Each row has:

  • family: aggregate for the neighbor-wide max_prefixes, or the bound's canonical family label such as ipv4_unicast, l3vpn_ipv4_unicast or l2vpn_evpn.
  • stage: accepted for a bound counted after import policy, or received for the max_prefixes_received_* bounds counted before it. Only the unicast families have a received row.

family and stage are the labels of the bgp_max_prefix_* metrics, so a row joins its series directly. Each row also carries the session actor's usage for that bound, the configured limit, the saturating headroom, a blocking flag for an open max_prefix_action = "block" episode, and the stable reason inbound_prefix_limit_reached while blocking. Unlike the outbound sibling, a bound that is not configured has no row at all, so the list is empty for a peer with no finite inbound bound — and equally empty from a daemon that does not expose the field and from a stale peer-session snapshot. Absence is therefore never proof that no bound is configured. Counts come from the session actor's O(1) enforcement accounting, never from the RIB, whose rows carry different Add-Path and lifecycle semantics. These rows are the only inbound limit and headroom report; prefixes_received_ipv4 and prefixes_received_ipv6 remain the unconditional per-family counts.

NeighborState.gr_retention reports RFC 4724 / RFC 9494 helper-side stale-route retention, one GracefulRestartRetentionState per family the RIB tracks in a GR or LLGR phase: the family label, the phase (gr_restart while the session is down and the restart timer runs, gr_awaiting_eor after re-establishment until End-of-RIB, or llgr), the remaining_seconds until the RIB's next retention deadline for that family, and the stale_routes count. The RIB reads all of it in the same actor turn as the rest of the neighbor snapshot, so the rows are present while the session is down. Phase and deadline are lookups, and the count comes from per-family counters the RIB maintains as routes are marked stale, re-advertised, withdrawn and swept, so ListNeighbors and GetNeighborState both report stale_routes without scanning received routes. The count can be zero while End-of-RIB is still awaited after every stale route was re-advertised. gr_retention_available is present and true from a daemon that exposes the rows; its absence means an older daemon, so an empty list must not be read as "nothing retained" unless the flag is present.

A dynamic neighbor leaves the neighbor inventory when its session goes idle, but the RIB can still retain its routes. Both RPCs still return a row for it while they are retained, with retention_only present and true: the row carries config.address, config.remote_asn (the ASN the RIB last recorded, 0 if unknown), state SESSION_STATE_IDLE, and the RIB-owned fields including gr_retention; every other configuration and session field is its default. ListNeighbors merges these rows into address order; GetNeighborState returns one only for an address without an interface or comparison peer. The row disappears when retention ends. The neighbor keeps its RIB identity and its dynamic_neighbor_limit slot until then (longer when it may still hold our routes as our helper), so a reconnect from the address returns as an ordinary row for the same neighbor. A neighbor kept only while it may hold our routes has no row. retention_only is absent on ordinary rows and from older daemons, which return no row for such a peer.

outbound_resync_pending is true while the peer missed outbound delivery and waits for the RIB's full export resync; outbound_dirty_seconds is the whole seconds that resync has been pending and is present only while it is. update_group_recovery_fallback names the update-group recovery fallback cause recorded for the current session (peer_limit, daemon_limit, allocation_failure or missing_proof) and is empty otherwise. prefixes_sent_pending is true while prefixes_sent is the update group's desired count for a grouped member awaiting resync rather than routes the peer is known to hold; ListAdvertisedRoutes for that peer reads its admitted baseline or returns FAILED_PRECONDITION during the same window. The two optional booleans are absent from an older daemon. Both update_group_recovery_fallback and prefixes_sent_pending are update-group diagnostics and explicitly unstable. See Update-group recovery fallback.

NeighborState.max_prefix_action is the effective current disposition of a crossed inbound bound, not a straight echo of the max_prefix_action configuration key. block and warning mirror the configured value. Configured shutdown reports restart whenever a timed max_prefix_restart_seconds is configured, and while a peer latched by a max-prefix violation still has a hold-down deadline pending; it reports shutdown otherwise, including once a latch has become indefinite. The companion max_prefix_restart_remaining_millis is present only while a hold-down is counting down. The field is a plain string: an empty value is a daemon that predates it, and clients must render an unrecognized value as unknown rather than mapping it back onto a configuration key.

NeighborState.outbound_prefix_limits reports ADR-0113 outbound unicast capacity, one OutboundPrefixLimitState per family: the family name (ipv4_unicast / ipv6_unicast), usage — distinct prefixes currently admitted into this peer's advertised state, post-policy, post-OTC, and post-exact-export, agreeing with advertised-route queries and never the shared update-group table's count — the optional configured limit (absence means unlimited, never zero), the saturating headroom (absent while the family is unlimited or usage is unknown), a blocking flag for an open blocking episode, and the stable reason outbound_prefix_limit_reached while blocking. The list is empty from a daemon that does not expose it and from a peer with no outbound registration; a registered peer always reports both unicast families.

During incomplete admission recovery, unavailable proof can make the admitted unique-prefix usage unknown. usage = 18446744073709551615 (UINT64_MAX) is that unknown sentinel, not a prefix count. headroom is absent until usage is known again; a present limit remains the configured maximum, and blocking still describes the actual blocking episode. The CLI preserves the numeric sentinel in JSON and renders unknown in text and the TUI. Route/path and stale counts remain exact; the unknown sentinel applies only to distinct-prefix capacity. Recovery restores ordinary usage and headroom reporting.

NeighborState.effective_posture is a read-only snapshot of the resolved running neighbor posture: NEXT_HOP ownership enforcement, RFC 1997 interpretation, route-server control-community handling, and the optional ORR vantage. The containing message is always present from a current daemon, so explicit false remains distinguishable from an older daemon that omitted the field. Clients must render an absent message, UNSPECIFIED, and unrecognized future ownership modes as unknown rather than disabled.


ConfigService

Live runtime config diagnostics and transaction planning. Diff / plan callers submit candidate TOML and receive only redacted diff / plan output; GetEffectiveConfig is the one deliberate full-document export — it returns the effective running config as normalized TOML with defaults resolved (selected default-empty policy lists may be omitted) and secret material replaced with <redacted> before it leaves the daemon (rbgp config effective). The two shipped full-document consumers (rbgp config effective and rbgp doctor) accept at most 384 MiB of TOML plus its protobuf envelope; other config RPC clients retain tonic's 4 MiB decode default.

RPCDescription
DiffRuntimeConfigValidate candidate TOML and compare it against the daemon's live runtime config snapshot
PlanConfigTransactionValidate candidate TOML, return a runtime snapshot token, and classify v1 transaction support without mutating daemon state
StreamPlanConfigTransactionOutside-v1 authenticated client stream for plan-only candidates larger than the unary ceiling; returns the unchanged plan plus an optional ephemeral plan token
StreamApplyConfigTransactionOutside-v1 authenticated operator stream that consumes an exact streamed-plan binding and invokes the existing transaction executor
ApplyConfigTransactionOperator-tier commit entry point for ADR-0076 config transactions; currently commits one pure runtime family at a time: full-set [[fib_tables]], full-set [[dynamic_neighbors]], static [[neighbors]] add/delete/modify changes, catalog-only policy/neighbor-set/peer-group/global-chain changes, pure live policy-chain impact for static neighbors and accepted dynamic peers, or peer-group/session reshape impact for static members with post-persist best-effort reset of live dynamic sessions
ConfirmConfigTransactionConfirm a pending confirmed transaction before its timer expires
AbortConfigTransactionAbort a pending confirmed transaction and roll back immediately
GetConfigTransactionStatusReturn redacted confirmed-transaction lifecycle state
GetLastSighupReloadOutside-v1, read-only latest process-local SIGHUP outcome, bounded typed effect receipt and names of fields observed to require a restart (record.pending_restart_required_fields) (rbgp config last-reload); empty before the first settled reload; started_monotonic_micros stamps the reload's start on the daemon host's CLOCK_MONOTONIC, which rbgp reload uses to recognize the reload that followed its signal. A complete outcome also carries live RIB-side outbound convergence (applied, converging with pending peers and oldest age, or converged when no RIB outbound resync is pending; not confirmation that peers received the view)
GetEffectiveConfigReturn the effective running config as normalized TOML — defaults resolved, selected default-empty policy lists omitted, secrets redacted (rbgp config effective)
ListConfigHistoryList up to twenty mixed v2/v3 config history rows — newest row at index 0, then older entries; per-entry timestamp, normalized-TOML SHA-256, config-source SHA-256 over that TOML digest plus the canonical accepted rpol/dataset source roster, provenance status, and one-line summary; never config documents (rbgp config history). Payload-bearing v2 rows are RECORDED; accepted normalized TOML above 10 MiB produces a rollback-ineligible METADATA_ONLY v3 row with normalized_toml_bytes and metadata_only_reason. Corrupt or duplicate-sequence rows are UNREADABLE with both digests empty. Retired TOML files are ignored and retained.
PreviewConfigRollbackOutside-v1 read-only rollback plan for a retained v2 row (rbgp config diff --history N). Requires index 1 or higher and the same source-provenance checks as rollback. Returns the unchanged redacted ConfigTransactionPlanResponse; missing, metadata-only, unreadable, and source-mismatched rows fail without mutation. Available at sensitive_read tier.
RollbackConfigTransactionRestore a provenance-verified v2 row through the same transaction executor as apply — same plan/impact classification and receipts (rbgp config rollback N). Metadata-only rows return FAILED_PRECONDITION before payload/source access, planning, confirm authority, or mutation; index zero remains INVALID_ARGUMENT. Unreadable rows and provenance mismatches fail closed before planning or mutation.

Rollback preview is an as-of plan: it reserves neither a history index nor a future commit. It captures the bounded retained envelope under the existing config coordinator, then releases it before external-source loading or planner actor waits. At planner entry, a nonblocking coordinator check rejects an unsettled baseline with retryable UNAVAILABLE; it releases the permit before RIB waits. It uses the existing config planning budgets: up to ten minutes for coordinator acquisition within the thirty-minute operation deadline. Cancellation ends the read request; it creates no mutation owner, confirm authority, history row, or recovery journal. An older server returns UNIMPLEMENTED, with no fallback to a mutation RPC.

History recording is best effort after an accepted durable config. Exactly 10 MiB of normalized TOML remains v2; larger accepted snapshots retain only a canonical metadata envelope of at most 64 KiB, including a redacted summary of at most 4 KiB. Neither normalized TOML nor the external-source roster is retained in v3. Both formats share one newest-first, twenty-row sequence. Listing rejects a twenty-first recognized final before decoding any row (INTERNAL, storage unavailable or unsafe); rollback maps the same unsafe roster to FAILED_PRECONDITION. Hashes identify accepted history; they cannot recover omitted bytes or authorize use of commit-confirm cleanup residue.

For a supported transaction with an independent mutation, the plan carries one canonical committed candidate through token, runtime stage, persistence, and accepted history. It may materialize omitted RFC 8212 presence (epoch-1 omission as epoch 1 plus explicit false; epoch-2 omission as epoch 2 plus explicit true) without changing effective policy. Representation-only or posture-changing candidates are rejected before mutation. FIB transactions stage the full tables-plus-posture snapshot; determinate failures attempt to restore both. Lost persistence acknowledgement remains ambiguous after attempted restore; rollback or post-durable finalization failure is also ambiguous.

Index 0 is not necessarily the running or currently persisted config. V2 rows hash the accepted external-source identity, but do not archive the .rpol or dataset bytes. Rollback performs one detached load and requires the normalized TOML, complete manifest, and source digest to match exactly.

DiffRuntimeConfigResponse contains boolean summary fields, a plain-text human_text rendering, and diff_json using the rustbgpd --diff --json schema. diff_json is unversioned and explicitly unstable; automation should read the boolean summary fields. Secret-bearing fields such as neighbor md5_password and tcp_ao.key material are redacted in renderings. The corresponding grpc_authz request summaries never log candidate_toml content; they record only redacted metadata such as request body size and token presence.

rbgp config plan and apply stream candidates by default. Plan prints its ephemeral plan token only when present and emits a JSON string or null; Apply accepts --plan-token, or obtains one by streaming a fresh plan for the same candidate and expected runtime snapshot. Plan and automatically planned Apply receive one unary compatibility attempt only when the streaming call returns the generated missing-method fingerprint (UNIMPLEMENTED with empty message and details). Explicit --plan-token Apply fails closed instead, because the unary RPC cannot preserve the reviewed candidate binding. Before that fallback, a fully encoded request above the 4,194,304-byte unary limit fails locally without a unary RPC or secret-bearing diagnostic. The proto and unary server behavior are unchanged. Both streaming methods use metadata version 1, which must appear first and once, followed by zero or more non-empty chunks no larger than 1 MiB, then one end frame carrying the exact aggregate length and raw 32-byte SHA-256, immediately followed by EOF. Aggregate input is capped at 384 MiB, idle input at 60 seconds, and the whole admission through planner reply at 30 minutes. One stream is active process-wide across all listeners. When it is busy, exactly one operator Plan or Apply may wait without preemption under that request's original 30-minute deadline. Observer/automation Plan, a second operator waiter, and lower-role calls while the waiter is registered return RESOURCE_EXHAUSTED; this is one bounded priority waiter, not a general queue. The listener must authenticate clients (mTLS, bearer token, or the owner-only UDS identity). The owner-only descriptor-relative spool file is unlinked immediately after open, before any candidate bytes are accepted, so candidate bytes never survive at a pathname. A crash between exclusive creation and unlink can leave an empty owner-only stub; unlink failure rejects the request before ingress. A COMMITTABLE streamed plan additionally carries plan_token, a UUIDv4 bound in memory to the runtime token, candidate digest, and length for 30 minutes. At most 256 bindings are live. Lower-role issuance evicts the oldest lower-role binding and fails with RESOURCE_EXHAUSTED if every binding is operator-issued; operator issuance evicts the oldest lower-role binding first, then the oldest operator binding. Consumption is role-agnostic, so an operator may apply an exact binding issued by observer/automation Plan. NOOP, REJECTED, and failed plans never issue one. Streamed Apply validates all framing and Apply metadata before atomically consuming the exact token/runtime/digest/length binding. A mismatch preserves the token; an expired, evicted, or successfully consumed token requires a new plan. After consume, client cancellation or deadline never cancels the existing state-changing apply future or restores the token.

ConfigTransactionPlanResponse wraps the same redacted diff with:

  • runtime_snapshot_token: an optimistic-concurrency token for the live runtime snapshot used during planning. It is an opaque, process-local change detector, not a cryptographic commitment or authorization credential; re-plan after a daemon restart.
  • supported_sections: sections the v1 transaction model can commit ([[fib_tables]], [[dynamic_neighbors]], static neighbor add/delete/modify, catalog-only [policy] / [peer_groups] changes with no effective impact on static neighbors or dynamic ranges, pure live policy-chain impact for static neighbors or accepted dynamic peers, and peer-group/session reshape impact — static members and live dynamic sessions).
  • unsupported_sections: hot-reloadable sections v1 refuses until an atomic executor exists. Mixed policy/session effective impact and dynamic-range peer-group reassignments continue to report effective neighbor inheritance impact.
  • restart_required_sections: sections that still require daemon restart. For [global], [rpki], [bmp] and [mrt], the section token is followed by the qualified names of changed fields. Values and redaction rules are described in the reload matrix.

redacted_diff.reload_applied.effective_neighbor_impact[] includes a machine-readable kind: policy_chain for a pure resolved import/export chain move that the live-policy executor can commit, or session_reshape when inherited peer-group/session state changes — committed by the session reshape executor (static members reconfigured in place; live dynamic sessions gracefully reset post-persist).

The planner is intentionally stricter than SIGHUP: "reload-applied" does not mean "transaction-committable" unless the section appears in supported_sections. ApplyConfigTransaction commits one pure runtime family at a time. Cross-family candidates, mixed policy/session effective impacts, and other valid-but-unsupported sections return REJECTED without mutation until their section executor lands.

Native plan/apply/rollback admit a full-snapshot family with external .rpol main/import files or [policy.datasets] snapshots declared only when the planner's fresh capture of those files is byte-identical to the accepted snapshot's recorded identity (ADR-0130) — the bytes are not covered by the transaction token and cannot be rolled back atomically with the TOML, so any drift rejects the transaction without mutation. Deploy changed TOML, .rpol graphs, and dataset snapshots together, then send SIGHUP. gNMI Set never verifies external inputs: a gNMI full-snapshot candidate remains rejected whenever they are present. A true no-op remains NOOP; a pure [[fib_tables]] transaction with unchanged external inputs remains committable because that executor substitutes only the targeted table set rather than adopting the full candidate config. diff_json.reload_applied.datasets_changed reports dataset binding/path edits. diff_json.summary.declared_datasets_count and diff_json.reload_applied.declared_datasets_count report how many datasets the candidate declares; the diff never compares their file contents, so a non-zero count means a reload re-reads files the preview did not evaluate.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d @ localhost:50051 rustbgpd.v1.ConfigService/DiffRuntimeConfig <<'JSON'
{
  "candidate_toml": "[global]\nasn = 65001\nrouter_id = \"10.0.0.1\"\nlisten_port = 179\n\n[global.telemetry]\nlog_format = \"json\"\n"
}
JSON

Plan a transaction without mutation:

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d @ localhost:50051 rustbgpd.v1.ConfigService/PlanConfigTransaction <<'JSON'
{
  "candidate_toml": "[global]\nasn = 65001\nrouter_id = \"10.0.0.1\"\nlisten_port = 179\n\n[[fib_tables]]\nname = \"edge\"\ntable_id = 1000\nmetric = 200\n"
}
JSON

Use the returned runtime_snapshot_token on the apply request. The daemon re-plans under the shared runtime-config coordinator before committing; a stale token fails without mutation. client_request_id and comment are audit metadata only and are not logged verbatim. To use a commit-confirmed workflow, include confirm_id on ApplyConfigTransaction; confirm_timeout_seconds defaults to 600 when omitted and is capped at 86400. While a confirmed transaction is applying or awaiting confirmation, other persisted runtime config mutators fail with FAILED_PRECONDITION. Call ConfirmConfigTransaction with the same confirm_id to make the change permanent, or AbortConfigTransaction to roll back immediately. If the timer expires first, the daemon re-applies the pre-commit runtime snapshot through the same transaction executor and persists the rollback. The confirm window is durable. Before commit, the v3 writer publishes the exact accepted normalized prior to <runtime_state_dir>/commit-confirm-v3-prior.toml, its provenance and file-identity metadata to commit-confirm-v3-metadata.json, then the sole boot authority to <absolute lexical config path>.commit-confirm-locator.json. Startup checks that locator before candidate contents and verifies the complete chain before restoring; unsafe, torn, or mismatched state fails closed. Confirm and successful rollback become terminal only after locator unlink and parent-directory fsync. Subsequent verified exact metadata/raw cleanup and pending-directory fsync are warning-only; locator-free residue cannot re-arm the transaction. Production reads and writes v3 authority only. A v2 locator or locator-free v1/v2 journal makes v0.65.0 and every later release refuse untouched. Recover with rustbgpd v0.64.0, or delete only after proving it terminal and intended. Status reports pending/terminal state. A failed abort/auto-revert rollback is not terminal: the transaction stays pending with an ABORT_FAILED/AUTO_REVERT_FAILED status and the mutation fence stays closed until the abort is retried successfully, the candidate is confirmed, or a restart boot-reverts from the retained journal. A gNMI CommitSetRollbackDuration re-arms the automatic rollback: status returns to PENDING at the new deadline, and a retry that fails again reports the failed status again. A rollback that moves import policy restores the prior chains rather than applying them as a new edit, so a peer that lost Route Refresh inside the confirm window does not block it: that one session is reset (Cease/Administrative Reset) once the prior chain is installed, and the peer resends its routes under it. The rollback still succeeds, and the abort's human_text and the status record name each reset peer. A restore that fails partway is never undone back to the candidate; it fences the daemon for supervised recovery (exit 70, then a boot revert from the retained journal) instead of reporting ABORT_FAILED or AUTO_REVERT_FAILED.

Abort and timer rollback do not depend on the runtime snapshot token. The token is a Plan→Apply change detector for callers: it covers the runtime config and the live update-group membership, so a session going up or down changes it, and a caller's Plan, Apply, or RollbackConfigTransaction holding the older token still fails with FAILED_PRECONDITION and must re-plan. The rollback of a pending confirmed transaction instead restores the prior snapshot the transaction recorded, under the runtime-config coordinator and behind the mutation fence, whatever sessions did during the window. It depends on what any apply depends on: the peer manager and config persistence being available, and the prior snapshot still planning as committable.

V3 commit-confirm caps the current accepted normalized prior at 384 MiB. An oversized prior makes Apply return FAILED_PRECONDITION, including actual and limit byte counts, before authority publication or peer, persistence, and runtime mutation. Ordinary unconfirmed Apply remains available.

GetConfigTransactionStatus (and the apply response) carries a ConfigTransactionConfirmation:

FieldTypeMeaning
statusConfigTransactionConfirmationStatusLifecycle state (see below).
confirm_idstringThe operator-supplied handle for the transaction.
timeout_secondsuint32Effective confirm timeout applied (echoed).
deadline_unix_secondsuint64Absolute live auto-revert deadline, minted after Apply commits and retained in the last terminal lifecycle record. Pre-commit durable authority carries a separate informational deadline derived at publication because boot recovery is unconditional.
committed_sectionsrepeated stringSections the confirmed apply committed.
runtime_snapshot_tokenstringPost-commit token for the pending change.
human_textstringRedacted human-readable summary.

ConfigTransactionConfirmationStatus values:

ValueMeaning
..._UNSPECIFIEDDefault zero value; not emitted in normal responses.
..._NONENo confirmed transaction is currently tracked.
..._PENDINGApplied and awaiting confirmation before the timer expires. Also reported while an expired timer's rollback is still waiting for the runtime-config coordinator; human_text then names the missed deadline and the wait.
..._CONFIRMEDMade permanent by ConfirmConfigTransaction.
..._ABORTEDRolled back by AbortConfigTransaction.
..._AUTO_REVERTEDTimer expired; the pre-commit snapshot was re-applied.
..._AUTO_REVERT_FAILEDTimer expired but the rollback re-apply failed; manual correction required.
..._ABORT_FAILEDAbort requested but the rollback re-apply failed; manual correction required.

(Each value is prefixed CONFIG_TRANSACTION_CONFIRMATION_STATUS_ in the proto.) Confirmed lifecycle transitions are also exposed through the bounded Prometheus counter bgp_config_transaction_lifecycle_total{operation, outcome}: operation is confirm, abort, or auto_revert; outcome is success or failure. The metric deliberately does not include confirm_id, candidate TOML, peer labels, or error strings.

Apply a pure full-set [[fib_tables]] transaction:

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d @ localhost:50051 rustbgpd.v1.ConfigService/ApplyConfigTransaction <<'JSON'
{
  "candidate_toml": "[global]\nasn = 65001\nrouter_id = \"10.0.0.1\"\nlisten_port = 179\n\n[[fib_tables]]\nname = \"edge\"\ntable_id = 1000\nmetric = 200\n",
  "expected_runtime_snapshot_token": "<runtime-snapshot-token-from-plan>",
  "client_request_id": "deploy-2026-06-03-001",
  "comment": "roll edge FIB table definition"
}
JSON

Apply a pure static-neighbor modify transaction:

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d @ localhost:50051 rustbgpd.v1.ConfigService/ApplyConfigTransaction <<'JSON'
{
  "candidate_toml": "[global]\nasn = 65001\nrouter_id = \"10.0.0.1\"\nlisten_port = 179\n\n[[neighbors]]\naddress = \"192.0.2.10\"\nremote_asn = 65010\nhold_time = 45\n",
  "expected_runtime_snapshot_token": "<runtime-snapshot-token-from-plan>",
  "client_request_id": "deploy-2026-06-03-002",
  "comment": "adjust neighbor hold timer"
}
JSON

Apply a transaction with a confirm timer:

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d @ localhost:50051 rustbgpd.v1.ConfigService/ApplyConfigTransaction <<'JSON'
{
  "candidate_toml": "[global]\nasn = 65001\nrouter_id = \"10.0.0.1\"\nlisten_port = 179\n\n[[neighbors]]\naddress = \"192.0.2.10\"\nremote_asn = 65010\nhold_time = 45\n",
  "expected_runtime_snapshot_token": "<runtime-snapshot-token-from-plan>",
  "client_request_id": "deploy-2026-06-03-003",
  "comment": "safe neighbor timer deploy",
  "confirm_id": "deploy-2026-06-03-003",
  "confirm_timeout_seconds": 120
}
JSON

Inspect and confirm the pending transaction:

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{}' localhost:50051 rustbgpd.v1.ConfigService/GetConfigTransactionStatus

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"confirm_id":"deploy-2026-06-03-003"}' \
  localhost:50051 rustbgpd.v1.ConfigService/ConfirmConfigTransaction

Abort instead of waiting for the timer:

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"confirm_id":"deploy-2026-06-03-003"}' \
  localhost:50051 rustbgpd.v1.ConfigService/AbortConfigTransaction

The transaction executors share the same coordinator and persistence ordering as the targeted runtime CRUD paths: re-plan under the runtime snapshot token, durably stage the exact accepted candidate next to the config file, stage the live config snapshot, apply the live runtime change, publish the staged candidate with an acknowledgement, roll back on a publication failure, and only then release the coordinator lock. A stage the persister refuses — an unwritable or read-only config directory, a full filesystem, or a candidate the daemon cannot derive from its accepted config — fails the transaction with FAILED_PRECONDITION before any session, catalog, or policy state changes; a rename that fails after the stage is compensated, and an ambiguous publication or lost acknowledgement fences as described under RecoveryRequired. FIB transactions still require the FIB reconciler to already be running, so adding the first [[fib_tables]] entry to a daemon that started without any tables requires a restart.

Dynamic-neighbor transactions replace the complete [[dynamic_neighbors]] set from the candidate TOML. Static-neighbor transactions support add/delete/modify: modifies use the same delete/re-add session-reconfigure semantics as SIGHUP, then roll back on apply or persistence failure.

Catalog-only transactions can stage named policy definitions, policy neighbor_sets, peer groups, and global named policy-chain assignments before a static neighbor or dynamic range depends on them. They are full-snapshot commits: the daemon updates the live runtime config snapshot and persists the accepted TOML, but does not run SetPolicy / SetPeerGroup live mutation commands.

Policy/neighbor-set/peer-group/global-chain transactions that move an existing static neighbor's or accepted dynamic peer's resolved import/export PolicyChain are also committable when the impact is purely a chain move. The executor stages the candidate on disk and the snapshot, re-applies the resolved chains to affected live sessions, captures prior chains for rollback, publishes the staged candidate with an acknowledgement, and restores both live policy chains and the snapshot on a publication failure. Dynamic peers are selected by the canonical [[dynamic_neighbors]] range that accepted them, not by a public API field. Re-evaluating already-received routes under a new import chain requires Route Refresh, so every impacted Established peer must have negotiated the Route Refresh capability; otherwise the apply is rejected and rolled back without committing the candidate.

Peer-group/session reshape transactions commit peer-group field edits or static-neighbor peer-group reassignments that rebuild existing sessions. The executor stages the candidate on disk and the snapshot, reconfigures affected static peers with the same delete/re-add semantics as SIGHUP, captures prior peer configs for rollback, publishes the staged candidate with an acknowledgement, and restores both live peers and the snapshot on a publication failure. Live dynamic sessions accepted by an affected [[dynamic_neighbors]] range cannot be delete/re-added (they exist only because the remote dialed in), so after a successful persist the executor gracefully resets them with a Cease NOTIFICATION carrying an RFC 9003 shutdown communication; each remote's reconnect is re-accepted under the committed config, and the dynamic_neighbor_limit slot accounting stays owned by the normal session-idle reaping. The dynamic reset is post-persist and best-effort by contract: a failed transaction never flaps a dynamic peer, and a session that could not be signaled keeps its running config until it reconnects (reported in the apply response, never silently swallowed). Reassigning a range to a different peer group remains a [[dynamic_neighbors]] record edit outside the reshape family (ADR-0086).

CLI equivalent:

rbgp config diff /tmp/new-config.toml
rbgp --json config diff /tmp/new-config.toml
# The runtime snapshot token printed by plan is opaque — capture it and pass
# it back verbatim:
RUNTIME_SNAPSHOT_TOKEN="$(rbgp --json config plan /tmp/new-config.toml \
  | jq -r .runtime_snapshot_token)"
rbgp config apply /tmp/new-config.toml \
  --expected-runtime-snapshot-token "$RUNTIME_SNAPSHOT_TOKEN"
rbgp config apply /tmp/new-config.toml \
  --expected-runtime-snapshot-token "$RUNTIME_SNAPSHOT_TOKEN" \
  --client-request-id deploy-2026-06-03-003 \
  --confirm-id deploy-2026-06-03-003 \
  --confirm-timeout 120
rbgp config status
rbgp config confirm deploy-2026-06-03-003
rbgp config abort deploy-2026-06-03-003

NeighborService

Peer lifecycle management. Supports static peers from config and dynamic peers added at runtime.

RPCDescription
AddNeighborAdd a peer dynamically through the presence-aware intent (starts session immediately); waits for the atomic config-file update and leaves no runtime change on persistence failure
DeleteNeighborRemove a peer and tear down its session (Cease / Administrative Shutdown, inside a Cease / Hard Reset when the peer negotiated RFC 8538 Notification GR); waits for the atomic config-file update and rolls runtime back on persistence failure
ListNeighborsList all peers with session state and counters
GetNeighborStateGet detailed state for a single peer
EnableNeighborRe-enable a previously disabled peer
DisableNeighborAdministratively disable a peer (sends NOTIFICATION: Cease / Administrative Shutdown, inside a Cease / Hard Reset when the peer negotiated RFC 8538 Notification GR)
SoftResetInRequest inbound route refresh (RFC 2918/7313) for one or more families
RefreshOutboundRe-emit one peer's current exportable outbound inventory across all negotiated families, without resetting the session
ReplayOutboundSchedule one Established peer's negotiated IPv4/IPv6 unicast replay with terminal UPDATE EoRs; outside the v1 contract
ResetNeighborAdministratively reset one enabled peer's session (Cease/Administrative Reset with an optional shutdown communication)
AddDynamicNeighborAdd a [[dynamic_neighbors]] prefix range at runtime; persists the accepted change atomically before returning and rolls back runtime on persistence failure
DeleteDynamicNeighborRemove a dynamic-neighbor range at runtime (stops future accepts; established peers drain on Idle; disabled members are released); waits for the atomic config-file update and rolls runtime back on persistence failure
ListDynamicNeighborsList configured dynamic-neighbor ranges (prefix, peer group, remote ASN, description)
SetGracefulShutdownRFC 8326 initiator toggle — attach the GRACEFUL_SHUTDOWN community to outbound updates for one peer (or all peers when address is empty) and clear with clear = true. Returns once the live sessions accepted the toggle; re-advertising already-sent routes with the change follows in the background, one peer at a time

ListNeighbors and GetNeighborState expose stale=true when a peer's session-state observation is unavailable. The row remains in the inventory; its placeholder Idle state is not evidence that the session is down. Check stale before interpreting state. An observed Idle with stale=false is a different result.

A ListNeighbors read that a configuration transaction admits while it waits does not hold that transaction. Manager-owned fields (configuration, transport settings, installed-policy RFC 8212 status, max-prefix latch) are captured when the read is admitted. Every session's state query is queued at the same instant, so each session field is observed before that session runs any later configuration command; counters can still advance in the meantime. The response can therefore arrive after the transaction, and after config reload complete, while describing the configuration at admission. A session that does not answer within its query bound is reported stale=true. See the ADR-0132 amendment.

ListNeighbors and GetNeighborState set is_dynamic and, for a dynamic peer, include accepted_dynamic_range with the canonical prefix and peer group captured when the connection was accepted. This is session provenance, not a query against the current matcher: deleting or editing that range does not rewrite the answer for an already-live session. The nested message is absent for static peers and from older daemons.

Remote ASN mode and the session ASN

NeighborConfig.remote_asn_mode carries how remote_asn matches the ASN in the peer's OPEN, as the configuration's remote_asn = <number>, "external" or "internal" does:

ModeMeaningremote_asn
REMOTE_ASN_MODE_UNSPECIFIEDNUMERIC, the behavior before the field existedthe configured ASN, non-zero
REMOTE_ASN_MODE_NUMERICthe peer must send exactly remote_asnthe configured ASN, non-zero
REMOTE_ASN_MODE_EXTERNALany ASN except the local one; an iBGP OPEN is refused0
REMOTE_ASN_MODE_INTERNALthe local ASN0
  • On AddNeighbor, EXTERNAL or INTERNAL with a non-zero remote_asn is INVALID_ARGUMENT. remote_asn = 0 is rejected only for NUMERIC and UNSPECIFIED, and an unknown mode is rejected.
  • ListNeighbors and GetNeighborState return the configured mode with remote_asn = 0 for a non-numeric mode, so the configured intent round-trips and is never replaced by a resolved or negotiated number. EXTERNAL is not the dynamic-neighbor wildcard.
  • The ASN the peer actually sent (the four-octet AS capability when present) is session state: NegotiatedSessionState.remote_asn, present while the session is Established.

Administrative state

NeighborState.admin_state says whether the daemon is holding a neighbor down and which owner did:

  • ENABLED: not held down; the session connects or accepts as configured.
  • OPERATOR_DISABLED: a runtime DisableNeighbor (rbgp neighbor <addr> disable). EnableNeighbor clears it.
  • CONFIG_ADMIN_DOWN: the neighbor's configured admin_down.
  • MAX_PREFIX_LATCHED: a max-prefix shutdown latch. EnableNeighbor, or the single automatic attempt that max_prefix_restart_seconds arms, clears it. An explicit disable keeps the latch.
  • SESSION_CRASH_LATCHED: the neighbor's session task crashed three times within ten minutes and the daemon latched it down. Only EnableNeighbor clears it; an explicit disable, a reconfigure and an armed max-prefix restart keep it. While it holds, a max-prefix latch on the same neighbor reports max_prefix_action shutdown and no restart countdown, since its expiry cannot restart the neighbor.
  • UNSPECIFIED: an older daemon that does not report it, or a retention-only row, which has no neighbor to hold.

When more than one owner holds a neighbor, admin_state names the first of SESSION_CRASH_LATCHED, MAX_PREFIX_LATCHED, CONFIG_ADMIN_DOWN and OPERATOR_DISABLED. A latch outranks the others because its message is the reported last_error, and the crash latch outranks the max-prefix latch because a max-prefix restart cannot lift it. A configured admin_down outranks a later operator disable.

A held-down neighbor settles to state IDLE and is not trying to connect. Disabling a session sends a Cease without replacing last_error, so for OPERATOR_DISABLED and CONFIG_ADMIN_DOWN that field is the failure from before the hold, not its cause. For the two latches it is the latch message: the max-prefix breach, or the crash with its time and the recovery command. bgp_peer_admin_enabled carries the same enabled or held-down state, without the owner; bgp_max_prefix_latched separates the max-prefix latch.

Interface-only neighbors

An interface-only neighbor (ADR-0142) is reported with an empty NeighborConfig.address and its interface:

  • NeighborState.learned_peer_address is the IPv6 link-local address bound to it, without a scope, and is empty until an address is bound.
  • NeighborState.discovery_state is INTERFACE_MISSING, LINK_DOWN, AWAITING_DISCOVERY or BOUND, and UNSPECIFIED for every other neighbor.
  • ListNeighbors lists a neighbor with no bound address after the addressed rows, ordered by interface. Session and RIB gauges are absent while unbound; previously accumulated per-neighbor lifetime totals are retained.
  • A selector with an empty address and an interface selects that interface's interface-only neighbor. So does fe80::x%swp1 (or fe80::x with interface swp1) for any link-local x, bound or not, because the interface owns at most one neighbor; a neighbor whose address and interface match the selector exactly is still selected first. A bare link-local selector stays INVALID_ARGUMENT. GetNeighborState answers for it bound or not. Actions that need a session (enable, disable, reset, soft reset, refresh, replay) return FAILED_PRECONDITION until an address is bound. SetGracefulShutdown applies to every peer only when both the address and the interface are empty; an interface alone selects that interface's neighbor like any other action.
  • Peer-scoped RIB and explain requests take the learned address with its scope, fe80::2%swp1, not the interface alone. gNMI lists an interface-only neighbor once it has a learned address.

AddNeighbor and DeleteNeighbor add and delete interface-only neighbors at runtime, with the same effect as a SIGHUP reload of the stanza (see the reload matrix):

  • AddNeighbor with an empty NeighborConfig.address and an interface adds an interface-only neighbor, including remote_asn_mode EXTERNAL or INTERNAL. Discovery starts on the interface and a peer is created once an address is learned. An interface that already has one returns ALREADY_EXISTS.
  • The first interface-only neighbor needs CAP_NET_RAW and the link monitor. Without them AddNeighbor returns FAILED_PRECONDITION, naming the cause, with nothing changed. A static link-local AddNeighbor at an interface-only neighbor's learned endpoint, its address on the same interface, bound or still reserved, returns ALREADY_EXISTS. One at that address on another interface returns FAILED_PRECONDITION with bmp_identity_conflict, naming the interface, while a BMP collector refuses identity conflicts, or naming the address-keyed feature that cannot be shared (see same address on two links).
  • DeleteNeighbor with an empty address and an interface deletes that interface's interface-only neighbor, bound or not: its session ends, its routes are purged, and the learned address it held or reserved is released. An interface with none returns NOT_FOUND. Deleting its bound peer by address returns FAILED_PRECONDITION, naming the interface selector.
  • A SetPeerGroup edit that changes an interface-only member's session settings rebinds that member, as a reload does; members whose settings do not change keep their sessions.
  • SetNeighborPeerGroup and ClearNeighborPeerGroup take an interface field. With an empty address it selects that interface's interface-only neighbor, which rebinds under its new group; with a link-local address it is the address's scope, as for DeleteNeighbor.

Add a neighbor

AddNeighborRequest.intent is field 2 and carries an inner NeighborConfig plus a required google.protobuf.FieldMask override_mask. Field 1 and the name config are reserved. A missing intent, inner config, or mask returns INVALID_ARGUMENT before persistence or runtime mutation; custom clients must migrate the former top-level config object under intent and send a mask naming each selected supported override (empty only when none are selected).

The bundled rbgp neighbor add command always sends intent with a present mask, even when no overrides are selected. It does not retry another payload.

The create override mask has a closed top-level path set: families, required_families, route_server_client, per_client_best, strict_role, add_path_receive, add_path_send, add_path_send_max, and paths_limit_receive_max. Wildcards, nested, duplicate, unknown, or partial Add-Path paths are rejected. The four Add-Path paths are one atomic block. Masked booleans preserve explicit false; masked family lists replace inherited lists and must be non-empty. Values outside the mask must retain their protobuf defaults.

CLI positive/negative pairs are mutually exclusive: --[no-]route-server-client, --[no-]per-client-best, and --[no-]strict-role. Any Add-Path option selects the quartet; explicit numeric zero remains an override, and --no-add-path emits the all-disabled tuple. Effective inherited prerequisites are validated by the server.

Unmasked fields stay absent in the persisted neighbor and inherit through the normal config resolver. This includes peer-group TTL security, Graceful Restart, route-reflector mode, prefix ORF, IPv6-only behavior, policies, and the complete Add-Path block. With no group and no family override, IPv4 neighbors resolve to IPv4 unicast while IPv6 neighbors resolve to IPv4 and IPv6 unicast.

NeighborConfig.required_families must be a subset of families; otherwise AddNeighbor returns INVALID_ARGUMENT. Empty inherits a non-empty peer-group list; when both are empty, partial negotiation is preserved. NeighborState.config.required_families reports the effective inherited list. Both fields accept the same canonical labels as the configuration file: ipv4_unicast, ipv6_unicast, ipv4_flowspec, ipv6_flowspec, l2vpn_evpn, linkstate, linkstate_vpn, l3vpn_ipv4_unicast, l3vpn_ipv6_unicast, ipv4_labeled_unicast, ipv6_labeled_unicast, rtc, l3vpn_ipv4_flowspec, and l3vpn_ipv6_flowspec. Read responses return those same labels; the bgpls spellings remain metric labels rather than configuration aliases.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"intent": {"config": {"address": "10.0.0.2", "remote_asn": 65002, "description": "peer-2"}, "overrideMask": {"paths": []}}}' \
  localhost:50051 rustbgpd.v1.NeighborService/AddNeighbor

For an IPv6 link-local / unnumbered peer, include interface in NeighborConfig. Follow-up operations that address a scoped peer use the same address + interface pair, or the scoped fe80::5054:ff:fe00:1%eth1 form in address; a bare link-local address is refused (see scoped neighbor identity).

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"intent": {"config": {"address": "fe80::5054:ff:fe00:1", "interface": "eth1", "remote_asn": 65101}, "overrideMask": {"paths": []}}}' \
  localhost:50051 rustbgpd.v1.NeighborService/AddNeighbor

List all neighbors

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.NeighborService/ListNeighbors

Get a single neighbor's state

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.NeighborService/GetNeighborState

Disable a neighbor

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2", "reason": "maintenance"}' \
  localhost:50051 rustbgpd.v1.NeighborService/DisableNeighbor

Enable a neighbor

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.NeighborService/EnableNeighbor

Reset a neighbor's session

rbgp neighbor 10.0.0.2 reset --reason "maintenance"

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2", "reason": "maintenance"}' \
  localhost:50051 rustbgpd.v1.NeighborService/ResetNeighbor

ResetNeighbor is the one-shot session bounce (bgpctl neighbor <peer> clear, clear bgp <peer>): the session sends Cease / Administrative Reset (RFC 4486 subcode 4) carrying reason as an RFC 9003 shutdown communication (deliberately capped at 128 bytes for interoperability, truncating at a UTF-8 boundary like DisableNeighbor) and closes the TCP connection. The peer's enable/disable state is untouched, so no EnableNeighbor follow-up is needed. A static active-open peer reconnects on its normal schedule; if it is already Idle, reset clears any NOTIFICATION backoff and starts the connection immediately. An accepted dynamic peer follows the normal Idle reap path and must dial in again; its next inbound connection is resolved from the current dynamic-range configuration. Scoped link-local peers pass interface as for the sibling RPCs.

  • Unknown peers return NOT_FOUND; administratively disabled peers return FAILED_PRECONDITION (enable the peer instead of resetting it).
  • A session that is not Established is still accepted: Connect/Active drop back to Idle without a NOTIFICATION and follow the static or dynamic lifecycle above. For an enabled static peer already in Idle, reset clears the NOTIFICATION reconnect backoff and starts a connection immediately; no teardown event or session-down sample is emitted because no session exists.
  • When the peer negotiated RFC 8538 Notification Graceful Restart, the reset is sent as Cease / Hard Reset wrapping the Administrative Reset and its communication, so neither side retains stale routes across the bounce. A Cease / Out of Resources raised while the reset drains queued output is wrapped in the Hard Reset the same way.
  • Routes still retained under graceful restart or LLGR from an earlier session loss are purged when the reset finds the session Idle, Connect, Active, OpenSent or OpenConfirm.
  • An Established active-primary teardown increments bgp_session_down_total{reason="local_notification"}. Pre-established resets do not create an Established-session down sample.
  • The sent NOTIFICATION appears in EventService with its on-wire form: code 6/subcode 4 normally, or code 6/subcode 9 when Notification GR wraps the Administrative Reset as a Hard Reset. The decoded inner communication is still exposed as shutdown_reason; no new event type is introduced.

Delete a neighbor

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.NeighborService/DeleteNeighbor

Trigger SoftResetIn

# Refresh all configured families (empty families list)
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.NeighborService/SoftResetIn

# Refresh only IPv4 unicast
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2", "families": ["ipv4_unicast"]}' \
  localhost:50051 rustbgpd.v1.NeighborService/SoftResetIn

Refresh one peer's outbound routes

rbgp neighbor 10.0.0.2 refresh-out

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.NeighborService/RefreshOutbound

scheduled: true means the RIB accepted the refresh pass; resulting updates were enqueued or retained for the ordinary dirty-retry path. It does not confirm writer drain or remote receipt. Unknown peers return NOT_FOUND; managed peers without an active outbound RIB registration return FAILED_PRECONDITION.

RIB queue admission and acknowledgement share a five-second budget. Readiness and operator reads remain admitted during that wait. A read already in progress finishes under its own deadline before the scheduling call returns; later mutations stay queued until both settle. A timeout does not prove that an admitted refresh had no effect.

This is an O(table) operation for the selected peer and can create a full-table UPDATE burst on a production session. Serialize operational use; the API intentionally has no all-peer or batch form.

Replay one peer's unicast routes with terminal EoRs

rbgp neighbor 10.0.0.2 replay-out

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.NeighborService/ReplayOutbound

ReplayOutbound is an experimental, mutating RPC outside the v1 contract. It schedules wire reannouncement of one Established peer's current exportable IPv4/IPv6 unicast routes through the canonical export and transport paths. Every negotiated unicast family receives a terminal UPDATE End-of-RIB (EoR), including empty families. The request has address and optional interface; there is no family filter or all-peer form. Existing RefreshOutbound behavior is unchanged. An older daemon returns UNIMPLEMENTED for the new RPC.

The session must negotiate only IPv4/IPv6 unicast families, with at least one family, and its IP address must be unique among managed peers. A single scoped IPv6 peer is supported; repeated link-local addresses on different interfaces are refused. These prerequisites are checked before monitoring reset or replay traffic, because the reset clears the entire cached peer inventory.

Eligible collectors have a monitor list that includes rib_out_post and omits rib_in_pre (for example monitor = ["rib_out_post"]; the default ["rib_in_pre"] is not eligible). Before replay, each receives a monitoring-only Peer Down (reason 5) followed by the current Peer Up, clearing its previous peer inventory. The BGP session stays established. Mixed inbound/outbound collectors are excluded because this operation cannot rebuild their inbound inventory. After enrollment, ordinary initial-table and peer-refresh unicast EoRs are not mirrored for the rest of this BGP writer generation, including for collectors excluded from enrollment. The actual BGP EoRs are still sent. Further complete BMP boundaries require another explicit replay; a new BGP session restores ordinary EoR mirroring.

The response contains only scheduled. A true value confirms admission for scheduling; it does not confirm completion, collector receipt, or remote BGP processing. Terminal BMP EoRs mark replay completion only after the session writer completes the preceding replay bytes and terminal wire EoRs. A caller disconnecting after scheduling does not cancel traffic already admitted.

While scheduling waits, readiness and operator reads remain admitted. If the five-second scheduling budget expires or its caller disconnects, an already admitted read finishes under its own deadline before the peer manager moves on to later mutations. These reads report live state; a session that cannot answer still has the read's normal timeout and failure behavior. Other commands that reach the session while scheduling waits are queued and run after it. A stop, BFD-down or other session close, or more than a few queued commands, ends the replay with FAILED_PRECONDITION so they run at once; retry the replay.

Unknown peers return NOT_FOUND. Unavailable sessions, another active replay, an empty or mixed-family session, a duplicate managed peer IP address, no eligible connected rib_out_post collector, or an export gate that prevents complete replay return FAILED_PRECONDITION. Dispatch, timeout, or lost acknowledgement failures return an error rather than a successful scheduling response. Later writer, peer, or collector generation failures suppress terminal BMP completion for affected streams. Absence of terminal BMP EoRs is incomplete evidence, even if scheduling succeeded.

This operation reannounces the selected peer's table on its live BGP session. Serialize full-table use and collect the complete BMP stream through its terminal EoRs when using the result as replay evidence.


PolicyService

Named policy definition CRUD plus global and per-neighbor chain assignment. Chain changes apply immediately for future route processing. Import-policy changes do not retroactively re-evaluate existing Adj-RIB-In state; use SoftResetIn if you need a full inbound refresh.

RPCDescription
ListPoliciesList all named policy definitions
GetPolicyReturn one named policy definition
SetPolicyCreate or replace a named policy definition
DeletePolicyDelete a named policy definition (rejected while referenced)
ListNeighborSets / GetNeighborSetList or fetch a named neighbor set
SetNeighborSet / DeleteNeighborSetCreate/replace or delete a named neighbor set
GetGlobalPolicyChainsReturn global import/export chain assignments
SetGlobalImportChain / SetGlobalExportChainReplace global chain assignment. Sessions positively down (Idle/Connect/Active) accept the new chain in memory and install it (plus RIB outbound registration) at PeerUp; retained Adj-RIB-In under an active GR/LLGR window remains evaluated under the prior chain until re-sync/EOR. Ambiguous sessions (SessionGone / state-query timeout) fail closed with INTERNAL and full compensation. IPv4/IPv6-unicast Route Refresh still requires an Established session with Route Refresh negotiated
ClearGlobalImportChain / ClearGlobalExportChainRemove the global chain assignment
GetNeighborPolicyChainsReturn one neighbor's import/export chain assignments
SetNeighborImportChain / SetNeighborExportChainReplace one neighbor's chain assignment
ClearNeighborImportChain / ClearNeighborExportChainRemove one neighbor's chain assignment
ExplainImportPolicyExplain why a prefix was permitted / denied / withdrawn / evicted / stale / not-seen on import for a given neighbor, reading the per-session import-decision cache (ADR-0073). For .rpol chain members the statement trace names the deciding term and carries per-term trace lines (ADR-0096). An all-path query above 4096 matches returns RESOURCE_EXHAUSTED; specify path_id for a point lookup. A bounded read timeout returns DEADLINE_EXCEEDED, not synthetic NO_SESSION. Side-effect-free; IPv4/IPv6 unicast only. SensitiveRead tier.
ListRejectedRoutesList every rejected inbound route a peer's session has retained, each tagged with its canonical reject-reason token (policy_reject, otc_route_leak, next_hop_ownership, as_path_loop, rr_loop, treat_as_withdraw), a bounded sub-reason detail, and a best-effort attribute summary. A named .rpol deny identifies its deciding policy:term; named TOML/default denies retain policy-only detail. The enumeration complement to ExplainImportPolicy's point lookup. Retention is a bounded per-peer LRU ([policy.reject_retention]); the response reports retention_enabled, capacity, and optional evictions_since_reset (absent from older daemons) so completeness is explicit. A bounded read timeout returns DEADLINE_EXCEEDED, not NOT_FOUND. Side-effect-free; IPv4/IPv6 unicast only. CLI: rbgp rib received <peer> --rejected. SensitiveRead tier.
TestPolicyDry-run a candidate .rpol policy (source sent in the request, compiled before RIB access) read-only over a version-fenced walk of the retained post-policy Adj-RIB-In (import) or Loc-RIB best routes (export). Import sees routes admitted by import policy when they were received or last re-evaluated: retained Adj-RIB-In under an active GR/LLGR window, or not yet re-evaluated after an import-policy change, can hold routes the installed chain would now reject, and routes a candidate would newly admit are not visible (ListRejectedRoutes lists recent rejections). Routes are evaluated in canonical (prefix, peer, path_id) order in pages capped at 1,000; family, limit, show_changes, counts, and term hits apply globally; limit = 0 evaluates the whole walk. Candidate datasets carry {name, entries} text, with at most 16 bindings and a 4 MiB encoded-request limit; missing, duplicate, undeclared, or malformed bindings return INVALID_ARGUMENT. show_rejected returns up to 1,000 candidate rejections among retained post-policy routes, and show_changes up to 1,000 diffs; a larger value of either returns INVALID_ARGUMENT. Each listener runs at most two TestPolicy and ComparePolicy requests at once, and a request holds its slot from compile through its last evaluated page; a request past that returns RESOURCE_EXHAUSTED. The compile runs off the async workers under a 30 s bound, and each route page is evaluated on the blocking pool; the RIB and peer reads that set up the walk and the walk itself share a 60 s bound, after which the request returns DEADLINE_EXCEEDED, naming how many routes it evaluated (or the read it was waiting on), with no partial response. A page already being evaluated when the client cancels or the deadline passes (at most 1,000 routes) finishes before its slot frees. A conservative mutation of the selected Received/Best table returns ABORTED with no partial response: retry the whole RPC from the beginning. Paging-generation exhaustion or an unavailable RIB backend returns UNAVAILABLE. No route, session, or counter impact; IPv4/IPv6 unicast (ADR-0096). CLI: rbgp policy test. SensitiveRead tier.
ComparePolicyCompare a candidate .rpol export chain with the export chain installed for one peer (peer, required), over the same version-fenced walk of Loc-RIB best routes. policies lists candidate policies from rpol_source in chain order (at most 64); with replace_member, the single candidate replaces that exactly named installed member and every other installed member stays in place. The installed chain is read from the peer's live outbound registration when the walk starts; a peer without one, or a replace_member request for a peer with no installed chain, returns FAILED_PRECONDITION, and a replace_member that does not name exactly one installed member returns INVALID_ARGUMENT, as does a composed candidate chain over the configuration structural bound (MAX_CHAIN_NODES) or referencing more than 16 datasets. Each member keeps its own dataset binding, so a candidate dataset that shares a name with an installed one does not replace it, and candidate members resolve prepend as self to the daemon's ASN. Attribute changes are compared on a canonical form: attribute and community-set order and a next-hop rewrite to the route's own next hop do not count. Returns both chains' member names, routes_evaluated, exact newly_rejected, newly_accepted and attributes_changed counts, and up to max_samples (at most 1,000) routes per class with each side's rendered attribute changes. Policy chains only: native egress steps (split horizon, iBGP/RR rules, RS control communities, OTC, NO_EXPORT, ORF, families) apply to neither side. limit = 0 evaluates the whole walk. Compile diagnostics, datasets, size limit, paging, the shared admission slots, the compile and walk deadlines, ABORTED and UNAVAILABLE behave as for TestPolicy. No route, session, or counter impact; IPv4/IPv6 unicast export only; outside the v1 inventory. CLI: rbgp policy compare. SensitiveRead tier.
GetPolicyStatsRead live per-term hit counters for installed policy chains (since chain install; direction import, export, or both). Each row's policy_generation names its counters: the install generation for import chains, the counter-instance id for export chains. Explicit-peer validation plus export, import, and dataset reads share one absolute 2 s deadline. Peer validation, import counters and dataset status come from the roster the peer manager publishes, and export counters from the roster the RIB manager publishes, not from an actor query, so success does not show that the peer manager or the RIB manager is making progress; readiness and health test that. A request that sees, after its capture, that either owner has stopped returns UNAVAILABLE. Reads stop on caller disconnect. By default, errors return no partial rows; unfiltered import/both requests may opt in to partial session-closure results as described below. Chainless sessions contribute no row; unknown peers return NOT_FOUND. Export rows derive peer_interface from their own chain's neighbor handle (see scoped neighbor identity). CLI: rbgp policy stats. SensitiveRead tier.
GetValidationPolicyPostureConservatively classifies RPKI-invalid and ASPA-invalid routes as ENFORCED, UNENFORCED, or UNKNOWN for installed static/dynamic peers and one prospective row per accepted dynamic range. The bounded response reports complete and omitted; an incomplete aggregate is never ENFORCED. This proves policy disposition only, not validator readiness, connectivity, configured intent, FIB state, or runtime enforcement. SensitiveRead tier; outside the narrow v1-stable surface.
ListConditionalAdvertisementsList installed conditional-advertisement definitions (ADR-0137), including those referenced by configured interface-only neighbors before binding, sorted by name. Each entry reports advertise_if, every condition entry (prefix plus optional range ge/le) with its own state (present, absent, or unknown), present_prefix_count, and up to eight present_prefixes in address order, the tracked observed condition and observed_for_ms, the applied gate (pending, advertise, or suppress), settle_time_seconds, settle_pending with settle_remaining_ms, selection_deferred (an RFC 4724 hold), and attached_neighbors, one row per static or bound interface-only neighbor sorted by address then interface, with a bare peer_address and the peer_interface of a link-local neighbor (empty for a numbered one). Unbound interface-only neighbors contribute no attachment row. Attachments retained during neighbor teardown may remain visible; internal retiring copies are omitted. The older attached_peers keeps listing bare addresses, one per neighbor, so two neighbors on one link-local address repeat it; attached_neighbors supersedes it. One RIB read, bounded by a 2 s deadline covering admission and reply (DEADLINE_EXCEEDED); it has no priority over route work. Side-effect-free: it reports the tracker's recorded verdicts and evaluates no policy. CLI: rbgp policy conditional-advertisements. SensitiveRead tier; alpha, outside the v1-stable surface.

Import rows use the selected session's actual installed counters, labels and generation. Numeric fields are sampled during collection; neither a row nor the fleet response is one atomic snapshot, and derived ratios are not exact instantaneous fractions. Import error count and error detail are acquired together. A session that has not initialized its observation remains pending within the deadline; by default a closed session or invalid counter state returns UNAVAILABLE, without partial rows. The roster names the sessions as of the peer manager's last completed operation: while an operation that replaces or removes many peers (a reload, a configuration transaction, a peer-group change) is in progress, a fleet read can select a session that has already exited and return UNAVAILABLE. Counter availability does not establish that the session command loop or the peer manager is responsive, or replace the live readiness checks. A capture result observed at or after the shared absolute deadline returns DEADLINE_EXCEEDED, including an otherwise successful final dataset read. See ADR-0133.

For fleet reads during peer churn, set allow_partial=true with an empty peer_address and direction=import or both (CLI: rbgp policy stats --direction both --allow-partial). Only a selected import session's closed publication may be skipped. The response's incomplete_peer_addresses lists those addresses, sorted and unique; a nonempty list means partial, including when every selected session exited. New or replacement sessions published after selection are not substituted. Live chainless sessions add neither a row nor an incomplete address. Closed selected publications are reported in incomplete_peer_addresses regardless of whether their last installed policy had a chain. In both mode, complete export rows precede the retained import rows. The CLI prints Partial import stats and the missing addresses; JSON includes incomplete_peer_addresses only when nonempty.

Using allow_partial with a peer filter or the export direction (including the empty default direction) returns INVALID_ARGUMENT before backend work. Unavailable counters, stopped roster owners, export errors, dataset errors, and the shared deadline still fail the whole RPC. A later dataset timeout discards even successfully collected partial import and complete export rows. The default request contract and the live-sampling semantics are unchanged.

Export rows use the counter instances the RIB manager's published roster designates: a peer's own export chain, or the global fallback when the peer has none. The RIB republishes after each completed operation, and a grouped policy transition switches its whole cohort once, at its final commit, so a read during a long RIB operation reports the live counters of the chains installed before it. policy_generation on an export row is the counter-instance id: nonzero, shared by update-group members that share counters, and new whenever the counters restart, including at each session registration unless the peer rejoins an update group that other members kept; compare it only for equality. The export capture does not wait for the RIB; it yields only while a chain's error lock is being written.

Sessions continue to service direct transport import-counter queries and neighbor-state queries during grouped unicast output, including waits for shared encoded chunks. Earlier queued session commands retain their ordering for those reads. GetPolicyStats bypasses that session command queue for its import stage, and reads the peer manager's and the RIB manager's published rosters rather than queueing on either actor (ADR-0136); its capture waits still consume the shared two-second deadline.

GetPolicyStats adds bounded stage timing to the existing grpc_authz request_summary: peer_validation (targeted requests only), export, import, and datasets, in execution order. Each completed stage records elapsed_ms, its remaining shared budget_ms at entry, cumulative rpc_elapsed_ms, and the gRPC code. A waiting stage records state=waiting so cancellation retains the active API stage. A failed stage is the last completed entry; no later stages run. The completed import entry also records publications=read/selected session counter publications and yields, the waits its capture took: one per session publication still Pending and one per retry of a busy counter error lock. A capture of installed publications takes no waits. These additive diagnostic fields do not change RPC responses or the two-second deadline. Apart from that import detail, they identify the API wait, not its underlying actor or session cause. RUST_LOG=info,policy_stats=debug also emits structured stage-completion events; no per-peer records are emitted for a fleet request.

The daemon installs each peer's complete effective export chain, including global inheritance. GetPolicyStats and rbgp policy stats report those installed peer chains; they do not include a separate global export row. The protobuf's global owner denotes a RIB fallback chain instance, not an aggregate of peer counters. Embedders may still install that fallback through RibManager::new; the daemon does not retain a startup fallback.

Policy statements support the same match surface as TOML config: prefix, ge, le, match_community, match_as_path, match_neighbor_set, match_route_type, match_as_path_length_ge/le, match_local_pref_ge/le, match_med_ge/le, match_next_hop, match_rpki_validation, match_aspa_validation, and match_evpn_route_type.

Explain an import decision

Answer "why didn't this prefix come in?" (or "what did the chain do to it?") from the per-session import-decision cache (ADR-0073). Side-effect-free — no RIB touch, no counter movement. Omit path_id to return every matching path. The cache is opt-in: without [policy.explain] enabled = true on the daemon the outcome is CACHE_DISABLED, which is deliberately distinct from NOT_SEEN. If the peer has no current session actor, the outcome is NO_SESSION; this is also distinct from a session that answered without a cached decision. CACHE_DISABLED and NO_SESSION are normal explain outcomes, not transport errors.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "peer_address": "10.0.0.2",
    "afi_safi": "ADDRESS_FAMILY_IPV4_UNICAST",
    "prefix": "192.0.2.0",
    "prefix_length": 24
  }' \
  localhost:50051 rustbgpd.v1.PolicyService/ExplainImportPolicy

Each matches entry carries an outcome — PERMIT / DENY / WITHDRAWN / EVICTED / STALE / NOT_SEEN — plus decision attribution and the modifications applied. A Deny names its configured denying member; a Permit after a nonempty chain uses chain_default_permit, while an absent or empty chain stays inline. Compare a match's policy_generation to the response's current_policy_generation to spot a STALE decision recorded before a policy reload. When an enabled cache answered, the response also carries cache_size and evictions_since_reset (absent from older daemons). An evicted prefix answers EVICTED, not NOT_SEEN, however many decisions have been evicted.

List a peer's rejected routes

Answer "show me everything of mine you filtered, and why" without knowing a prefix in advance — the looking-glass filtered-route surface. Side-effect-free. Returns NOT_FOUND when the peer has no live session (the session-local retention store is gone, which is honestly distinct from "nothing rejected").

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"peer_address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.PolicyService/ListRejectedRoutes

Each retained rejection carries the prefix identity, the canonical reason token with its bounded sub-reason detail (policy:term for a named .rpol deciding term, otherwise the matched policy name for policy_reject), the announcement's next hop, AS_PATH, communities, RPKI/ASPA validation states, and the rejection timestamp. retention_enabled: false means the empty listing is a configuration fact. Present evictions_since_reset: 0 proves no retained row was displaced this session; a positive count means the listing may be incomplete, while absent means the older serving daemon cannot answer. CLI: rbgp rib received <peer> --rejected.

Create or replace a named policy

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "name": "tag-internal",
    "definition": {
      "default_action": "permit",
      "statements": [
        {
          "action": "permit",
          "prefix": "10.0.0.0/8",
          "le": 16,
          "set_community_add": ["65001:100"]
        }
      ]
    }
  }' \
  localhost:50051 rustbgpd.v1.PolicyService/SetPolicy

Attach a global import chain

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"policy_names": ["reject-bogons", "tag-internal"]}' \
  localhost:50051 rustbgpd.v1.PolicyService/SetGlobalImportChain

Attach a per-neighbor export chain

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2", "policy_names": ["tag-ixp"]}' \
  localhost:50051 rustbgpd.v1.PolicyService/SetNeighborExportChain

Create a named neighbor set

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "name": "ix-clients",
    "definition": {
      "addresses": ["10.0.0.2", "10.0.0.3"],
      "remote_asns": [65002, 65003],
      "peer_groups": ["rs-clients"]
    }
  }' \
  localhost:50051 rustbgpd.v1.PolicyService/SetNeighborSet

Delete a named policy

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"name": "tag-internal"}' \
  localhost:50051 rustbgpd.v1.PolicyService/DeletePolicy

PeerGroupService

Peer-group CRUD plus neighbor membership assignment. SetPeerGroup replaces every field PeerGroupDefinition carries and persists back to TOML. Group fields the definition does not carry, such as role, strict_role, prefix_orf_receive, disable_ipv4_unicast, link_local_next_hop, tcp_mss, bfd, conditional_advertisements, and the per-family prefix limits, are set in the configuration file and keep their configured values. When an inherited setting changes, the daemon recomputes effective per-neighbor config and reconciles only the peers that reference that group. Read responses redact md5_password and expose only the non-secret has_md5_password presence flag. SetPeerGroup preserves the existing stored MD5 password when the field is omitted or set to true without a new md5_password; set has_md5_password = false with no md5_password to clear it explicitly. Use the configuration file or write-side source of truth to inspect credential material.

PeerGroupDefinition.required_families is the raw group list returned by peer-group CRUD. An empty neighbor list inherits it and cannot clear it; a non-empty neighbor list overrides it. Every effective requirement must be a subset of the member's effective configured families.

RPCDescription
ListPeerGroupsList all peer-group definitions
GetPeerGroupReturn one peer-group definition
SetPeerGroupCreate or replace a peer-group definition
DeletePeerGroupDelete a peer-group definition (rejected while referenced)
SetNeighborPeerGroupAssign one neighbor to a peer group
ClearNeighborPeerGroupRemove a neighbor's peer-group reference

Create or replace a peer group

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "name": "rs-clients",
    "definition": {
      "families": ["ipv4_unicast", "ipv6_unicast"],
      "required_families": ["ipv6_unicast"],
      "hold_time": 90,
      "route_server_client": true,
      "export_policy_chain": ["tag-ixp", "suppress-leaks"]
    }
  }' \
  localhost:50051 rustbgpd.v1.PeerGroupService/SetPeerGroup

Assign a neighbor to a peer group

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"address": "10.0.0.2", "peer_group": "rs-clients"}' \
  localhost:50051 rustbgpd.v1.PeerGroupService/SetNeighborPeerGroup

RibService

Query the routing information base. Its route surface is query-only; stream live route changes through EventService.WatchEvents.

RPCDescription
ListReceivedRoutesAdj-RIB-In: all routes received from peers
ListBestRoutesLoc-RIB: best route per prefix after path selection
ListAdvertisedRoutesAdj-RIB-Out: routes advertised to a specific peer
ExplainAdvertisedRouteDry-run export decision for one prefix (or, with rd, one VPN identity) to one peer: the gate ladder in live evaluation order (best_route, split horizon, RFC 4456 reflection, family, RFC 9494 LLGR, RFC 5291 ORF, RFC 4684 RT membership for VPN identities, the stop-only no_advertise / no_export / rs_control rungs, ADR-0137 conditional advertisement immediately before export policy (conditional_advertisement_suppressed / conditional_advertisement_eval_error), export-policy rejection with per-term attribution or nonempty Permit with chain_default_permit, then for Add-Path send the stop-only add_path_send_max check on the policy-compacted rank, RFC 9234 OTC, Adj-RIB-Out diff), produced by a dry run of the live staging body. deny_validation carries the deciding export term's rpki_<state> / aspa_<state> codes on a policy_denied stop, with the same semantics as export read-back; it is empty otherwise. The rung set and order vary by selection shape; see the explain how-to. For negotiated unicast Add-Path send, optional source { peer_address, path_id } selects one exact Adj-RIB-In candidate.
ExplainBestPathShow all candidates for a prefix with decisive comparison reasons; optional peer_address field scopes to that peer's Add-Path send view
LookupBestPathOutside-v1 global-only LPM: bounded ancestor probes return the closest installed Loc-RIB winner plus every alternative for that one matched prefix from one actor turn; old daemons fail with UNIMPLEMENTED
ListFlowSpecRoutesFlowSpec selected Loc-RIB, local-intent reconciliation, or per-peer committed advertised Adj-RIB-Out within the scoped controller contract; remote received-candidate diagnostics remain alpha
ListEvpnRoutesDeprecated whole-table EVPN Loc-RIB view, outside v1; use ListBestEvpnRoutes for bounded best pages
ListReceivedEvpnRoutesBounded accepted post-policy EVPN Adj-RIB-In for one source neighbor, filterable by type / RD
ListAdvertisedEvpnRoutesBounded committed EVPN Adj-RIB-Out for one destination neighbor, filterable by type / RD
ExplainEvpnRouteExact typed EVPN candidate selection, optional destination export trace and caller-selected SRv6 Argument pair inspection, with installed and committed state kept distinct
ListBgpLsRoutesDeprecated whole-table selected BGP-LS / BGP-LS VPN view, outside v1; use ListBgpLsRibRoutes with view = BEST
ListVpnRoutesDeprecated whole-table selected VPNv4/VPNv6 view, outside v1; use ListVpnRibRoutes with view = BEST
ListLabeledRoutesDeprecated whole-table selected labeled-unicast view, outside v1; use ListLabeledRibRoutes with view = BEST
ListRtcRoutesDeprecated whole-table selected RT-Constrain view, outside v1; use ListRtcRibRoutes with view = BEST
ListVpnRibRoutesScoped RR-only L3VPN: bounded best/received/advertised pages with typed family, prefix, RD and peer filters
ListLabeledRibRoutesScoped RR-only labeled-unicast: bounded best/received/advertised pages with typed family, prefix and peer filters
ListRtcRibRoutesScoped RR-only RT-Constrain: bounded best/received/advertised pages with membership and peer filters
ListBgpLsRibRoutesScoped RR-only BGP-LS / BGP-LS VPN (RFC 9552): bounded best/received/advertised pages of opaque NLRI/TLV bytes with family, NLRI type and peer filters
ListBestEvpnRoutesBounded selected EVPN best pages with source/RD/MAC/ESI/VNI filters; scoped RR-only for Types 1–5, with all-types and Type 6 calls outside v1
ListTopologyNodesDeprecated whole-graph RFC 9107 ORR node view, outside v1; use ListOrrTopologyNodes
ListTopologyLinksDeprecated whole-graph RFC 9107 ORR link view, outside v1; use ListOrrTopologyLinks
ListOrrTopologyNodesScoped RR-only: bounded pages of RFC 9107 ORR topology nodes built from the BGP-LS Adj-RIB-In union
ListOrrTopologyLinksScoped RR-only: bounded pages of RFC 9107 ORR topology links — IGP adjacencies, link addresses, and metrics (the SPF input)
ListOrrStatusRFC 9107 ORR per-vantage status — configured vantages, their resolved topology nodes, and the peers bound to them
ListBlackholeDiscardsRFC 7999 BLACKHOLE kernel-discard install status when [global] honor_blackhole = true and [global] install_blackhole_discard = true
ListFibRoutesADR-0061 general unicast Linux FIB route status for configured [[fib_tables]]
ListFibTablesList the committed [[fib_tables]] and whether the FIB reconciler was started with an open command channel; UNAVAILABLE if that channel has closed. Served without querying the reconciler, so runtime_available = true is not a responsiveness guarantee (sensitive_read)
SetFibTableCreate-or-replace a [[fib_tables]] entry by name (upsert; full definition, not a patch) at runtime; hot-applies through the reconciler and persists. Requires the reconciler running (≥1 table at startup) else FAILED_PRECONDITION (mutating)
DeleteFibTableRemove a [[fib_tables]] entry by name at runtime; NOT_FOUND if absent (mutating)
ListRouteEventsRecent unicast route add / withdraw / best-change / export-policy-filtered event history from the bounded in-memory RIB ring

Limit-blocked ListBlackholeDiscards rows reuse REJECTED with stable reason text active_limit_exceeded or install_rate_limited; both are retryable.

The three unicast route-listing RPCs return raw ordered extended_communities, the ASPA verification string in aspa_state, and received_at_epoch_seconds on every Route (0 means unknown). MED is reported only by the optional med_attr: it is set when the route carries a MULTI_EXIT_DISC attribute, including an explicit 0, and absent when it carries none. The bare med scalar (field 8), which reported an absent MED as 0, is removed; its number and name are reserved. Native rbgp --json rib preserves the raw extended-community values, omits an empty aspa_state from an older daemon but retains a genuine "unknown" state, and retains the zero receive-time sentinel. The same native route serializer is used by best, received, advertised, and embedded ExplainBestPath routes.

Unknown peers in peer-scoped views

A peer-scoped view that finds no rows returns NOT_FOUND with the message neighbor <address> not found when the address names no known peer. This covers ListReceivedRoutes with neighbor_address set, ListAdvertisedRoutes, received/advertised-mode ListFlowSpecRoutes, ListReceivedEvpnRoutes, ListAdvertisedEvpnRoutes, ExplainEvpnRoute with received_from or advertised_to when that side is absent, and BfdService.GetBfdSessions with peer_address set. A known peer is a configured neighbor, an accepted dynamic peer, or an address whose Adj-RIB-In still retains Graceful Restart or LLGR stale routes after its session ended; the first two clauses are the managed peers GetPolicyStats resolves from the published roster. The synthetic peer 0.0.0.0 that owns routes added through InjectionService is always known. A known peer that is down or has sent nothing still returns OK with an empty result. The daemon checks only when a view is empty, so a view with rows never pays for it. The whole check is bounded by one peer-manager read deadline, and exceeding it returns DEADLINE_EXCEEDED.

At startup the gRPC listeners serve before the configured-peer roster is installed. If a peer-scoped read would otherwise return NOT_FOUND in that window, it returns retryable UNAVAILABLE until registration completes. This includes GetNeighborState, GetNeighborPolicyChains, scoped GetPolicyStats, and a concrete-neighbor gNMI Get. gNMI Subscribe retains its empty snapshot behavior for an absent neighbor. The peer manager registers the whole configured set in one operation: a view that reaches it while registration runs waits for the complete roster, within its read deadline, and GetPolicyStats sees every configured neighbor at once when registration ends. /readyz and systemd READY=1 are reported only after the roster is installed.

A continuation token does not outlive its peer. Removing a peer mutates the route table, so the next continuation returns ABORTED. Restarting from an empty token returns NOT_FOUND only once the address is neither managed nor retaining stale routes; while its Adj-RIB-In still retains Graceful Restart or LLGR stale routes, the restart returns OK with those rows.

Prefix-SID inspection on VPN and EVPN routes

VpnRouteEntry.prefix_sid (field 14) and EvpnRouteEntry.prefix_sid (field 17) are optional views of the retained Prefix-SID path attribute. VPN Loc-RIB listings and all EVPN route views, explain snapshots, and current or previous event snapshots use the same conversion. An absent attribute leaves the field absent; older daemons and stored event records decode with no view.

The view carries the complete attribute value in raw_value and the original path-attribute flags. services contains the first L3 (type 5) and first L2 (type 6) Service TLV, preserving service, SID Information, and SID Structure order. Each SID exposes its advertised IPv6 sid_value, numeric endpoint_behavior (including unknown codes), separate SID flags, and all six structure fields: locator block, locator node, function, argument, transposition length, and transposition offset. Reserved bytes, unknown TLVs, and ignored duplicate services remain available in raw_value.

rbgp --json rib vpn, EVPN route lists and explain output, and EVPN event JSON expose an optional prefix_sid object with lowercase hex raw_value. Text output adds an advertised SID summary; structure lists the six fields in the order above. JSON includes a nonempty decode_error and no decoded services if stored raw data fails structural inspection; the raw bytes remain available. Routes without Prefix-SID keep their existing JSON shape.

Each SID can also carry optional reconstructed_sid (field 5), restoring a Function from the high-order bits of the route's label: a single 20-bit VPN label or the applicable EVPN service field. MAC/IP L2 and L3 services use label 1 and label 2 respectively; L3 requires an IP address. Ethernet A-D per EVI uses its L2 label and IP Prefix uses its L3 label; these EVPN labels supply up to 24 Function bits. IMET uses a single ingress-replication (0x06) PMSI label for up to 24 Function bits or an SRv6 P2MP (0x0d) PMSI label for up to 20 high-order Function bits (RFC 10018 §4.1.1.1.2). The raw sid_value stays unchanged. Text labels the derived value reconstructed-sid; JSON omits the field when it is unavailable, including when reading an older daemon or event record.

Reconstruction requires exactly one SID Structure, a nonzero transposition wholly inside its Function, valid bounds, and zero advertised bits in the vacated slice. Missing or ambiguous labels/structures, no transposition, and nonzero Argument lengths leave it absent. A missing or unsupported IMET PMSI tunnel type also leaves a transposed Function unavailable. Argument composition involving another route (such as Ethernet A-D per ES plus IMET) is outside this per-route view; use the explicit EVPN Argument pair inspection.

This is attribute inspection. It does not validate endpoint behavior against the route family, select a service, originate SRv6 routes, or program forwarding. The EVPN prefix_sid field remains alpha, outside the scoped EVPN reflector boundary.

Runtime observability surfaces

Runtime visibility is intentionally split by access pattern rather than forced through one RPC shape.

NeedSurfaceShapeRetention / loss behavior
Live unicast route deltasEventService.WatchEvents with EVENT_CATEGORY_ROUTEStreaming event feedLive-only; WatchEvents emits stream_lagged when slow subscribers miss events
Recent unicast route timelineListRouteEvents / rbgp eventsBounded history queryIn-memory 4096-event ring, process-local, oldest entries evicted
Live session lifecycleEventService.WatchEvents with EVENT_CATEGORY_SESSIONStreaming event feedLive-only; no replay after reconnect
Recent session lifecycleEventService.ListSessionEvents / rbgp events sessionsBounded history queryIn-memory 4096-event ring shared by all peers, process-local; the response reports evicted_total and oldest_retained_unix_ms
Live policy mutation summariesEventService.WatchEvents with EVENT_CATEGORY_POLICYStreaming event feedLive-only; slow subscribers can lag and miss events
Recent policy mutation summariesEventService.ListPolicyEvents / rbgp events policyBounded history queryIn-memory 4096-event ring, process-local, oldest entries evicted
Live EVPN route best-path deltasEventService.WatchEvents with EVENT_CATEGORY_EVPNStreaming event feedLive-only; slow subscribers can lag and miss events
Recent EVPN route timelineEventService.ListEvpnEvents / rbgp events evpnBounded history queryIn-memory 4096-event ring, process-local, oldest entries evicted
RFC 7999 discard programmingListBlackholeDiscards / rbgp rib blackholesSnapshotCurrent reconcile snapshot only; retryable limit blocks are REJECTED with active_limit_exceeded or install_rate_limited
ADR-0061 general Linux FIB programmingListFibRoutes / rbgp rib fibSnapshotCurrent reconcile snapshot plus persisted owned-state semantics
ADR-0061 FIB route apply outcomesEventService.WatchEvents with EVENT_CATEGORY_DATAPLANE and BGP_EVENT_TYPE_DATAPLANE_ROUTE_* / rbgp events watch --category dataplaneStreaming event feedLive via WatchEvents; no replay and no bounded List* history API
EVPN L2/L3 dataplane readiness and managed-netdev ownership statusEvpnService (ListEvpnInstances, ListEvpnNexthops, ListEthernetSegments, ListIpVrfs, ListManagedNetdevs) / rbgp evpn ...SnapshotLatest daemon or dataplane report snapshot
BGP-LS topology objectsListBgpLsRibRoutes / rbgp rib bgplsBounded pagesSelected Loc-RIB, accepted input or committed export; raw BGP-LS NLRI/TLV bytes preserved
ADR-0067 BFD session stateBfdService.GetBfdSessions / rbgp bfdSnapshotCurrent BFD actor snapshot
Live BFD session state changesEventService.WatchEvents with EVENT_CATEGORY_BFD and BGP_EVENT_TYPE_BFD_SESSION_* / rbgp events watch --category bfdStreaming event feedLive-only; opt-in (not in the default route+session set); slow subscribers can lag
Alerting / countersPrometheus /metricsCumulative counters and gaugesProcess lifetime, scrape-dependent

Use a live stream when you need a tail, ListRouteEvents when you need recent route context after the fact, and status RPCs for current ownership/readiness state. WatchEvents does not replay ListRouteEvents; clients that need both context and a live tail should query history first, then subscribe.

List received routes (Adj-RIB-In)

# All received routes
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.RibService/ListReceivedRoutes

# From a specific peer
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"neighbor_address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.RibService/ListReceivedRoutes

List best routes (Loc-RIB)

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.RibService/ListBestRoutes

List advertised routes (Adj-RIB-Out)

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"neighbor_address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.RibService/ListAdvertisedRoutes

Explain one advertised route decision

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"peer_address": "10.0.0.2", "prefix": "203.0.113.0", "prefix_length": 24}' \
  localhost:50051 rustbgpd.v1.RibService/ExplainAdvertisedRoute

This dry-runs the current export decision for a single prefix and peer. The response includes the final decision, decisive reasons, selected best-route identity, and any export modifications that would be applied.

In ExplainModifications, used by this response, ExplainImportPolicy and TestPolicy, as_path_prepend lists the ASNs the policy chain places in front of the AS_PATH, leftmost first, with computed operands resolved: a policy that prepends 2.5 three times and then 666.5 twice reports [43646981, 43646981, 131077, 131077, 131077]. It replaced the as_path_prepend_asn / as_path_prepend_count pair, whose field numbers and names are reserved, because one ASN and count cannot represent that sequence.

For an IPv4/IPv6 unicast peer with negotiated Add-Path send, set the optional presence-bearing source message to explain one exact Adj-RIB-In candidate:

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"peer_address":"10.0.0.2","prefix":"203.0.113.0","prefix_length":24,"source":{"peer_address":"198.51.100.7","path_id":0}}' \
  localhost:50051 rustbgpd.v1.RibService/ExplainAdvertisedRoute

The echoed source.path_id remains the inbound Add-Path identity. The top-level response path_id is the independent outbound path ID rustbgpd would use after eligibility and export policy: a path keeps its ID while it is sent, and a new path takes the lowest free one. It is 0 for a pre-selection/policy denial or a candidate beyond add_path_send_max. A later OTC or exact-wire denial retains the attempted non-zero ID, and the adj_rib_out rung compares the row at that exact ID. Inbound ID 0 remains selectable because message presence, not a sentinel, distinguishes selection from the legacy winner-oriented query. Unknown source identity returns NOT_FOUND; a source selector without negotiated unicast Add-Path send returns FAILED_PRECONDITION. source is mutually exclusive with rd and labeled.

A grouped peer's unicast explain and ListAdvertisedRoutes read the same admitted state. If the peer missed an update because its outbound queue was full or its receiver closed before peer teardown, and no pre-regroup baseline exists, nothing records which group entries it missed. Both RPCs then return FAILED_PRECONDITION instead of reporting the group's desired routes as advertised. The listing's message is advertised routes are unavailable until outbound resynchronization completes. The refusal is transient and clears when the peer's next resync is admitted, so retry after its queue drains or a new session registers. A peer that retains a regroup baseline is answered from that baseline by both RPCs. VPN and labeled-unicast explain do not apply this refusal.

Best-path explain is also available via ExplainBestPath RPC — it returns all candidates for a prefix with the decisive comparison reason for each. Set peer_address on the request to scope the response to that peer's Add-Path send view: candidates that pass the peer's live export gates (the RFC 5291 §6 refresh gate, sendable-family, the Address-Prefix ORF filter, split-horizon and iBGP / RFC 4456 route-reflector rules, RFC 1997 NO_ADVERTISE / NO_EXPORT, route-server control communities, the LLGR export restriction, conditional advertisement and export policy), fall within the peer's effective add_path_send_max and are not withheld at commit (RFC 9234 OTC egress, the outbound prefix limit) get a non-zero advertised_path_id naming the path ID they would carry on the wire; everything else stays at advertised_path_id = 0. A family still waiting for the peer's ROUTE-REFRESH and an ORF-denied prefix report no IDs. The IDs are the next staging decision: an ORF filter pushed with DEFER takes effect at the prefix's next change or the next ROUTE-REFRESH, so until then the peer can still hold a path explain reports at 0. ExplainAdvertisedRoute names the gate that stops a path. The response echoes peer_address and the effective add_path_send_max so the operator can read advertisement intent without cross-referencing the peer config. Empty peer_address returns the v0.7.0 global Loc-RIB view unchanged. Unknown peer_address → NOT_FOUND. Import explain is available via PolicyService.ExplainImportPolicy (ADR-0073), including structured statement/term traces for matched policies.

SRv6 semantic ineligibility is distinct from an import-policy rejection. ExplainBestPath retains these candidates with vs_best_reason = "srv6_sid_invalid", multipath = "none", and advertised_path_id = 0. If no eligible candidate remains, the RPC succeeds with an absent best_route and empty best_reason; the CLI prints the retained candidates. A prefix with no retained candidates still returns NOT_FOUND. only_path means one eligible candidate, even if other retained candidates are ineligible. EVPN received views and exact explain likewise retain the received route and its eligibility reason. Use ListVpnRibRoutes for bounded selected, received and advertised VPN pages. The deprecated ListVpnRoutes retains only the whole-table selected view outside v1.

Longest-prefix lookup in the global Loc-RIB

rbgp rib lookup 203.0.113.99
rbgp --json rib lookup 2001:db8::7/128

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"prefix":"203.0.113.99","prefix_length":32}' \
  localhost:50051 rustbgpd.v1.RibService/LookupBestPath

rbgp rib lookup <IP|CIDR> issues exactly one LookupBestPath request. Bare IPv4 and IPv6 addresses use /32 and /128; an explicit CIDR keeps its mask. The daemon performs bounded ancestor probes and returns the closest installed global Loc-RIB winner plus every alternative for that matched prefix from one actor turn. The response therefore uses the existing best-path explanation shape, and its prefix may be less specific than the query. There is no peer-scoped mode and no client-side listing fallback. A syntactically invalid target is rejected locally, no covering route returns NOT_FOUND, and a daemon without the outside-v1 method returns UNIMPLEMENTED (not supported by this daemon in the CLI).

Address family filtering

Route-listing RPCs and the route-event surfaces (ListReceivedRoutes, ListBestRoutes, ListAdvertisedRoutes, ListRouteEvents, and EventService.WatchEvents) accept an afi_safi field to filter by address family. Supported values are IPV4_UNICAST (1), IPV6_UNICAST (2), or unspecified (0, returns both unicast families). Route watch events include the address family of each route change. FlowSpec routes use ListFlowSpecRoutes with IPV4_FLOWSPEC (3), IPV6_FLOWSPEC (4), or unspecified (0). EVPN routes use the bounded ListBestEvpnRoutes, ListReceivedEvpnRoutes and ListAdvertisedEvpnRoutes with EVPN-specific filters; the deprecated ListEvpnRoutes retains its whole-table view outside v1. BGP-LS routes use the bounded ListBgpLsRibRoutes with ADDRESS_FAMILY_BGP_LS (6), ADDRESS_FAMILY_BGP_LS_VPN (7), or unspecified (0); the deprecated ListBgpLsRoutes retains its whole-table view outside v1.

Pagination

The unicast route-listing RPCs ListReceivedRoutes, ListBestRoutes, and ListAdvertisedRoutes support pagination via page_size and page_token. ListFibRoutes also supports optional pagination; unlike the route-listing RPCs, page_size = 0 preserves the legacy behavior and returns the full filtered FIB status snapshot. The bounded family reads are described in Bounded VPN, labeled, RTC, BGP-LS and EVPN best pages. ListBlackholeDiscards, ListFlowSpecRoutes, and the deprecated ListBgpLsRoutes do not support pagination.

Their shared ListRoutesRequest also accepts optional recorded-route predicates: typed rpki_validation (VALID, INVALID, or NOT_FOUND), typed aspa_validation (VALID, INVALID, or UNKNOWN), and presence-aware as_path_contains for one exact nonzero ASN. UNSPECIFIED means no verdict filter; unknown numeric enum values and ASN 0 return INVALID_ARGUMENT. Predicates are identical across Received, Best, and Advertised, compose AND-wise with the existing prefix/origin/community filters, apply to both total_count and bounded pages, and are part of the opaque continuation-token identity. AS-path membership covers exact numeric members of represented AS_SEQUENCE and AS_SET segments only; it is not a regex or policy evaluation. RFC 9774 rejection of newly received AS_SET and AS_CONFED_SET forms remains unchanged.

# First page (2 routes)
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"page_size": 2}' \
  localhost:50051 rustbgpd.v1.RibService/ListBestRoutes

# Next page (pass the previous response's next_page_token verbatim)
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"page_size": 2, "page_token": "<next_page_token>"}' \
  localhost:50051 rustbgpd.v1.RibService/ListBestRoutes

page_token is opaque: always pass the next_page_token from the previous response (empty = listing complete), and only reuse it with the same RPC, neighbor, route scope, and semantically equivalent route filters. Changing a scope or filter returns gRPC INVALID_ARGUMENT; changing only page_size is safe. Tokens are process-local and mutation-fenced: Received and Best share one conservative table generation, while Advertised has an independent generation. Any mutation in that class makes the next request fail with gRPC ABORTED; a peer-specific listing can therefore restart after an unrelated peer in the same class changes. The server retains no route snapshot or cursor registry. page_size is capped server-side at 1000 rows per page (0 = default of 100).

Every ListRoutesResponse, including an empty or terminal page, carries a page_version message with an epoch and generation. The pair exposes the same process-local consistency fence used by continuation tokens. A client may compare the complete pair across Received and Best pages in one logical capture; a changed value means the entire capture must be discarded. The values are opaque, may repeat after daemon restart, and are not a RIB snapshot generation. In particular, page_version.generation must never be compared with or substituted for a producer-local rbgp-ribsnap/1 header generation. Older daemons omit this additive message field.

During startup unicast selection release, clients may set accept_releasing to read the rows already committed. The same response names each releasing address family in selection_release.releasing_families, including on empty and final pages. A present selection_release with no families means that none of the requested families was releasing when the actor answered. An absent message means the daemon did not report its release state. A zero count therefore means that no matching rows are visible yet. Release batches invalidate continuations through the usual scope generations. Clients that omit the opt-in receive their page after release. Older daemons ignore the opt-in and finish the synchronous release before answering.

Every response also carries total_count: the exact filtered count for the whole selected view, regardless of page size. This is the contract behind rbgp rib --count and rbgp rib received|advertised <PEER> --count, which request a single-row page and read only total_count. For an address that names no known peer the count fails with NOT_FOUND rather than reporting zero (unknown peers).

Exact-prefix filters use existing prefix lookups for Received, Best, and clean Advertised views; other predicates then examine only that prefix's candidate rows. Family-only first pages seek into the existing ordered indexes and read maintained family counts. The one remaining count walk is an update-group member's Advertised total, which visits that member's own export rejections. Ordering, filtered totals, and continuation-token rules are unchanged.

This is not a complete bound on RIB actor work. Member-local exclusions can still require scans, a cold Best index can require rebuilding, and dirty grouped Advertised baselines still scan their admitted rows. Filters without an exact prefix can also scan the selected scope. Pagination bounds the returned rows, not the work of every query.

The same contract backs rbgp rib --limit N, rbgp rib received PEER --limit N, and rbgp rib advertised PEER --limit N for N from 1 through 1000 (--limit 0 is a usage error). A limited query issues one RPC and exposes the exact total_count plus whether the returned page is complete; it never follows a continuation into a potentially changing table on its own. When more routes match, human output prints Next page token: <token>, --json adds next_page_token to its envelope, and the rbgp-rib/1.1 JSON-lines end record carries the same field. Pass it back with --page-token and the same view, --limit, and filters for the next page; a table change between pages makes the daemon refuse the continuation with ABORTED, so restart without the token. Unbounded CLI listings retain the version-fenced full-walk behavior described above.

Route.validation_state is the route's recorded RPKI origin-validation verdict, not a configuration/readiness sentinel. not_found means the validation table applied to that route had no covering VRP. It is therefore the natural value for every route when no [rpki] sources are configured, but on a configured and ready deployment it is a real per-route uncovered-origin result. Consumers must use the RPKI cache/readiness surfaces when they need to distinguish those deployment states; this route field cannot do so by itself. The rpki_validation request filter selects that recorded fact and therefore inherits the same distinction. aspa_validation likewise selects the recorded per-route ASPA fact rather than cache readiness.

Watch route changes (streaming)

Live route deltas stream through EventService.WatchEvents with EVENT_CATEGORY_ROUTE (see Watch unified events).

# Live route stream (streams until interrupted)
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"categories": ["EVENT_CATEGORY_ROUTE"]}' \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

# Watch changes for a specific peer and family
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"categories": ["EVENT_CATEGORY_ROUTE"], "neighbor_address": "10.0.0.2", "afi_safi": "ADDRESS_FAMILY_IPV4_UNICAST"}' \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

Each route event arrives as a BgpEvent whose route payload is the same RouteEvent message that ListRouteEvents returns. Event types: ROUTE_EVENT_TYPE_ADDED, ROUTE_EVENT_TYPE_WITHDRAWN, ROUTE_EVENT_TYPE_BEST_CHANGED, and ROUTE_EVENT_TYPE_POLICY_FILTERED. Policy-filtered events are route-level export-policy denials: peer_address is the source route peer, target_peer_address is the outbound peer whose export policy denied the route, and reason is currently policy_denied.

Each RouteEvent carries an event_id, a monotonic process-local cursor that is assigned before the event is written to history and broadcast to live subscribers. The cursor resets on daemon restart and is not reused within one process.

WatchEvents does not backfill recent events for new subscribers. Clients that need both context and a live tail should call ListRouteEvents first, then open a live stream for subsequent deltas (rbgp events watch --backfill 50 does exactly this). WatchEvents emits BGP_EVENT_TYPE_STREAM_LAGGED with a StreamLagEvent payload when a subscriber falls behind the bounded route broadcast.

List recent route events

# Return the recent route-event timeline (oldest-to-newest within the window)
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"limit": 100}' \
  localhost:50051 rustbgpd.v1.RibService/ListRouteEvents

# Filter by peer and IPv4 unicast
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"neighbor_address": "10.0.0.2", "afi_safi": "ADDRESS_FAMILY_IPV4_UNICAST", "limit": 50}' \
  localhost:50051 rustbgpd.v1.RibService/ListRouteEvents

# Drill into one exact prefix
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"prefix": "203.0.113.0", "prefix_length": 24, "limit": 20}' \
  localhost:50051 rustbgpd.v1.RibService/ListRouteEvents

ListRouteEvents reads the same unicast route events that feed WatchEvents, but from a bounded 4096-event in-memory ring. Peer filters match peer_address, previous_peer_address, and target_peer_address, so a peer-scoped query includes withdraws, best-path moves away from that peer, and routes filtered by that peer's export policy. Prefix filters are exact-match only and can be combined with peer, family, and limit filters. The filter does not do containment or longest-prefix matching, so a query for 203.0.113.0/16 will not return an event recorded for 203.0.113.0/24. event_id values are monotonic within the running daemon and can be used by clients to de-duplicate a history window against a live stream. They are not persisted or reused within one process. The history is process-local and resets on daemon restart.

List FlowSpec routes

# List global IPv4 and IPv6 FlowSpec routes (SAFI 133)
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.RibService/ListFlowSpecRoutes

# List only IPv6 FlowSpec routes
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"afi_safi": "ADDRESS_FAMILY_IPV6_FLOWSPEC"}' \
  localhost:50051 rustbgpd.v1.RibService/ListFlowSpecRoutes

ADDRESS_FAMILY_UNSPECIFIED (0) selects only global IPv4 and IPv6 FlowSpec (SAFI 133), in every view: selected, local intent, received and advertised. The explicit global families also exclude VPN rules. Select ADDRESS_FAMILY_L3VPN_IPV4_FLOWSPEC (13) or ADDRESS_FAMILY_L3VPN_IPV6_FLOWSPEC (14) to read the corresponding VPN FlowSpec family (AFI 1 or 2 / SAFI 134). Its rows carry rd and typed route_targets; the RTs also remain in raw extended_communities. VPN receive/reflection is outside the origination contract: received SAFI 134 is decoded and discarded, so remote received views have no retained VPN rows. See the VPN controller contract.

rbgp --json flowspec retains the legacy formatted components array and also emits ordered component_details records with the API component type, prefix, value, and offset. The explicit offset preserves the RFC 8956 IPv6 prefix-match semantics, including zero and nonzero values. When a returned row contains VPN scope, JSON also preserves nonempty rd and route_targets; empty fields are omitted, preserving global output. The CLI accepts and renders l3vpn_ipv4_flowspec and l3vpn_ipv6_flowspec, and includes RD/RTs in text rows. Select a VPN family explicitly with --family; flowspec add takes --rd and repeated --route-target flags, and flowspec delete takes the same --rd.

Each row reports its action communities twice: typed in actions, and raw in extended_communities (8-octet values) or ipv6_extended_communities (20-octet values from path attribute 25). Each entry in the latter protobuf bytes list is exactly 20 octets. Unknown values, reserved bits, order and duplicates survive in the raw lists. The CLI JSON represents each 20-octet value as an array of octets and omits the new list when empty. Only the raw list carries a community the API does not model, so a client that cross-checks the two should expect each typed action to have a raw twin. actions types traffic-rate-bytes (traffic_rate), traffic-rate-packets (traffic_rate_packets), traffic-action, traffic-marking, direct target-IP redirect/copy (redirect_ip), and three VRF redirect forms. A VRF redirect's route_target selects its form, on input and in listings:

route_targetExtended community
ASN:value, ASN up to 65535, 32-bit valueRedirect 2-octet AS (0x8008)
a.b.c.d:value, 16-bit valueRedirect IPv4 address (0x8108, RFC 7674)
ASN:value, ASN above 65535, 16-bit valueRedirect 4-octet AS (0x8208, RFC 7674)
high.low:value (RFC 5396 asdot+), 16-bit valueRedirect 4-octet AS, for any ASN

A listing renders a 4-octet-AS redirect whose ASN fits in 16 bits in RFC 5396 asdot+ form, 0.ASN:value. A plain ASN:value with that ASN would select the 2-octet-AS community instead, so the asdot+ spelling is what keeps the 4-octet-AS encoding when a controller reads a rule back and re-injects it. The v1 controller boundary pins these typed actions, packet rate included, as API shape only: it makes no forwarding or enforcement guarantee for any action. AddFlowSpec does not deduplicate the existing actions against raw values: send each action once, typed or raw. The new redirect_ip rejects any raw target-IP action in either list when a typed target-IP action is also present, even if the targets or copy bits differ. Raw-only lists remain lossless.

traffic_marking: { dscp: 46 } originates the traffic-marking community 0x8009 (RFC 8955 §7.5). dscp must be 0 to 63: AddFlowSpec, AddLeasedFlowSpec and AddGuardedFlowSpec return INVALID_ARGUMENT for a larger value before mutation, on every FlowSpec family. A raw 0x8009 value is advertised as supplied; the typed projection ignores the two reserved bits above the DSCP of a raw or received community and the raw list retains them.

redirect_ip: { address: "192.0.2.10", copy: false } originates the direct IPv4 target community 0x010c. An IPv6 literal originates 0x000c in the 20-octet IPv6 Address Specific Extended Communities attribute (type 25). copy: true sets the copy bit; false redirects the original traffic. Target addresses must be IP literals; unspecified, multicast and IPv4 broadcast addresses, hostnames, CIDRs and scoped literals return INVALID_ARGUMENT before mutation. Originated reserved bits are zero; received reserved bits are ignored by the typed projection and retained raw. This follows draft-ietf-idr-flowspec-redirect-ip-16, which is still an Internet-Draft. Neither the existing VRF redirect action nor the legacy next-hop-based 0x0800 encoding is an alias for this action.

Pin controller stubs to a release that implements these fields: an older protobuf server may ignore an unknown action or raw list. An accepted add is not a feature probe. These additive fields do not add a bounded authorization deadline or per-admission revision to leased mutation; an RPC timeout still does not cancel an admitted operation. A safety-sensitive diversion controller needs those additional safeguards and exact router/software qualification; this action/read-back slice does not provide them. See ADR-0143.

The ordinary ListFlowSpecRoutes response remains the selected Loc-RIB view in routes. Set received_peer_address to an IP address to inspect that peer's retained, post-import-policy candidates instead, including nonselected and infeasible rules. afi_safi narrows all three views. Invalid peer addresses are rejected before the query reaches the RIB. The address 0.0.0.0 selects the rules injected through InjectionService; see the FlowSpec injection contract.

Received mode returns received_routes and sets received_view: true, even when empty; ordinary mode leaves both unset. An empty received view for an address that names no known peer returns NOT_FOUND instead (unknown peers). Clients must check this acknowledgement because older servers ignore the additive request field. rbgp flowspec received PEER [-a FAMILY] performs that check and reports an unsupported operation instead of displaying an older server's selected routes as received candidates.

Set advertised_peer_address to inspect the destination peer's committed post-export-policy Adj-RIB-Out. The response uses routes and sets advertised_view: true, including for an empty result; received_view stays false. Both peer selectors together return INVALID_ARGUMENT. Unknown peers return NOT_FOUND; until the initial configured-peer roster is installed, an unresolved peer returns UNAVAILABLE. A known peer with no negotiated FlowSpec family returns an acknowledged empty view. Each row's peer_address is the source peer, including 0.0.0.0 for local injection, not the queried destination. Export denials and suppression omit rows; export modifications appear in the committed attributes and actions.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"advertised_peer_address":"192.0.2.1"}' \
  localhost:50051 rustbgpd.v1.RibService/ListFlowSpecRoutes
rbgp flowspec advertised 192.0.2.1 -a ipv4_flowspec

Clients must check advertised_view before interpreting the rows: an older server ignores the selector and returns its selected Loc-RIB instead. rbgp flowspec advertised PEER [-a FAMILY] rejects that unacknowledged response. This gRPC mode belongs to the scoped controller contract and retains the sensitive_read authorization tier.

"Committed" means admitted to the destination's outbound channel. When that channel is full, the peer becomes outbound-dirty and this view retains the previous committed rows until resynchronization succeeds, including a prior row awaiting withdrawal. Admitted updates can still await transport encoding or socket writes. This is local state, not evidence that the edge accepted, installed, or enforced a rule. Reads filter inside the RIB task before copying rows and check cancellation at bounded visit intervals; they still walk the destination's FlowSpec table and return a unary response, without pagination.

Each received row contains the existing route projection plus path_id, selected, validation, reason, and pending. Validation is disabled, local, feasible, or infeasible; pending is the validation value only when no result has completed for this candidate. Otherwise a pending revalidation preserves the last completed value and reason, with pending: true. Selection is reported independently: a completed feasible result does not mean the candidate currently owns the selected entry.

Infeasibility reasons are missing_destination, nonzero_destination_offset, no_covering_unicast, local_covering_unicast, missing_as_path, unsupported_as_path, originator_mismatch, leftmost_as_mismatch, unknown_neighbor_as, and conflicting_more_specific. An empty reason means no completed failure. local_covering_unicast names an eBGP rule whose best-match cover is a locally injected unicast route without an AS_PATH, which cannot supply the leftmost AS that RFC 9117 section 4.2 requires. Received means retained after import policy, not a historical record of every UPDATE. See the feasibility decision for opt-in validation and convergence semantics.

Bounded VPN, labeled, RTC, BGP-LS and EVPN best pages

ListVpnRibRoutes, ListLabeledRibRoutes, ListRtcRibRoutes and ListBgpLsRibRoutes require view = BEST (1), RECEIVED (2) or ADVERTISED (3). UNSPECIFIED (0) and unknown values return INVALID_ARGUMENT. Received and advertised require neighbor_address: it names the source for accepted post-policy input, or the destination for local export state. Best accepts only the optional source_peer_filter, which selects a winner's source. A neighbor in Best or a source filter in a peer view returns INVALID_ARGUMENT.

Advertised rows keep the source peer in peer_address; they do not prove remote receipt. Unknown received or advertised neighbors return NOT_FOUND, while a known peer with no matching routes gets an empty page. An unknown Best source returns an empty page. Group-owned VPN advertised pages return FAILED_PRECONDITION while the destination is dirty, awaiting resync, or its outbound receiver is closed before peer teardown: shared staging cannot reconstruct that peer's last admitted announcements or undelivered withdrawals. Retry after export settles or a new session registers. The existing operator count projection retains its behavior; the new page never presents deferred desired rows as committed advertised routes.

VPN and labeled pages take typed AddressFamily values in afi_safi: ADDRESS_FAMILY_L3VPN_IPV4_UNICAST (8), ADDRESS_FAMILY_L3VPN_IPV6_UNICAST (9), ADDRESS_FAMILY_IPV4_LABELED_UNICAST (10), or ADDRESS_FAMILY_IPV6_LABELED_UNICAST (11), as appropriate. ADDRESS_FAMILY_UNSPECIFIED (0) selects both address families of that RPC; other values return INVALID_ARGUMENT. Their prefix_filter is an IP address with prefix_filter_length, as in unicast listings. Host bits are normalized. longer_prefixes = true includes longer-or-equal prefixes; otherwise the match is exact. An empty prefix selects all prefixes, requires length 0, and makes longer_prefixes irrelevant.

VPN also accepts an exact typed rd_filter, using the same lossless RD grammar as legacy EVPN reads, peer pages, explain, event filters and injection.

RTC accepts ADDRESS_FAMILY_UNSPECIFIED (0) or ADDRESS_FAMILY_IPV4_RT_CONSTRAIN (12). It uses native membership fields rather than IP prefixes or RDs: optional origin_as_filter and exact full /96 route_target_filter (RT:65000:1, numeric ASN or IPv4 administrator), or 0x plus 16 raw hexadecimal digits. Raw input must encode a Route Target extended community; it preserves the administrator encoding. Default and partial RTC memberships remain visible without that full-target filter.

BGP-LS accepts ADDRESS_FAMILY_UNSPECIFIED (0), ADDRESS_FAMILY_BGP_LS (6) or ADDRESS_FAMILY_BGP_LS_VPN (7), and an optional raw nlri_type_filter (0 selects every type). Rows are ordered by family, raw NLRI type, Route Distinguisher, opaque NLRI bytes, source and path, so a page walk visits each row once. A continuation token carries the last row's NLRI bytes, so BGP-LS tokens can be larger than other family tokens.

ListBestEvpnRoutes reads installed best routes. Its optional filters are route_type_filter (0 or 1–6), source_peer_filter, rd_filter, exact Type 2 mac_filter, exact 10-byte esi_filter, and vni_filter (0–16777215). Filters combine with AND. Types without the selected MAC or ESI do not match. VNI means a VXLAN Encapsulation Extended Community (tunnel type 8) and either Type 2 label, the Type 1 per-EVI label, the Type 5 label, or Type 3's PMSI label field. An MPLS label with the same numeric value does not match.

Every request takes page_size (0 defaults to 100; values above 1000 clamp to 1000) and an opaque page_token. Responses carry routes, total_count, next_page_token and page_version { epoch, generation }. Only the page's rows are cloned, using O(page) temporary storage. These unordered family tables are scanned per page to compute filtered counts; pagination bounds allocation, not scan CPU. Tokens include scope, canonical filters, family, source and Add-Path identity. A table mutation returns ABORTED; restart with an empty token. Tokens are process-local and cannot survive a daemon restart. Changed scope/filter or malformed tokens return INVALID_ARGUMENT.

These five RPCs are inventoried within their scoped RR-only roles. EVPN calls must select each of Types 1–5 separately to stay inside its role; all-types and Type 6 calls remain alpha, as do the prefix_sid and smet entry fields. The best-request filters are included; the existing EVPN peer MAC/ESI/VNI filters remain explicitly unstable. Authorization is unchanged: all five methods require sensitive_read.

The whole-table ListVpnRoutes, ListLabeledRoutes, ListRtcRoutes, ListBgpLsRoutes and ListEvpnRoutes methods are deprecated and outside v1. Their replacements are ListVpnRibRoutes, ListLabeledRibRoutes, ListRtcRibRoutes, ListBgpLsRibRoutes with view = BEST, and ListBestEvpnRoutes, respectively. Existing methods retain their signatures and behavior; this change removes none. Older servers return UNIMPLEMENTED for the bounded methods: do not silently fall back when a caller requires bounded pages or peer views.

rbgp rib vpn received 192.0.2.1 --rd 65000:100 --prefix 10.0.0.0/24 --limit 100
rbgp rib labeled advertised 192.0.2.2 -a labeled-v4 --limit 100
rbgp rib rtc received 192.0.2.1 --route-target RT:65000:100 --limit 100
rbgp evpn best --mac 00:11:22:33:44:55 --vni 100 --limit 100

The new CLI pages print a JSON object with view, neighbor (nullable for unscoped best), routes, total_count, next_page_token and page_version. The plain list commands keep their JSON arrays and build them by walking every bounded page, so rows come out in the pages' key order. --page-token continues the selected page; --page-size aliases --limit. Per-peer views and filtered queries default to 100 rows. No CLI command requests an old whole-table RPC.

Route Distinguisher identity

Every RD-typed API request accepts structured text (65000:100 or 192.0.2.1:100) or 0x/0X followed by exactly 16 hexadecimal digits for the complete eight wire bytes. This includes legacy EVPN lists, paged VPN and EVPN reads, export explain, exact EVPN selectors, event filters, and EVPN injection or withdrawal. Empty optional filters select any RD; an empty VPN export-explain RD still selects unicast. An exact selector or injection requires a nonempty RD.

API and CLI output renders a Type 2 RD whose ASN is at most 65535 in canonical lowercase raw hexadecimal: 0x00020000fde80064 is distinct from the Type 0 RD 65000:100. Other RD display forms remain unchanged. Feed the returned RD text into a filter or selector to retain the same identity. The published wire crate's text parsing and display behavior are unchanged.

Existing persisted event labels and payloads keep their historical spelling; they are not migrated or made newly distinguishable by this correction. New EVPN event envelopes and payloads use the same lossless spelling.

List EVPN routes

The deprecated ListEvpnRoutes retains its existing unpaginated best-route view outside v1; use ListBestEvpnRoutes for bounded best pages. The ListReceivedEvpnRoutes and ListAdvertisedEvpnRoutes methods require neighbor_address and accept route_type_filter (0 or 1–6), rd_filter, page_size, and page_token. They also accept the explicitly unstable mac_filter, esi_filter, and optional vni_filter, with the same matching rules as ListBestEvpnRoutes. The EVPN route-reflector boundary includes calls filtered to Types 1–5 through its inventoried fields and JSON floor; all-types and Type 6 calls remain alpha. Older servers return UNIMPLEMENTED without falling back to a unicast table.

Requests with MAC, ESI or VNI filters return response metadata x-rustbgpd-evpn-peer-filters: mac,esi,vni. Clients must check this acknowledgement before interpreting rows or counts: older daemons can silently ignore additive request fields. rbgp fails before printing text or JSON when the acknowledgement is absent or different. Calls without those filters keep their existing response behavior.

Received means accepted post-policy Adj-RIB-In, including candidates that are not best. An absent route does not prove the neighbor never sent it; historical EVPN import rejection details are not retained. Advertised means committed Adj-RIB-Out for the requested destination, after export gates and successful outbound enqueue. It does not confirm remote receipt or installation. Each row's peer_address remains its original source peer, which may differ from the requested destination. Use exact EVPN explain for candidate-selection and destination export diagnostics.

These peer methods return one page with routes, total_count, next_page_token, and page_version. The default page size is 100; the maximum is 1000, and larger requests clamp to 1000. Rows are ordered by typed EVPN route identity and source peer. Use the returned token with the same neighbor, direction, and filters to continue. Changed scope or filters, malformed or modified tokens return INVALID_ARGUMENT; table mutations return ABORTED, requiring a restart from an empty token. An empty page for an address that names no known peer returns NOT_FOUND (unknown peers). Tokens expire on daemon restart. Version counters are conservative across peers and families in the same table class, so an unrelated mutation can also invalidate a walk. Types 3/4, attribute changes, retained-route lifecycle changes, and peer teardown participate.

Each page scans the selected table: O(table size × log page size) work and O(page size) retained route references/copies. Pagination bounds response memory; it does not provide an index or a snapshot retained across mutations.

rbgp evpn received 192.0.2.1 --route-type 2 --rd 65000:100 --limit 100
rbgp evpn advertised 192.0.2.2 --rd 65000:100 --limit 100

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"neighbor_address":"192.0.2.2","route_type_filter":2,"rd_filter":"65000:100","page_size":100}' \
  localhost:50051 rustbgpd.v1.RibService/ListAdvertisedEvpnRoutes

The CLI prints one page and its continuation metadata; pass --page-token '<token>' to resume, quoting the opaque token for the shell. --json returns a page object. For selected Loc-RIB pages, use ListBestEvpnRoutes: each example below returns one page, not the whole table. Repeat the same filters with the returned next_page_token until it is empty; after ABORTED, restart with an empty token. Plain rbgp evpn walks every page itself and prints one listing; after ABORTED it fails without retrying.

# First Loc-RIB page across all supported types (outside the scoped v1 profile)
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"page_size":100}' \
  localhost:50051 rustbgpd.v1.RibService/ListBestEvpnRoutes

# First Type 2 (MAC/IP) page within the scoped RR-only role
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"route_type_filter":2,"page_size":100}' \
  localhost:50051 rustbgpd.v1.RibService/ListBestEvpnRoutes

# First Type 2 page filtered by Route Distinguisher
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"route_type_filter":2,"rd_filter":"65000:100","page_size":100}' \
  localhost:50051 rustbgpd.v1.RibService/ListBestEvpnRoutes

# Continue the preceding filtered query with its returned nonempty token
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"route_type_filter":2,"rd_filter":"65000:100","page_size":100,"page_token":"<next_page_token>"}' \
  localhost:50051 rustbgpd.v1.RibService/ListBestEvpnRoutes

For the deprecated ListEvpnRoutes, route_type_filter accepts 0 (no filter) or 1..=6 matching the EVPN route type numbers (RFC 7432, RFC 9136, and RFC 9251 Type 6). peer_filter is an optional typed IP-address match (for example, expanded and compressed IPv6 spellings are equivalent); rd_filter is an optional typed route-distinguisher match using the shared RD input grammar, including raw hexadecimal for every RD type. Empty strings disable each filter. Invalid filters fail with INVALID_ARGUMENT before the RIB actor is queried.

Type 6 rows carry the optional EvpnRouteEntry.smet message (EvpnSmetView): source, group, originator_ip, and the raw flags byte (0–255). Each source/group is an EvpnSmetAddress with an explicit oneof value: {"wildcard":true} or {"ip":"239.1.2.3"}. A wildcard group requires a wildcard source; concrete source and group addresses must share a family. The originator address may use either family independently. CLI JSON renders source and group as "*" or IP strings. Flags remain payload and do not form part of the key. Type 6 is alpha relay support; see the SMET boundary.

Explain an exact EVPN route

RibService.ExplainEvpnRoute takes a required EvpnRouteSelector in key: its rd and exactly one route-specific selector identify a single NLRI. Optional received_from looks up one retained source, and advertised_to evaluates one destination. Both are neighbor IP addresses. This additive, sensitive_read RPC is outside the narrow v1 contract; older servers return UNIMPLEMENTED. Existing unicast explain requests keep their current meaning.

The CLI uses rbgp evpn explain <selector> --rd <RD> with optional --received-from <PEER> and --advertised-to <PEER>. Put these options after the selector. Each selector is an exact key lookup, with no pattern or longest-prefix matching:

CLI selectorProto selectorRequired key fields beyond RDEthernet Tag
ead-per-esead_per_es--esiCLI fixes it to MAX_ET; RPC requires 4294967295
ead-per-eviead_per_evi--esi, --ethernet-tagRequired; MAX_ET is rejected
mac-ipmac_ip--mac; optional --ip--ethernet-tag defaults to 0
imetimet--originator-ip--ethernet-tag defaults to 0
eses--esi, --originator-ipNot part of the Type 4 key
ip-prefixip_prefix--prefix in canonical CIDR form--ethernet-tag defaults to 0; nonzero tags are supported
smetsmet--source, --group, --originator-ip--ethernet-tag defaults to 0

For Type 2, omitting --ip (an empty RPC ip) selects the MAC-only key; it does not match every host IP attached to that MAC. Type 5 prefixes must have zero host bits. ESI uses ten colon-separated hex octets; MAC uses six. Labels, next hop, and gateway are route payload, not selector fields. Invalid selectors return INVALID_ARGUMENT before querying the RIB.

For Type 6, source and group must be explicit. The CLI accepts an IP or the quoted literal '*'; RPC selectors use the same EvpnSmetAddress oneof as route views, and wildcard must be true. This selects the route's literal wildcard field, not every source or group. A wildcard group requires a wildcard source, concrete source/group families must agree, and the originator family is independent. Flags are not selector fields.

# Exact MAC-only route, with source and destination diagnostics
rbgp evpn explain mac-ip --rd 65000:100 --mac 02:00:00:00:00:11 \
  --received-from 10.0.0.1 --advertised-to 10.0.0.2

# The same MAC with a host IP is a distinct key
rbgp evpn explain mac-ip --rd 65000:100 --mac 02:00:00:00:00:11 \
  --ip 192.0.2.11 --advertised-to 10.0.0.2

# Type 6: exact wildcard-source route with an independent IPv6 originator
rbgp evpn explain smet --rd 65000:100 --source '*' --group 239.1.2.3 \
  --originator-ip 2001:db8::1 --advertised-to 10.0.0.2

# Type 5 supports an exact IPv6 prefix and a nonzero Ethernet Tag
rbgp evpn explain ip-prefix --rd 65000:100 --ethernet-tag 100 \
  --prefix 2001:db8:100::/64 --advertised-to 10.0.0.2

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"key":{"rd":"65000:100","imet":{"ethernet_tag":0,"originator_ip":"10.0.0.1"}},"received_from":"10.0.0.1","advertised_to":"10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.RibService/ExplainEvpnRoute

The response is a read-only snapshot for that exact key. It walks the peer roster using exact lookups and returns a bounded number of routes, rather than copying every candidate or scanning the full EVPN table. --json exposes the same distinctions as the text output:

FieldMeaning
receivedAccepted post-policy Adj-RIB-In route from received_from, if retained. Omitted when no source is requested or no accepted route is retained.
candidate_countNumber of currently retained accepted candidates across sources.
bestInstalled Loc-RIB route.
selection_bestWinner of a fresh comparison over the retained candidates, without installing it.
comparedRequested retained source when it loses; otherwise the runner-up when the source wins or none was requested. Absent when the requested source is not retained or there is no comparison.
selection_reasonDecisive reason why selection_best beats compared; absent without a pair.
selection_deferredEVPN selection is currently deferred; the installed best may differ from fresh selection or be absent.
exportPresent only when advertised_to was requested.

Selection uses the live EVPN comparator: freshness ranks precede Type 2 sticky and MAC Mobility sequence preferences, followed by the remaining BGP criteria. A fresh comparison can still select a stale route if that is the best retained candidate. Missing input is not an import rejection explanation: historical EVPN import rejection details are not retained, and absence does not prove that a peer never sent this key.

export.decision, reasons, gates, and modifications describe a current dry run through the shared export staging path, using installed best. export.staged is the post-policy candidate that clears that path, while export.advertised is the committed local Adj-RIB-Out route for the requested destination. Each route's peer_address remains its source; export.peer_address names the destination. A missing outbound session is reported as a stopping destination_unavailable gate.

already_advertised means staging found an identical committed route and suppressed a duplicate advertisement. outbound_dirty is a destination-wide resynchronization flag, not proof that this particular route is pending. A retained exact-encoder rejection can stop an otherwise eligible candidate. The query neither sends nor freshly encodes an UPDATE, and committed state is not proof of remote receipt, acceptance, or installation.

Inspect an explicit SRv6 Argument pair

For an IMET key, optional srv6_argument_companion (request field 4) selects one exact EAD-per-ES key with MAX_ET and a nonzero ESI. Its RD is independent of the IMET RD. The CLI exposes this only on evpn explain imet as paired --argument-rd and --argument-esi options:

rbgp --json evpn explain imet --rd 65000:100 --originator-ip 192.0.2.3 \
  --argument-rd 65000:200 --argument-esi 00:11:22:33:44:55:66:77:88:99 \
  --advertised-to 192.0.2.9

Both routes are read in one RIB actor turn. received_from selects the same accepted-source Adj-RIB-In for both; advertised_to selects the same committed local Adj-RIB-Out for both; neither selects installed Loc-RIB. Both peer filters together return INVALID_ARGUMENT when a companion is requested. The primary snapshot remains in received, export.advertised, or best, respectively. Fresh selection and staged export are never composition inputs.

The optional srv6_argument response (field 11) records companion_key, the retained companion snapshot if present, scope (received, advertised or best), scope_peer, status, detail, optional sid, and association. The companion route's peer_address remains its source; scope_peer identifies the requested source or destination. CLI JSON adds srv6_argument only for a pair request and omits its sid when no candidate can be computed.

StatusMeaning
COMPOSED / composedA candidate SID combines the IMET LOC:FUNC with the selected companion's Argument.
LOC_FUNC_ONLY / loc_func_onlyA candidate LOC:FUNC SID with zero Argument bits, including when no usable companion Argument is present or the IMET Argument length is zero.
CONFLICT / conflictBoth relevant Argument lengths are nonzero and differ; no candidate SID. This concerns the requested pair, not route selection.
UNAVAILABLE / unavailableRequired SID, structure, label or transposition input cannot be used; no candidate SID.
AMBIGUOUS / ambiguousMultiple SID entries, structures or label sources prevent a unique result; no candidate SID.

For transposed IMET Function bits, inspection uses the same PMSI label limits as the per-route view: 24 bits for ingress replication (0x06) and 20 high-order bits for SRv6 P2MP (0x0d). A missing or unsupported PMSI tunnel type makes the Function unavailable; duplicate label sources remain ambiguous.

This is alpha, read-only RFC 9819 section 3.3 inspection. The association is always caller_selected: computation is conditional on the caller choosing the applicable same-egress Ethernet Segment route. Retained peer, RD and next-hop metadata do not establish original egress identity. The result does not assert forwarding, remote receipt or installation, and no pairing search or service origination is performed. Advertised SID values, raw Prefix-SID bytes and per-route Function reconstruction are unchanged.

Omitting the companion preserves the existing request meaning and CLI text and JSON shape. An older server can ignore the additive request field; the CLI then fails explicitly if the requested srv6_argument response is absent.

List BGP-LS routes

# First page of BGP-LS and BGP-LS VPN routes in Loc-RIB
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"view": "FAMILY_ROUTE_VIEW_BEST", "page_size": 1000}' \
  localhost:50051 rustbgpd.v1.RibService/ListBgpLsRibRoutes

# BGP-LS only, selected from one peer, for Node NLRI; repeat with
# "page_token" set to each non-empty next_page_token
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"view": "FAMILY_ROUTE_VIEW_BEST", "afi_safi": "ADDRESS_FAMILY_BGP_LS", "source_peer_filter": "10.0.0.2", "nlri_type_filter": 1}' \
  localhost:50051 rustbgpd.v1.RibService/ListBgpLsRibRoutes

ListBgpLsRibRoutes is the ADR-0077 controller-facing BGP-LS surface; see bounded pages for its views, paging and errors. rbgp rib bgpls walks every page and prints one JSON array. The deprecated whole-table ListBgpLsRoutes remains outside v1 with its original afi_safi, peer_filter and nlri_type_filter request. It preserves BGP-LS routes as opaque RFC 9552 objects: raw Route Distinguisher bytes for BGP-LS VPN, raw NLRI descriptor/payload bytes, and raw BGP-LS Attribute (type 29) bytes when present. Negotiated BGP-LS routes can also be reflected to eligible peers through the normal route-reflector pipeline and feed the RFC 9107 ORR topology used for per-vantage best-path selection. The daemon does not synthesize BGP-LS from a local LSDB or negotiate BGP-LS Add-Path. GR / LLGR stale preservation for BGP-LS and BGP-LS VPN is implemented as part of the RR-family stale pipeline. Its afi_safi filter accepts only unspecified, BGP-LS, or BGP-LS VPN. As with EVPN, VPN, labeled-unicast, and RT-Constrain route listings, a non-empty peer filter must parse as an IP address and matches by address identity rather than display spelling.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"page_size": 1000}' \
  localhost:50051 rustbgpd.v1.RibService/ListOrrTopologyNodes

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"page_size": 1000}' \
  localhost:50051 rustbgpd.v1.RibService/ListOrrTopologyLinks

ListOrrTopologyNodes and ListOrrTopologyLinks page the RFC 9107 topology built from every peer's BGP-LS Adj-RIB-In. Nodes are ordered by canonical node key. Links are ordered by local key, remote key, then the Link NLRI (Route Distinguisher and bytes), so parallel links between the same endpoints each appear once even when their visible fields match. Paging follows the bounded family contract: page_size 0 defaults to 100 and values above 1000 clamp to 1000. Tokens are process-local and signed. Any BGP-LS input change returns ABORTED; restart with an empty token. A changed or malformed token returns INVALID_ARGUMENT. A link token carries its Link NLRI bytes, so it can be larger than other family tokens. rbgp topology nodes and rbgp topology links walk every page and keep their JSON arrays. Both methods require sensitive_read.

The whole-graph ListTopologyNodes and ListTopologyLinks remain functional, with unchanged signatures and behavior, but are deprecated and outside v1. ListOrrStatus stays unpaged: configured vantages bound its size.

List BLACKHOLE discard status

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.RibService/ListBlackholeDiscards

Returns one row per currently observed best route carrying the RFC 7999 BLACKHOLE community when the opt-in FIB reconciler is active. state is a BlackholeDiscardState enum (BLACKHOLE_DISCARD_STATE_INSTALLED, BLACKHOLE_DISCARD_STATE_REJECTED, or BLACKHOLE_DISCARD_STATE_FAILED); reason carries values such as installed, owned, adopted, adopted_pending_reap, broad_prefix, not_ebgp, active_limit_exceeded, install_rate_limited, route_churn_deferred, foreign_route_exists, ownership_state_unavailable, receipt_write_failed, dump_failed, remove_failed, reap_failed, or the kernel install error string. receipt_write_failed marks an install refused because the ownership receipt could not be written ahead of it; the next pass retries. Both limit reasons are retryable and may transition to installed when active capacity or a token becomes available. Discard routes adopted from a previous run at startup are also listed: a leftover that no BGP route has claimed yet appears as adopted_pending_reap with an unspecified peer (0.0.0.0 or ::) until it is reaped (reap_failed if the kernel removal fails); one that a BLACKHOLE best route re-claims is reported as adopted with that route's peer. An empty list means either the reconciler is disabled or no BLACKHOLE-marked best routes are currently visible.

List general FIB route status

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.RibService/ListFibRoutes

rbgp rib fib          # human table
rbgp rib fib --json   # JSON array for scripts
rbgp rib fib --table edge --state rejected --reason route_limit_exceeded
rbgp rib fib --prefix 203.0.113.0/24 --neighbor 198.51.100.2
rbgp rib fib --limit 100

Returns one row per desired route, daemon-owned route, or one-pass reconciliation outcome in the ADR-0061 general unicast Linux FIB runtime. The runtime is default-off and only starts when at least one [[fib_tables]] block is configured. state is a FibRouteState enum (FIB_ROUTE_STATE_INSTALLED, FIB_ROUTE_STATE_REJECTED, FIB_ROUTE_STATE_FAILED, or FIB_ROUTE_STATE_UNRESOLVED); reason carries values such as owned, foreign_route_exists, next_hop_family_unsupported, next_hop_unspecified, peer_not_allowed, route_limit_exceeded, owned_route_drifted, next_hop_unresolved, dump_failed:DETAIL, or a kernel apply error such as install_failed:DETAIL. When a pre-kernel planning query fails, this RPC preserves the last successful status snapshot; use bgp_dataplane_reconcile_planning_failures_total and the matching structured warning for the current failure.

ListFibRoutesRequest supports optional filters for table_name, state, reason, exact prefix + prefix_length, and peer_address; filters compose with AND semantics. The prefix filter is an exact route-key match, not longest-prefix or containment matching, so 203.0.113.0/24 does not match 203.0.113.128/25. Empty strings and FIB_ROUTE_STATE_UNSPECIFIED mean "no filter"; for direct gRPC callers, prefix_length must be 0 when prefix is empty. rbgp rib fib exposes the same filters as --table, --state, --reason, --prefix, and --neighbor. page_size and page_token enable optional pagination over the filtered status rows; page_size = 0 keeps the legacy full-snapshot response, and page_token is valid only when page_size > 0. The response includes next_page_token and total_count.

A scoped peer selector such as fe80::1%eth0 matches the row's retained address and interface. Rows with another interface or no recorded interface do not match that selector.

Reads use the last complete status publication. Conversion, base ordering and summary counts run outside the FIB reconciler and API executor; while a newer publication is being prepared, reads can lag native reconciliation. Each publication prepares only its unfiltered order eagerly. The first request for a filter combination can sort the full publication on a blocking worker; later requests reuse that index for exact counts and clone only returned rows. Index preparations are serialized across listeners. Canceling a request leaves its started preparation running to completion without holding the publication lock, so newer status rows can still be published. Unpaged reads still allocate and return the complete matching result. The legacy dataplane event summary uses three counts prepared with the same publication, so polling it does not walk the FIB rows.

CLI JSON output remains a route array unless --limit is given (1 or more; omit it for the full snapshot), in which case it emits an object with routes, next_page_token, total_count, and optional sampling metadata.

table_id, metric, prefix, prefix_length, next_hop, and next_hops describe the route identity and forwarding value. next_hop is the selected best route's representative gateway; next_hops is the canonical installed set for ECMP / multipath rows. The CLI human table renders Table, Metric, Prefix, Next hop, State, and Reason; JSON output uses table_name, table_id, metric, prefix, next_hop, next_hops, peer_address, state, reason, and optional sampling. Sampling is present on high-cardinality rows such as route_limit_exceeded; it reports the number of surfaced sample rows, suppressed rows, total rows in that table/metric/reason set, the configured max_routes, the status sample cap, and whether the sample is complete. Pagination still applies only to surfaced rows: total_count does not include suppressed rows. A pre-existing kernel row in a configured table is reported as foreign_route_exists; RTPROT_BGP is not ownership proof by itself because another daemon can use the same protocol marker. A row rustbgpd previously owned but later finds changed by another writer is reported as owned_route_drifted; the daemon releases ownership and does not delete that replacement on a later withdraw.


EventService

Unified typed live event stream. Current categories are route events, session events (peer lifecycle plus BGP NOTIFICATION sent/received metadata), policy mutation summary events, EVPN route best-path events, dataplane status-row summary changes for the daemon-owned FIB / BLACKHOLE discard reconcilers, live ADR-0061 per-route FIB apply outcomes, and BFD session state changes.

RPCDescription
WatchEventsServer-streaming: unified typed event stream sourced from structured daemon events
ListSessionEventsUnary: recent session lifecycle events from the peer manager's bounded in-memory history
ListPolicyEventsUnary: recent policy / neighbor-set / peer-group / chain mutation events from the peer manager's bounded in-memory history
ListEvpnEventsUnary: recent EVPN route add / withdraw / best-change events from the RIB's bounded in-memory history

Every event carries its time as int64 timestamp_unix_ms, Unix epoch milliseconds captured when the event is recorded: the BgpEvent envelope and each payload (RouteEvent, SessionEvent, NotificationEvent, PolicyEvent, DataplaneRouteEvent, EvpnRouteEvent and BfdSessionEvent) carry the same value. ListRouteEvents returns RouteEvent with the same field. The former decimal-string timestamp fields are removed, and their numbers and names are reserved.

Watch unified events

# Watch the default live route + session events
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

# Watch only route adds for one exact prefix
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"categories": ["EVENT_CATEGORY_ROUTE"], "event_types": ["BGP_EVENT_TYPE_ROUTE_ADDED"], "prefix": "203.0.113.0", "prefix_length": 24}' \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

# Watch session establishment/loss for one peer
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"categories": ["EVENT_CATEGORY_SESSION"], "event_types": ["BGP_EVENT_TYPE_SESSION_ESTABLISHED", "BGP_EVENT_TYPE_SESSION_LOST"], "neighbor_address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

# Watch BGP NOTIFICATIONs for one peer
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"categories": ["EVENT_CATEGORY_SESSION"], "event_types": ["BGP_EVENT_TYPE_NOTIFICATION_SENT", "BGP_EVENT_TYPE_NOTIFICATION_RECEIVED"], "neighbor_address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

# Watch policy / peer-group / chain mutation summaries
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"categories": ["EVENT_CATEGORY_POLICY"], "event_types": ["BGP_EVENT_TYPE_POLICY_CHANGED"]}' \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

# Query recent session establishment/loss history for one peer
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"event_types": ["BGP_EVENT_TYPE_SESSION_ESTABLISHED", "BGP_EVENT_TYPE_SESSION_LOST"], "neighbor_address": "10.0.0.2", "limit": 20}' \
  localhost:50051 rustbgpd.v1.EventService/ListSessionEvents

# Query recent peer-scoped policy mutation history
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"event_types": ["BGP_EVENT_TYPE_POLICY_CHANGED"], "neighbor_address": "10.0.0.2", "limit": 20}' \
  localhost:50051 rustbgpd.v1.EventService/ListPolicyEvents

# Watch FIB / BLACKHOLE dataplane status-row summary changes
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"categories": ["EVENT_CATEGORY_DATAPLANE"], "event_types": ["BGP_EVENT_TYPE_DATAPLANE_STATUS_CHANGED"]}' \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

# Watch per-route FIB install failures for one prefix
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"categories": ["EVENT_CATEGORY_DATAPLANE"], "event_types": ["BGP_EVENT_TYPE_DATAPLANE_ROUTE_FAILED"], "prefix": "203.0.113.0", "prefix_length": 24}' \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

# Watch EVPN route best-path changes for one peer
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"categories": ["EVENT_CATEGORY_EVPN"], "event_types": ["BGP_EVENT_TYPE_EVPN_ROUTE_ADDED", "BGP_EVENT_TYPE_EVPN_ROUTE_WITHDRAWN", "BGP_EVENT_TYPE_EVPN_ROUTE_BEST_CHANGED"], "neighbor_address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.EventService/WatchEvents

# Query recent Type 2 EVPN route events for one RD
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"route_type_filter": 2, "rd_filter": "65000:100", "limit": 20}' \
  localhost:50051 rustbgpd.v1.EventService/ListEvpnEvents

WatchEvents is a live stream only: it does not replay the bounded ListRouteEvents history and it does not persist events. The rbgp events watch --backfill N command composes both RPCs client-side for route events by subscribing live first, printing recent ListRouteEvents results through the same BgpEvent renderer used by the live stream, and suppressing live route events whose event_id was already printed. The command prints a history block followed by the live tail; it does not server-side merge the two streams by wall-clock timestamp.

There is no durable event cursor. A client that reconnects opens and buffers a new live stream first, waits for the WatchEvents response headers (sent only after the daemon has subscribed to every requested source; no event is sent at stream start), then re-reads the state it needs and applies the buffered events, reconciling any overlap. The separate RPCs give no atomic handoff: a change between a state read and a later stream open is lost with no lag signal. gNMI Subscribe ON_CHANGE subscribes before its snapshot internally. BMP to a collector, Prometheus, and the daemon logs are the durable record.

Filters compose AND-wise across category, type, peer, family, and exact prefix. Repeated categories are ORed, repeated types are ORed, and the two dimensions are ANDed. A request is accepted when any selected category/type pair is real; no intersection returns INVALID_ARGUMENT. An empty category or type dimension is a wildcard for compatibility validation (the live default/opt-in selection rules below still apply).

Synthetic BGP_EVENT_TYPE_STREAM_LAGGED control frames bypass ordinary category, type, peer, family, and prefix filters after compatibility validation.

WatchEvents compatibility:

CategoryCompatible event types
RouteBGP_EVENT_TYPE_ROUTE_ADDED, BGP_EVENT_TYPE_ROUTE_WITHDRAWN, BGP_EVENT_TYPE_ROUTE_BEST_CHANGED, BGP_EVENT_TYPE_ROUTE_POLICY_FILTERED, BGP_EVENT_TYPE_STREAM_LAGGED
SessionBGP_EVENT_TYPE_SESSION_STATE_CHANGED, BGP_EVENT_TYPE_SESSION_ESTABLISHED, BGP_EVENT_TYPE_SESSION_LOST, BGP_EVENT_TYPE_PEER_ADDED, BGP_EVENT_TYPE_PEER_REMOVED, BGP_EVENT_TYPE_PEER_ENABLED, BGP_EVENT_TYPE_PEER_DISABLED, BGP_EVENT_TYPE_MAX_PREFIX_WARNING, BGP_EVENT_TYPE_NOTIFICATION_SENT, BGP_EVENT_TYPE_NOTIFICATION_RECEIVED, BGP_EVENT_TYPE_STREAM_LAGGED
PolicyBGP_EVENT_TYPE_POLICY_CHANGED (never BGP_EVENT_TYPE_STREAM_LAGGED)
DataplaneBGP_EVENT_TYPE_DATAPLANE_STATUS_CHANGED, BGP_EVENT_TYPE_DATAPLANE_ROUTE_INSTALLED, BGP_EVENT_TYPE_DATAPLANE_ROUTE_WITHDRAWN, BGP_EVENT_TYPE_DATAPLANE_ROUTE_FAILED, plus BGP_EVENT_TYPE_STREAM_LAGGED only for the per-route source (not the peerless summary source)
EVPNBGP_EVENT_TYPE_EVPN_ROUTE_ADDED, BGP_EVENT_TYPE_EVPN_ROUTE_WITHDRAWN, BGP_EVENT_TYPE_EVPN_ROUTE_BEST_CHANGED, BGP_EVENT_TYPE_STREAM_LAGGED
BFDBGP_EVENT_TYPE_BFD_SESSION_UP, BGP_EVENT_TYPE_BFD_SESSION_DOWN, BGP_EVENT_TYPE_BFD_SESSION_STATE_CHANGED, BGP_EVENT_TYPE_STREAM_LAGGED

Route events are sourced from the structured RIB broadcast, including export-policy denial events (route_policy_filtered) for unicast routes present in Loc-RIB but filtered from an outbound peer; session events are sourced from the peer manager's session broadcast and cover both lifecycle transitions and metadata-only BGP NOTIFICATION sent/received events; policy events are sourced from the peer manager after a runtime policy / neighbor-set / peer-group / chain mutation is accepted and are also retained in the bounded ListPolicyEvents process-local history ring; dataplane summary events are status-row count changes from the existing ListFibRoutes and ListBlackholeDiscards snapshots. ADR-0061 per-route FIB dataplane events are emitted directly by the FIB runtime when a route is installed, withdrawn, or fails to apply; they are live only and are not replayed by ListFibRoutes. EVPN events are sourced from the RIB's EVPN best-path broadcast and are also retained in a bounded ListEvpnEvents process-local history ring. The FIB rejected count reflects surfaced status rows; high-cardinality route_limit_exceeded rows carry ListFibRoutes sampling metadata with suppressed-row totals, so the event count itself is not a global suppressed-route total. Empty category and type filters subscribe to the default route + session live stream. A non-empty type filter narrows the stream; BGP_EVENT_TYPE_POLICY_CHANGED, BGP_EVENT_TYPE_DATAPLANE_STATUS_CHANGED, an ADR-0061 per-route dataplane event type, an EVPN route event type, or a BGP_EVENT_TYPE_BFD_SESSION_* type with empty categories selects the corresponding opt-in stream, and EVENT_CATEGORY_POLICY, EVENT_CATEGORY_DATAPLANE, EVENT_CATEGORY_EVPN, or EVENT_CATEGORY_BFD selects those streams explicitly. Transport sessions send ordinary state-change lifecycle events over a bounded channel that is separate from the lossless TCP collision-coordination path, so high churn can drop observability events without risking collision handling. Live lag warnings emit for route, session, per-route dataplane, EVPN, and BFD sources, but not policy or peerless dataplane. Prefix and family filters match unicast route events and per-route FIB dataplane events; session, policy, EVPN, BFD, and peerless dataplane summary events do not match requests that set prefix or afi_safi. Peer filters match route, session, EVPN, BFD, and per-route FIB dataplane events; route events also match target_peer_address for route_policy_filtered. Peer filters do not match peerless dataplane summary events. BgpEvent repeats common fields such as peer, target peer, prefix, type, and severity at the top level even when the payload also carries them so category-agnostic clients can render or filter events without unpacking the oneof.

ListSessionEvents accepts neighbor_address, lifecycle-only event_types, and limit filters. Valid event_types are the eight session lifecycle types: BGP_EVENT_TYPE_SESSION_STATE_CHANGED, BGP_EVENT_TYPE_SESSION_ESTABLISHED, BGP_EVENT_TYPE_SESSION_LOST, BGP_EVENT_TYPE_PEER_ADDED, BGP_EVENT_TYPE_PEER_REMOVED, BGP_EVENT_TYPE_PEER_ENABLED, BGP_EVENT_TYPE_PEER_DISABLED, and BGP_EVENT_TYPE_MAX_PREFIX_WARNING. Empty event_types means all eight lifecycle types.

The history is one ring for all peers. When it is full, the oldest repeated pre-Established STATE_CHANGED event is evicted first, so a down or flapping peer's connection retries do not push out another peer's ESTABLISHED or LOST record; with no such event left, the oldest event goes. The response carries evicted_total (events lost since daemon start, all peers, also exported as bgp_session_event_history_evicted_total) and oldest_retained_unix_ms (the oldest retained event across all peers, before the request filter or limit). A nonzero evicted_total means rows were dropped: retry (STATE_CHANGED) rows can be missing at any time, while other event types are dropped only once no retry rows remain, oldest first, so those newer than oldest_retained_unix_ms are retained. rbgp events sessions prints a note on stderr when evicted_total is nonzero.

NeighborState.last_error is not cleared when the session reaches Established. last_error_unix_ms is when the session recorded it (0 when there is no error or the message is a daemon-owned latch or refusal). An error older than the current session's establishment, now - uptime_seconds, is history, not a cause. rbgp neighbor shows the time as (at <time>) and in JSON as last_error_unix_ms. BGP_EVENT_TYPE_MAX_PREFIX_WARNING is one crossing of a configured max-prefix warning threshold (max_prefix_warning_percent, or the bound itself under max_prefix_action = "warning"): it carries EVENT_SEVERITY_WARNING, empty old and new states because nothing transitioned, and a reason naming the scope, usage, bound, and threshold percentage. It is never a teardown. Crossings that happen while an earlier warning for the same scope is still queued in the daemon are folded into that warning's single event: its reason then ends with ; N threshold crossings since the last report, and the usage, bound, and threshold it names are those of the first crossing. bgp_max_prefix_warning_total counts every crossing. NOTIFICATION sent/received types are not retained in the history ring and are rejected here with INVALID_ARGUMENT; subscribe to WatchEvents with BGP_EVENT_TYPE_NOTIFICATION_SENT / BGP_EVENT_TYPE_NOTIFICATION_RECEIVED for live NOTIFICATION metadata. Route event types are likewise rejected; use RibService.ListRouteEvents for route history. The history ring holds at most 4096 events; limit = 0 requests that full bounded daemon window, and larger values are clamped to the same ceiling. Responses contain the most recent matching events, ordered oldest-to-newest within that selected recent window.

ListPolicyEvents accepts neighbor_address, BGP_EVENT_TYPE_POLICY_CHANGED, and limit filters. Empty event_types means all policy event types, which is currently equivalent to BGP_EVENT_TYPE_POLICY_CHANGED; route, session, dataplane, and stream_lagged event types are rejected with INVALID_ARGUMENT. A peer filter matches only peer-scoped policy mutations such as neighbor import/export chain changes; global policy, neighbor-set, peer-group, and global-chain mutations are peerless and do not match a neighbor_address filter. The history ring holds at most 4096 events, is process-local, and resets on daemon restart.

ListEvpnEvents accepts neighbor_address, EVPN route-event event_types, route_type_filter, rd_filter, and limit. Valid event types are BGP_EVENT_TYPE_EVPN_ROUTE_ADDED, BGP_EVENT_TYPE_EVPN_ROUTE_WITHDRAWN, and BGP_EVENT_TYPE_EVPN_ROUTE_BEST_CHANGED; empty event_types means all three. The peer filter matches both the current and previous best-path peer so withdrawals and best-path moves away from a peer remain visible to peer-scoped dashboards. route_type_filter accepts EVPN route types 1 through 6 (RFC 7432 / RFC 9136 / RFC 9251), and rd_filter uses the same display format as ListEvpnRoutes. The history ring holds at most 4096 events, is process-local, and resets on daemon restart.

Slow live-stream consumers do not block the daemon. If a WatchEvents subscriber falls behind the bounded broadcast channel, missed events are skipped and bgp_event_stream_lagged_total{service,source} records the missed count. WatchEvents emits an in-band stream_lagged warning for route, session, per-route dataplane, EVPN, and BFD sources. Policy and peerless dataplane lag is metric-only and discarded without an in-band warning. Use bgp_event_stream_subscribers{service,source} to see active stream readers and bgp_route_event_history_depth / bgp_route_event_history_capacity to understand how much recent unicast route history is available through ListRouteEvents. See docs/reference/operations.md for alerting guidance that combines these stream metrics with ADR-0064 authorization decision volume.

Unified event types:

TypeMeaning
BGP_EVENT_TYPE_ROUTE_ADDEDBest path for a prefix was added
BGP_EVENT_TYPE_ROUTE_WITHDRAWNBest path for a prefix was withdrawn
BGP_EVENT_TYPE_ROUTE_BEST_CHANGEDBest path for a prefix changed
BGP_EVENT_TYPE_SESSION_STATE_CHANGEDBGP FSM state changed; payload carries old/new state and session role
BGP_EVENT_TYPE_SESSION_ESTABLISHEDFSM reached Established
BGP_EVENT_TYPE_SESSION_LOSTFSM left Established; severity is WARNING
BGP_EVENT_TYPE_PEER_ADDEDPeer entered the authoritative managed set; payload carries new state idle and the neighbor's exact address and interface. An idle dynamic neighbor kept for Graceful Restart retention stays in the set, so its reconnect emits no second PEER_ADDED
BGP_EVENT_TYPE_PEER_REMOVEDPeer left the authoritative managed set after session retirement; payload carries no FSM state or role and preserves the neighbor's exact address and interface. For a dynamic neighbor kept for Graceful Restart retention it arrives when the neighbor is deleted, not when its session goes idle
BGP_EVENT_TYPE_PEER_ENABLEDOperator enabled a configured peer
BGP_EVENT_TYPE_PEER_DISABLEDOperator disabled a configured peer
BGP_EVENT_TYPE_NOTIFICATION_SENTrustbgpd sent a BGP NOTIFICATION; payload carries direction, code, subcode, description, session role, and optional RFC 9003 shutdown reason
BGP_EVENT_TYPE_NOTIFICATION_RECEIVEDrustbgpd received a BGP NOTIFICATION from the peer; payload carries the same metadata
BGP_EVENT_TYPE_BFD_SESSION_UPBFD session transitioned to Up
BGP_EVENT_TYPE_BFD_SESSION_DOWNBFD session transitioned to Down
BGP_EVENT_TYPE_BFD_SESSION_STATE_CHANGEDBFD session changed state; payload carries peer, state, diagnostic, and strict flag

NOTIFICATION events are metadata-only. Raw NOTIFICATION packet data remains limited to BMP peer-down handling; WatchEvents does not retain or replay it. NotificationEvent.shutdown_reason (RFC 9003) is peer-supplied free text delivered verbatim over the API — it can legally contain ANSI escape sequences as valid UTF-8, so consumers rendering it to a terminal must sanitize it; rustbgpd's own CLI and log paths already escape it.

Stream health event types:

TypeMeaning
BGP_EVENT_TYPE_STREAM_LAGGEDSource-scoped route, session, per-route dataplane, EVPN, or BFD loss on the live stream.

Policy event types:

TypeMeaning
BGP_EVENT_TYPE_POLICY_CHANGEDRuntime policy, neighbor-set, peer-group, or chain mutation accepted by the peer manager. Payload carries operation, target type, target, optional peer address, and affected peer count. This is a runtime-applied audit signal; config-file persistence is a separate path.

Dataplane event types:

TypeMeaning
BGP_EVENT_TYPE_DATAPLANE_STATUS_CHANGEDFIB / BLACKHOLE installed, rejected, or failed status-row count changed; the legacy three-bucket summary intentionally ignores unresolved FIB rows, which are exposed by ListFibRoutes and bgp_fib_routes_unresolved
BGP_EVENT_TYPE_DATAPLANE_ROUTE_INSTALLEDADR-0061 FIB runtime successfully installed or replaced one route
BGP_EVENT_TYPE_DATAPLANE_ROUTE_WITHDRAWNADR-0061 FIB runtime successfully removed one owned route
BGP_EVENT_TYPE_DATAPLANE_ROUTE_FAILEDADR-0061 FIB runtime failed to apply one route operation; severity is WARNING

InjectionService

Programmatic route injection and withdrawal. Injected routes appear as locally originated (peer address 0.0.0.0) and are advertised to all peers (subject to export policy).

RPCDescription
AddPathInject a route with specified attributes
DeletePathWithdraw a previously injected route
ListPathExportDispositionsPer-peer export disposition of one injected unicast route; see export read-back
BatchListPathExportDispositionsThe same for up to 1000 injected unicast route keys per paged walk; see batch read-back
ListFlowSpecExportDispositionsThe same for one injected FlowSpec rule; see FlowSpec read-back
BatchListFlowSpecExportDispositionsThe same for up to 1000 injected FlowSpec rule keys per paged walk; see FlowSpec batch read-back
AddFlowSpecInject a FlowSpec rule with actions
DeleteFlowSpecWithdraw a previously injected FlowSpec rule
AddLeasedPath / AddLeasedFlowSpecInject a route or FlowSpec rule under an owner's lease; see leased injection
RenewLeaseRenew an owner's lease generation
ListInjectionLeasesList the injection lease table
ListLeasedKeysList the keys one lease owner holds; see reconcile an owner's keys
IssueMutationWindow / AddGuardedFlowSpec / DeleteGuardedFlowSpec / RenewGuardedLeaseWindow- and revision-fenced FlowSpec mutations; see guarded FlowSpec mutations
MarkReplayCompleteSignal that a controller finished replaying after a planned restart; see replay-complete signal
AddEvpnRouteInject an EVPN Type 2 (MAC/IP), Type 3 (IMET), or Type 5 (IP Prefix) route; Type 5 may be interface-less or carry an overlay-index gateway
DeleteEvpnRouteWithdraw a previously injected EVPN route by its EVPN route key

Inject an IPv4 route

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "prefix": "10.99.0.0",
    "prefix_length": 24,
    "next_hop": "10.0.0.1",
    "communities": [4259905793]
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/AddPath

Inject an IPv6 route

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "prefix": "2001:db8:ff::",
    "prefix_length": 48,
    "next_hop": "fd00::1",
    "origin": 0,
    "as_path": [65001],
    "local_pref": 100
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/AddPath

Optional fields: as_path, origin, local_pref, med, communities, extended_communities, large_communities, path_id.

The prefix and next_hop fields accept both IPv4 and IPv6 addresses. Prefix length is validated against the address family (max 32 for IPv4, 128 for IPv6). An IPv4 prefix takes either next-hop family (RFC 8950). An IPv6 prefix requires an IPv6 next hop; an IPv4 next_hop is rejected with INVALID_ARGUMENT. Multicast and broadcast next hops are rejected. path_id defaults to 0 (default path) when omitted.

Next-hop self

An unspecified next_hop (0.0.0.0 or ::, for either prefix family) means next-hop self, the usual default for a remotely triggered blackhole (RTBH) controller that lets the edge's own policy map a community to a discard route. The daemon resolves it per session at export, like set next-hop self in export policy, for eBGP, iBGP and route-server-client sessions alike; an explicit export-policy next-hop action still wins. An export-policy IPv6 next hop cannot apply to an IPv4 route toward a peer without Extended Next Hop; as for any route, the default next hop is used instead, which for this route is self.

PrefixNext hop sent on each session
IPv4The session's local IPv4 address (the router ID on an IPv6-only session without Extended Next Hop), or the session's local address in MP_REACH_NLRI when Extended Next Hop (RFC 8950) is negotiated
IPv6The neighbor's local_ipv6_nexthop, else the session's local IPv6 address

An IPv6 route on a session with neither, for example IPv6 unicast over an IPv4-only session without local_ipv6_nexthop, is not sent to that peer. AddPath still succeeds and the local read-back still shows the route: it was accepted locally, and only the export to that peer is withheld. ListPathExportDispositions reports the peer as withheld with reason family_suppressed:missing_ipv6_next_hop (eBGP) or exact_export_rejected:missing_ipv6_next_hop (iBGP and route-server clients). The daemon never sends an unspecified next hop. How the suppression shows depends on the session:

  • eBGP, other than route-server clients: the whole IPv6 unicast family is withheld when the session establishes. The daemon logs one WARN per session and increments bgp_export_family_suppressed_total{family="ipv6_unicast",reason="missing_ipv6_next_hop"}. rustbgpd --check warns about such neighbors before deployment. The peer still receives an empty IPv6 unicast End-of-RIB with the initial table, so a restarting peer does not wait out its graceful-restart selection deferral for the family.
  • iBGP and route-server clients: the session keeps the family, and the exact-export preflight refuses each next-hop-self route with reason missing_ipv6_next_hop in bgp_exact_export_rejections_total.

For IPv6 RTBH over IPv4 sessions, set local_ipv6_nexthop on the neighbor or its peer group. A reloaded value applies to the per-route refusals on the next route emission. On an eBGP session that withheld the family, the reload restores it without a session reset: the session receives its full IPv6 unicast table and an End-of-RIB.

The route is stored with the unspecified next hop, so ListBestRoutes, ListReceivedRoutes, BMP Loc-RIB and MRT show 0.0.0.0 or ::, and a [[fib_tables]] table rejects it with reason next_hop_unspecified rather than installing a gateway. GoBGP (v3.37.0 and v4.10.0) also treats an unspecified AddPath next hop as the session's local address for eBGP and iBGP peers, but sends it unchanged to route-server clients.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "prefix": "198.51.100.7",
    "prefix_length": 32,
    "next_hop": "0.0.0.0",
    "communities": [4294902426]
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/AddPath

4294902426 is 65535:666, the RFC 7999 BLACKHOLE community.

Withdraw a route

# IPv4
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"prefix": "10.99.0.0", "prefix_length": 24}' \
  localhost:50051 rustbgpd.v1.InjectionService/DeletePath

# IPv6
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"prefix": "2001:db8:ff::", "prefix_length": 48}' \
  localhost:50051 rustbgpd.v1.InjectionService/DeletePath

# Treat an already absent route as success
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"prefix": "10.99.0.0", "prefix_length": 24, "allow_missing": true}' \
  localhost:50051 rustbgpd.v1.InjectionService/DeletePath

Unicast injection contract

A local route is identified by (prefix, prefix_length, path_id). AddPath is an upsert on that key, so a controller can re-announce its whole route set on every reconcile pass:

AddPathResponse.outcomeMeaning
PATH_INJECT_OUTCOME_CREATEDNo local route had this key.
PATH_INJECT_OUTCOME_REPLACEDA local route with this key had a different next hop or attributes; the new route replaced it.
PATH_INJECT_OUTCOME_UNCHANGEDAn identical local route already existed. The stored route, including its RPKI validation state, is kept and nothing is redistributed.
PATH_INJECT_OUTCOME_UNSPECIFIEDThe daemon predates the field.

The outcome compares the new route with the previous local route only, as for FlowSpec: replacing a local route that a received route out-selects still reports REPLACED, although nothing changes on the wire. 0.0.0.0 and :: are the same next-hop-self route.

OK confirms that the route was accepted into the local Adj-RIB-In (peer 0.0.0.0). Selection and outbound distribution for an eligible changed route run in the same RIB turn, before the reply. Existing export policy, next-hop-self and admission checks still apply. OK does not mean that a peer received or installed the route.

After a planned restart, while selection is deferred for a unicast family, only local RTBH candidates participate in ordinary best path, Add-Path, ORR and per-client best selection. A local route qualifies when it is an IPv4 /32, an IPv6 /128, or carries the standard BLACKHOLE community 65535:666 (RFC 7999), regardless of prefix length. This covers AddPath and AddLeasedPath with every path_id. Other injected unicast, including untagged defaults and aggregates, remains retained but ineligible, like received candidates. When selection becomes available, ordinary competition resumes and a received route can replace a local one. Collision failback can stage that selection while completion markers remain held. See the ADR-0141 amendment.

ListPathExportDispositions reports the actual local export outcome; local RTBH injection bypasses selection_deferred; other injected unicast reports that pending reason while its family is held. A row the peer's Adj-RIB-Out already held before the hold stays frozen there and reports COMMITTED until the injection changes. ExplainAdvertisedRoute explains that frozen row in every export mode, with a selection_deferred_frozen step. Once the injection would export differently, or not at all (including through an ORF installed during the hold), explain stops at selection_deferred: the peer keeps the admitted row until release. That is the one deciding stop; its detail names the gate that would apply after release. A grouped route-server client is compared in its own control-scrubbed form. Another eligible local path can still out-select an RTBH route, and policy or admission can withhold or delay export. The family's End-of-RIB remains held until release selection is sent and all existing completion gates allow it. MarkReplayComplete releases only the separate End-of-RIB grace window. It does not release selection deferral; see Controller upgrade and rollback.

DeletePath removes only a route added through AddPath; it never removes a received route. During selection deferral, delete and lease expiry withdraw the local route or select another eligible local RTBH path immediately; removing the last eligible local path never advertises a received fallback before selection becomes available. A key with no local route returns NOT_FOUND by default. Set allow_missing: true to get OK with outcome NOT_PRESENT instead, so a controller's withdraw is idempotent across retries and daemon restarts.

DeletePathResponse.outcomeMeaning
PATH_DELETE_OUTCOME_DELETEDA local route with this key was removed from the local Adj-RIB-In.
PATH_DELETE_OUTCOME_NOT_PRESENTNo local route had this key; returned only with allow_missing.
PATH_DELETE_OUTCOME_UNSPECIFIEDThe daemon predates the field.

A daemon that predates these fields ignores allow_missing: a missing route returns NOT_FOUND, and a present route is deleted with outcome UNSPECIFIED.

rbgp rib add prints the outcome, for example Route 10.99.0.0/24 added (unchanged), and its --json result carries outcome (created, replaced, unchanged, or unknown for an older daemon). rbgp rib delete reports the delete outcome the same way: its --json result carries outcome (deleted, not_present, or unknown for an older daemon). With --allow-missing, a missing route prints Route 10.99.0.0/24 not present and exits 0; without the flag a missing route is still an error. An older daemon's success prints Route 10.99.0.0/24 deleted (the daemon did not report an outcome).

Injected routes are process-local. They are not written to the config and do not survive a daemon restart. A restart can fall between two polls of any signal, so a controller does not rely on detecting it. It reconciles periodically and idempotently: it re-adds its whole desired route set, where routes still present report UNCHANGED and cost no redistribution, and withdraws what it no longer wants with allow_missing: true. It always reconciles after reconnecting to the daemon. A ControlService.GetHealth uptime_seconds lower than on the previous poll is an extra trigger to reconcile at once, not the detector: a poll can see a restarted daemon whose uptime has already passed the previous reading. A leased controller gets a stronger signal: renewing a lease generation from before the restart fails. To list exactly the injected routes, call RibService.ListReceivedRoutes with neighbor_address: "0.0.0.0".

Export read-back

AddPath confirms local acceptance only. To learn which peers the route was exported to, call ListPathExportDispositions with the same (prefix, prefix_length, path_id) key. It returns one row per peer with an Established session, in peer-address order, and each row has exactly one disposition. By default, rows cover Established peers only: a configured peer without a session is absent from the list. Absent does not mean withheld; it means no session exists to export to.

Set include_configured to also list every managed peer without an Established session, with disposition PATH_EXPORT_DISPOSITION_NOT_ESTABLISHED, in the same order. Managed peers are the configured neighbors, plus dynamic neighbors while the daemon tracks them. A link-local neighbor's row carries its peer_interface, as Established rows do. Both lists come from the same read, so no join with NeighborService.ListNeighbors is needed.

dispositionMeaning
PATH_EXPORT_DISPOSITION_COMMITTEDThis exact route sits in the peer's Adj-RIB-Out, committed to its outbound path. advertised_path_id is its outbound Add-Path identifier, 0 on single-best.
PATH_EXPORT_DISPOSITION_WITHHELDThe route is not exported to this peer; reason says why.
PATH_EXPORT_DISPOSITION_PENDINGExport has not settled; reason names what is outstanding.
PATH_EXPORT_DISPOSITION_NOT_ESTABLISHEDThe peer is managed but has no Established session, so nothing is exported to it. Returned only with include_configured.

Committed is local send-side state. BGP carries no acceptance signal, so it does not mean the peer received, accepted or installed the route. A route for the same prefix from another peer, or under another local path_id, never counts as this route's export: when another path is a peer's selected route, this route is WITHHELD with reason not_selected, even though the peer has a route for the prefix.

reasonDispositionMeaning
family_suppressed:<reason>WithheldThe session negotiated the family but withholds it from export, for example family_suppressed:missing_ipv6_next_hop for eBGP IPv6 unicast without an IPv6 next hop. A reload that supplies local_ipv6_nexthop restores it.
family_not_negotiatedWithheldThe session did not negotiate the route's family. This takes precedence over any pending reason.
not_selectedWithheldAnother path is this peer's selected route, or the route ranks beyond the peer's Add-Path send_max.
export_policyWithheldExport policy, or the RFC 8212 default deny, rejects the route; for a per-client-best peer, the policy denies every candidate.
outbound_prefix_limitWithheldThe peer's outbound prefix limit is reached.
exact_export_rejected:<reason>WithheldThe session's encoder refuses the route's exact wire form, for example exact_export_rejected:missing_ipv6_next_hop. A bare exact_export_rejected means a fresh probe no longer reproduces the refusal.
export_ruleWithheldAnother export gate stops the route, such as split horizon, NO_ADVERTISE, LLGR, an ORF filter, OTC or conditional advertisement.
selection_deferredPendingGraceful Restart selection deferral holds injected unicast other than local /32, /128 or BLACKHOLE 65535:666 routes. A row already admitted before the hold, unchanged since, reports COMMITTED.
outbound_resyncPendingOutbound delivery to the peer is resynchronizing.
orf_pendingPendingThe peer negotiated ORF and has not sent its first ROUTE-REFRESH.
not_yet_committedPendingThe route is staged but the Adj-RIB-Out does not hold it yet.
not_establishedNot establishedThe peer has no Established session.

New reason codes may be added. explain_code gives the stop code of the export explain ladder behind a reason, the same vocabulary as ExplainAdvertisedRoute, and detail is human-readable text that may change. A key with no local route returns NOT_FOUND.

deny_validation tells a validation deny, such as route-origin validation dropping an RPKI-Invalid blackhole, from any other policy deny without parsing detail. It is empty unless explain_code is policy_denied. Then it holds one code for each validation state the deciding export-policy statement's match tests, carrying the route's state at evaluation: rpki_valid, rpki_invalid or rpki_not_found, then aspa_valid, aspa_invalid or aspa_unknown.

Deciding statementdeny_validation
TOML statement with match_rpki_validation = "invalid", alone or with other conditions such as a prefix["rpki_invalid"]
rpol term whose guard compares route.rpki and whose reject decides, such as if route.rpki == invalid { reject }["rpki_invalid"] for an Invalid route
Statement testing both RPKI and ASPA["rpki_invalid", "aspa_invalid"], with the route's states
Statement testing no validation state, such as a prefix-list denyempty
Later statement's deny after a statement that tested RPKI permittedempty
RFC 8212 default deny, per-client-best deny of every candidateempty; explain_code is not policy_denied

The code records what the deciding statement tests, not that validation alone decided. Statement conditions AND together, so other conditions also matched. Inside an rpol guard under || or !, the validation comparison need not be the operand that held. An rpol term decided by a loop, a fail-closed evaluation error or a fail-closed bound reports no codes. New codes may be added.

page_size 0 returns up to 100 peers, and larger values are capped at 1000. A non-empty next_page_token continues after the last peer returned. The call is a sensitive_read, served on read-only listeners, and each page costs one single-prefix export explain per peer.

Pages are read live, one call at a time. A resumed page returns ABORTED when any of these changed since the walk's first page:

  • The route's content: next hops, path attributes or validation state. Removing the route counts as a change.
  • The Established peer set: a peer joined or left. A flap, where the peer goes down and comes back, counts even though the set ends up the same.
  • The export policy of an Established peer, such as a reload that replaces it without resetting the session, or the contents of a dataset that policy, or the advertise_policy of a conditional advertisement attached to the peer, reads.
  • Another export setting of an Established peer that changes without a session reset: its outbound prefix limits, a conditional advertisement attached to it (installed, restored, or its applied state changing), its peer group, its Add-Path send limits, a withheld family becoming exportable, its ORF filter or initial ORF gate, or its session's outbound encoding profile, such as a reload that changes local_ipv6_nexthop. Rewriting a setting to the value it already had does not count.
  • With include_configured, the managed peer set: a neighbor was added or removed. A managed peer becoming Established counts as a peer joining the Established set, so its NOT_ESTABLISHED row is never stale or repeated.

Any page, including the first, also returns ABORTED when such a dataset is refreshed, or a session's outbound encoding profile changes, while the page's rows are being evaluated, so no page mixes either.

On ABORTED, discard the rows already collected and restart the walk with an empty page_token. A restarted walk for a removed route returns NOT_FOUND, so NOT_FOUND on a first page always means no local route has the key.

The route check compares content, not identity. Removing the route and restoring identical content between pages cannot be told apart from no change, and the walk stays valid, because every disposition is a function of that content. Changes to other local routes do not abort a walk, unless they change the applied state of a conditional advertisement attached to a listed peer.

Other inputs are read live on each page and are not part of this check: routes from other sources that change which path a peer selects or fill its outbound prefix limit, and outbound delivery progress, such as a peer resynchronizing or a staged route reaching its Adj-RIB-Out. A change to one of them between pages need not abort the walk, and a peer's row reflects them as of the page that listed it.

The next_page_token is opaque. It is bound to the route key, include_configured and the daemon process that issued it. A token for another key or another include_configured, an altered token, or one from before a daemon restart returns INVALID_ARGUMENT; restart the walk with an empty page_token.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"prefix": "2001:db8::7", "prefix_length": 128}' \
  localhost:50051 rustbgpd.v1.InjectionService/ListPathExportDispositions
Batch read-back

BatchListPathExportDispositions reads many keys in one paged walk, such as every key ListLeasedKeys lists for an owner. keys takes the same (prefix, prefix_length, path_id) keys, and include_configured works as above. Each page lists keys in request order. Each key appears as one routes entry that echoes the key as requested, with the key's rows as ListPathExportDispositions lists them.

A key with no local route is listed with found = false and no rows; the call does not fail with NOT_FOUND. found = false means the key had no local route when the page that lists it was read. Each resumed page also checks that every key has a route exactly when it had one on the first page, so a key that gains or loses its route between those reads returns ABORTED. The check compares reads, not the history between them: a route added and removed again between two pages leaves nothing to compare and does not abort the walk.

The cost of a walk is bounded in three ways:

  • Keys per walk. A request names 1 to 1000 keys. This bounds the keys, not the routes or rows one response returns. An empty list, more than 1000 keys, or a key named twice after host bits are masked returns INVALID_ARGUMENT before any work. Split a larger set across walks.
  • Entries per page. page_size 0 returns up to 100 entries, and larger values are capped at 1000. Each peer row is one entry, and so is a key listed with no rows. Peer rows use up the page budget, so a page covers fewer keys as the peer count grows, and one key with more peers than the page size spans several pages. Each row costs at most one single-prefix export explain; NOT_ESTABLISHED rows and keys without a route cost none.
  • Route checks per page. Every page re-reads the route of each named key to check the walk, so this per-page cost grows with the key count, up to 1000 route lookups.

A key whose rows do not fit on a page is listed again at the start of the next page with its remaining rows, so concatenate a key's entries across pages.

A resumed page returns ABORTED on the changes ListPathExportDispositions checks. The route check covers every named key, not only the one being listed: if any key's route content, or whether it has a route, differs from the first page, the whole walk aborts. Changes to local routes outside the key list do not abort it. The next_page_token is bound to the key list in order, include_configured and the daemon process. A token for another key list returns INVALID_ARGUMENT.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"keys": [{"prefix": "2001:db8::7", "prefix_length": 128},
                {"prefix": "203.0.113.9", "prefix_length": 32}],
       "include_configured": true}' \
  localhost:50051 rustbgpd.v1.InjectionService/BatchListPathExportDispositions
FlowSpec read-back

ListFlowSpecExportDispositions reports the per-peer export disposition of one rule added with AddFlowSpec, AddLeasedFlowSpec or AddGuardedFlowSpec, named by the same (afi_safi, rd, components) key. rd is empty for global rules and required for VPN families 13 and 14. This diagnostic RPC is outside v1. Rows, peer order, include_configured, paging, the page-to-page ABORTED check and the token rules are those of ListPathExportDispositions, applied to the rule: its content is its path attributes, and the token is bound to the rule key. A key with no local rule returns NOT_FOUND; a malformed key returns INVALID_ARGUMENT.

The token is bound to the complete scope: it cannot resume a different RD's walk. A peer that negotiated only global FlowSpec (AFI 1 or 2, SAFI 133) still reports WITHHELD / family_not_negotiated for a VPN rule without the corresponding SAFI-134 family.

COMMITTED means the peer's Adj-RIB-Out holds this key from the local rule, with the attributes export would send now. A received rule with the same key never counts: when it is the selected rule, the local rule is WITHHELD with not_selected. advertised_path_id is always 0. Graceful Restart selection deferral does not hold a local rule, so selection_deferred is not reported; a daemon without that exemption reports the hold as pending. The reasons are a subset of the unicast ones:

reasonDispositionFlowSpec meaning
family_not_negotiatedWithheldThe session did not negotiate the rule's FlowSpec family.
not_selectedWithheldA received rule with the same key is selected (no explain_code), or no rule is selected (no_best_route).
export_policyWithheldExport policy, or the RFC 8212 default deny, rejects the rule.
export_ruleWithheldA gate before or after policy stops it; explain_code is no_advertise_suppressed, no_export_suppressed, llgr_stale_suppressed, ibgp_split_horizon or no_advertise_policy_suppressed.
exact_export_rejectedWithheldThe session's encoder refuses the rule.
outbound_resync, not_yet_committedPendingAs for unicast.
not_establishedNot establishedAs for unicast, with include_configured.

Export policy evaluates a FlowSpec rule with RPKI state not_found and ASPA state unknown, so deny_validation reports rpki_not_found or aspa_unknown when the deciding statement tests them. Each row costs one FlowSpec export evaluation, and no policy counters move.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"afi_safi": "ADDRESS_FAMILY_IPV4_FLOWSPEC",
       "components": [{"type": 1, "prefix": "192.0.2.0/24"}],
       "include_configured": true}' \
  localhost:50051 rustbgpd.v1.InjectionService/ListFlowSpecExportDispositions
FlowSpec batch read-back

BatchListFlowSpecExportDispositions is BatchListPathExportDispositions for FlowSpec rules, such as every FlowSpec key ListLeasedKeys lists for an owner. keys takes LeasedFlowSpecKey values, the same (afi_safi, rd, components) keys ListFlowSpecExportDispositions takes, and one walk may mix global and VPN families and RDs. Each response lists rules in request order; each entry echoes the key as requested, with its rows as ListFlowSpecExportDispositions lists them. This diagnostic RPC is outside v1. Daemons that predate it return UNIMPLEMENTED.

The contract is that of the unicast batch, except for malformed keys:

  • A key with no local rule is listed with found = false and no rows; the call does not fail with NOT_FOUND.
  • A malformed key does not fail the call either. A key that ListFlowSpecExportDispositions would refuse with INVALID_ARGUMENT, such as a non-FlowSpec family, a VPN key without an RD, a global key with one, or invalid or out-of-order components, keeps its place as one entry with found = false, no rows and error set: code is invalid_key and message begins with keys[i]:. The unicast batch still fails the call on a malformed key.
  • A request names 1 to 1000 keys. An empty list, more than 1000 keys, or a key named twice returns INVALID_ARGUMENT naming the offending index (keys[i]) before any rule is read. Two parsed keys are the same when they name the same family, RD and components. Malformed keys are never duplicates, even of each other: each is reported at its own index.
  • page_size counts entries: each peer row is one, and so is a key listed with no rows, including a malformed key. A key whose rows do not fit continues at the start of the next page.
  • Every page re-reads the rule of each named key. A resumed page returns ABORTED when any key's rule content (its path attributes), or whether it has a rule, differs from the first page, or on the peer, policy and managed-set changes ListPathExportDispositions checks. A malformed key never has a rule, so it never aborts a walk.
  • The next_page_token is bound to the keys exactly as sent, in order, include_configured and the daemon process. A token from another key list or from another export-disposition RPC returns INVALID_ARGUMENT.

Each page reads all its keys in one RIB turn, so the rows on one page describe one RIB state. Across pages, the ABORTED check above keeps every key's rule and the peer and policy inputs as they were on the first page. Loc-RIB selection, which decides not_selected when a received rule with the same key wins, and outbound delivery progress are read live on each page and are not fenced, so a later page can reflect a change to them.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"keys": [
         {"afi_safi": "ADDRESS_FAMILY_IPV4_FLOWSPEC",
          "components": [{"type": 1, "prefix": "192.0.2.0/24"}]},
         {"afi_safi": "ADDRESS_FAMILY_IPV4_FLOWSPEC",
          "components": [{"type": 2, "prefix": "198.51.100.7/32"},
                         {"type": 3, "value": "=6"}]}],
       "include_configured": true}' \
  localhost:50051 rustbgpd.v1.InjectionService/BatchListFlowSpecExportDispositions

Leased injection

Unowned injected state lives until it is deleted or the daemon stops, so a controller that stops while the daemon runs leaves its routes and rules in place. AddLeasedPath and AddLeasedFlowSpec take the same request as AddPath and AddFlowSpec plus an InjectionLease { owner, lease_seconds }, and return the same outcome plus the owner's LeaseGeneration (ADR-0141). Every entry an owner adds shares that owner's one lease across all families and VPN RDs. Separate deadlines require separate owners. When the lease's deadline passes without a renewal or a further leased add, the daemon withdraws all of the owner's routes and rules in one RIB turn, logs a WARN line with the counts and the lag from the deadline, and counts it in bgp_injection_lease_expiries_total{owner}.

RuleBehaviour
owner1-64 bytes of [A-Za-z0-9._-], else INVALID_ARGUMENT
lease_seconds5-3600, else INVALID_ARGUMENT
Leased add, owner has a live leaseJoins it; the deadline becomes max(current, now + lease_seconds) and never moves earlier
Leased add, no live leaseStarts a new generation; at most 64 live owners, else RESOURCE_EXHAUSTED
Leased add of a key the owner does not holdAt most 16,384 keys per owner, unicast and FlowSpec together, else RESOURCE_EXHAUSTED; keys awaiting expiry still count
RenewLease(owner, generation, lease_seconds)Sets the deadline to exactly now + lease_seconds, which may shorten it; FAILED_PRECONDITION (GENERATION_NOT_LIVE) unless generation is the owner's live lease
Leased add on a key held by another ownerFAILED_PRECONDITION (OWNER_MISMATCH)
Leased add on a key held by no ownerFAILED_PRECONDITION (KEY_UNOWNED); delete the unowned entry first, or add under another path_id
Unowned add on an owned keyFAILED_PRECONDITION (OWNER_MISMATCH)
DeletePath/DeleteFlowSpecowner must match the entry ("" for unowned) unless override_owner is set, else FAILED_PRECONDITION: OWNER_MISMATCH when an owner holds the entry, KEY_UNOWNED when an owner is named but the entry is unowned

Every rejection above leaves the RIB, the lease table and the wire unchanged. Each ownership or generation FAILED_PRECONDITION carries one google.rpc.ErrorInfo detail with domain: "rustbgpd" in the grpc-status-details-bin trailer. Its reason, shown in parentheses above, is the contract for telling the cases apart; the status code stays FAILED_PRECONDITION and the message text is not contract. Clients read it with their gRPC library's rich-error support, for example tonic-types in Rust or status.FromError(err).Details() in Go. A lease is live while now < deadline on the daemon's monotonic clock, so a renewal at exactly the deadline fails. A renewal never creates or resurrects a lease. A controller that gets FAILED_PRECONDITION from RenewLease, or a generation from a leased add other than the one it holds, assumes its state is gone and re-adds its full desired state; the first leased add starts the new generation. Store a LeaseGeneration and compare it as an opaque pair: both incarnation and sequence must match, and neither alone orders or identifies a generation. incarnation is a random fixed64 and sequence a uint64, so proto JSON (for example grpcurl output) renders both as strings, such as {"incarnation": "3238451053446743976", "sequence": "1"}; keep them as strings rather than parsing them into floating-point numbers. Renew well inside the lease, for example every third of it. RenewLease is served from the lease table and never waits behind RIB work.

A leased add whose outcome is unknown, such as a deadline, a lost connection or INTERNAL "RIB manager dropped reply" (which can follow a commit), may be retried as the same leased add. Whether or not the first attempt committed, the entry is owned intent: the retry joins the owner's lease, or starts a new generation if it has expired, and a leased add never becomes permanent injection.

ListInjectionLeases keeps listing an owner past its deadline, with lease_remaining_ms: 0, until the expiry pass scheduled for that deadline takes it and hands its routes to the RIB for withdrawal; the routes may still be present until the RIB applies that batch. Remaining 0 means expired and pending removal: RenewLease refuses that generation with GENERATION_NOT_LIVE, so a controller that adopts such an entry after its own restart re-adds its full desired state instead of renewing.

Expiry removes local intent only. Other eligible routes or rules can keep applying; during selection deferral only local RTBH unicast (/32, /128 or BLACKHOLE 65535:666) and local FlowSpec candidates are eligible. The daemon makes no promise about remote acceptance or enforcement. The lease bounds how long a stopped controller's state outlives it; when the daemon itself stops, peers drop the routes as their sessions close or their Graceful Restart timers run out. SIGHUP does not touch leases. A daemon that predates these RPCs answers UNIMPLEMENTED and creates nothing, so never retry a failed leased add through AddPath or AddFlowSpec.

The lease RPCs, the delete owner and override_owner fields and the read-back below are part of the v1 inventory. A daemon restart invalidates every generation: injected state is process-local, so after a restart the first renewal returns FAILED_PRECONDITION and the controller re-adds. The v1 contract lists the pinned semantics. When peers withdraw an expired entry, and whether a dataplane stops enforcing it, are outside the guarantee.

RibService.ListReceivedRoutes with neighbor_address: "0.0.0.0" and ListFlowSpecRoutes with received_peer_address: "0.0.0.0" report each owned entry's injection_owner, lease_generation and lease_remaining_ms (0 means expired, withdrawal pending); unowned entries leave them unset. The three are set together or not at all, so a row with only some of them is malformed. ListBestRoutes reports them on a best local route too. Advertised rows never carry them, because their path_id is the outbound one. InjectionService.ListInjectionLeases lists the lease table. rbgp rib received 0.0.0.0 and rbgp flowspec received 0.0.0.0 show each owned entry's owner and remaining lease, in text and under lease in --json.

Reconcile an owner's keys

InjectionService.ListLeasedKeys lists exactly the keys one owner holds: each unicast key as the (prefix, prefix_length, path_id) that DeletePath takes, each FlowSpec key as the afi_safi, rd and components that DeleteFlowSpec takes, with the key's LeaseGeneration and lease_remaining_ms (0 means expired, withdrawal pending). Another owner's keys and unowned entries never appear. Keys come in a fixed order, unicast by prefix and path_id and then FlowSpec by AFI, optional RD and components. An absent RD identifies SAFI 133; a present RD identifies SAFI 134. The existing t1 cursor preserves that complete identity, including boundaries between global scope and two RDs with identical components. page_size 0 returns up to 100 keys, larger values are capped at 1000, and a non-empty next_page_token continues after the last key returned, so a key added or removed elsewhere does not shift the pages. An owner holds at most 16,384 keys. It is a sensitive_read, served on read-only listeners.

VPN lease keys report family 13 or 14 and their lossless RD. Echo both into a delete: either VPN family without its RD returns INVALID_ARGUMENT, including when an older client drops the unknown RD field. It cannot address a global sibling. Every scoped key counts toward the same per-owner cap; an RD does not create another lease or quota.

Every page carries generation, the owner's live generation the walk is bound to, so an empty page is never ambiguous:

generationkeysMeaning
absentanyThe owner has no live lease. Re-add the whole desired state; any keys listed are expired and awaiting withdrawal.
presentsomeThe owner's keys. Each row carries its own generation: a row whose generation differs from the page's belongs to an expired generation and awaits withdrawal (lease_remaining_ms 0). Renewing the live generation does not keep it; re-add it if it is still wanted.
presentnoneA live lease that holds no keys.

A walk is bound to the daemon process and to the owner's generation at its first page. If the daemon restarts, or the owner's lease expires or a new generation starts, before a later page, that page returns ABORTED with no keys and a google.rpc.ErrorInfo whose reason is WALK_INVALIDATED (domain rustbgpd): start the walk again with an empty page_token. A walk that began with no live lease also aborts if any lease generation started since, even one that expired again before the next page. A token from a previous daemon process is never accepted, and a token is valid only for the owner it was issued for: another owner's token returns INVALID_ARGUMENT. Adding or deleting keys does not change the generation, so it does not abort a walk. Errors are always gRPC statuses, never an empty OK page.

A controller that restarts while the daemon keeps running finds its previous process's keys under its owner, still renewed by nobody:

  1. List its owner's keys page by page, restarting the walk on ABORTED.
  2. Re-add each key it still wants with a leased add; this joins the owner's live lease, or starts a new generation if the old one expired.
  3. Delete each listed key it no longer wants with DeletePath or DeleteFlowSpec, passing its owner.
  4. Renew with the generation the leased adds returned.

The listing reads the daemon's state at the time of each page; a key can expire between the listing and the delete, so delete with allow_missing: true. After a daemon restart the owner holds no keys: injected state is process-local, and the keys the controller adds again carry the new process's incarnation. The FlowSpec components come back in the daemon's canonical spelling, for example ==80 for a request's =80, which DeleteFlowSpec accepts unchanged.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"owner": "rtbh-pop1"}' \
  localhost:50051 rustbgpd.v1.InjectionService/ListLeasedKeys

To remove an owned entry by hand, for example a blackhole still announced for a controller that is wedged or gone, delete it as its owner or override the owner:

rbgp rib delete 198.51.100.7/32 --override-owner
rbgp flowspec delete -a ipv4_flowspec --match "dest=203.0.113.7/32" --owner rtbh-pop1

Without either flag, a delete of an owned entry fails with exit status 1, names the owner and points at both flags. Deleting an entry does not stop a live controller from adding it again; stop the controller, or let its lease lapse, first. The leased adds and RenewLease are operator_only; a successful RenewLease is audited at INFO rather than WARN. A delete's audit summary names the owner and generation the removed entry held, so an override_owner delete names the owner it bypassed; a different requested owner is logged as requested_owner. The owner is a label that keeps controllers from changing each other's state by mistake, not a security boundary between operators.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "path": {"prefix": "198.51.100.7", "prefix_length": 32,
             "next_hop": "0.0.0.0", "communities": [4294902426]},
    "lease": {"owner": "rtbh-pop1", "lease_seconds": 30}
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/AddLeasedPath

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"owner": "rtbh-pop1", "generation": {"incarnation": "<from the add>",
       "sequence": "<from the add>"}, "lease_seconds": 30}' \
  localhost:50051 rustbgpd.v1.InjectionService/RenewLease

Connecting a controller

Injection RPCs are operator_only in the method inventory, so the controller's principal needs the operator role. The daemon rejects a TCP listener without authentication at config load, so a client that only knows plaintext gRPC uses one of these transports:

  • Owner-only Unix socket. Run the controller as the daemon's user and connect to unix:///var/lib/rustbgpd/grpc.sock with insecure channel credentials. Such a socket authorizes its clients as the implicit local-operator principal; no token or roles entry is needed. Set the channel's default authority to a host name such as localhost: gRPC otherwise sends the socket path as the HTTP/2 :authority, which the daemon resets.
  • Loopback TCP with a bearer token. Configure [global.telemetry.grpc_tcp] on 127.0.0.1 with token_file and a principal mapped to operator in [security.grpc.roles], and send authorization: Bearer <token> as metadata on every call. Add it to each call directly: gRPC attaches call credentials such as an access token only to a channel it considers secure, and whether local loopback credentials qualify depends on the gRPC version.

In C++ these are, for example:

// Owner-only Unix socket.
grpc::ChannelArguments args;
args.SetString(GRPC_ARG_DEFAULT_AUTHORITY, "localhost");
auto uds = grpc::CreateCustomChannel("unix:///var/lib/rustbgpd/grpc.sock",
                                     grpc::InsecureChannelCredentials(), args);

// Loopback TCP with a bearer token, added to every call.
auto tcp = grpc::CreateChannel("127.0.0.1:50051",
                               grpc::InsecureChannelCredentials());
grpc::ClientContext context;
context.AddMetadata("authorization", "Bearer " + token);

Do not expose the listener beyond loopback to reach a remote controller; see security for the remote mTLS posture.

Guarded FlowSpec mutations

A leased mutation can commit long after the controller sent it: it can wait before its handler runs, for RIB queue admission and behind RIB work, and a client timeout cancels none of these. The guarded methods (ADR-0144) fence a FlowSpec rule against that. They are part of the v1 contract, which pins their API shape only.

RPCBehaviour
IssueMutationWindow(owner, window_seconds)Issues a window living window_seconds (1..=120). An owner holds at most 64 live windows and the daemon 4,096; past either cap the call is RESOURCE_EXHAUSTED
AddGuardedFlowSpec(rule, lease, window, revision)A leased FlowSpec add, checked against the window when it commits. The owner's deadline becomes max(current, min(now + lease_seconds, window expiry)): the add caps any extension at its window but keeps a later deadline set earlier, which the new rule then shares. revision is a nonzero client-chosen value stored with the rule
DeleteGuardedFlowSpec(rule key, owner, revision)Removes the rule only at its revision: DELETED, or NOT_PRESENT for an absent rule. Needs no window
RenewGuardedLease(owner, generation, lease_seconds, window)Sets the deadline to exactly min(now + lease_seconds, window expiry), which may shorten it

A guarded rule is an AddFlowSpecRequest and accepts the same component grammar, actions, communities and VPN scope as AddFlowSpec. A rule needs no destination component: for example, a source host with protocol, source ports and TCP flags, a typed redirect_ip and a standard community. Export policy evaluates such a rule without a prefix, so a prefix term does not match it; match its communities instead.

A window's expiry is therefore not the rule's withdrawal deadline. The owner's lease never outlives the latest-expiring window it used, and no window lives more than 120 s after it was issued. Read the lease deadline back (ListInjectionLeases, or lease_remaining_ms on the rule) rather than inferring it from a window.

Owners are named without a prefix in requests. The daemon keeps a guarded owner's rules and lease in a separate namespace and reports it as guarded:<owner>: in FlowSpecRouteEntry.injection_owner, in ListInjectionLeases, and as the owner ListLeasedKeys takes. The leased and unleased methods cannot add, renew or delete a guarded owner's state; DeleteFlowSpec with override_owner remains the operator's break-glass. Read-back reports each guarded rule's revision in FlowSpecRouteEntry.admission_revision and LeasedKey.admission_revision.

RefusalStatus
Malformed owner, window_seconds outside 1..=120, revision 0, missing window, rule, lease or generation, lease_seconds outside 5..=3600INVALID_ARGUMENT
Window expired, unknown, another owner's or another process'sFAILED_PRECONDITION, WINDOW_NOT_LIVE
Present rule at another revision, or at the same revision with another payload; delete of another revisionFAILED_PRECONDITION, REVISION_MISMATCH
Rule held by another owner, guarded or not, or by no ownerFAILED_PRECONDITION, OWNER_MISMATCH or KEY_UNOWNED
Renewal of a generation that is not liveFAILED_PRECONDITION, GENERATION_NOT_LIVE
Window cap reachedRESOURCE_EXHAUSTED

These refusals, and UNIMPLEMENTED or PERMISSION_DENIED, are definitive: the request changed nothing. Any other outcome, such as DEADLINE_EXCEEDED, UNAVAILABLE or a dropped connection, is unknown, because the add may have committed while its window was live. Resolve it by reading the rule's revision back, or by retrying with the same revision under a live window, which is UNCHANGED for an identical payload. To change a guarded rule, delete it at its revision and add it with a new one; never reuse a revision for a different admission of the same key. A daemon without these methods answers UNIMPLEMENTED, or PERMISSION_DENIED to a credential without the operator role, and changes nothing; never retry a guarded mutation through the leased or unleased methods.

All four methods are operator_only. A successful IssueMutationWindow or RenewGuardedLease is audited at INFO rather than WARN.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"owner": "scrubber", "window_seconds": 60}' \
  localhost:50051 rustbgpd.v1.InjectionService/IssueMutationWindow

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "rule": {"afi_safi": "ADDRESS_FAMILY_IPV4_FLOWSPEC",
             "components": [{"type": 1, "prefix": "203.0.113.7/32"}],
             "actions": [{"traffic_rate": {"rate": 0}}]},
    "lease": {"owner": "scrubber", "lease_seconds": 30},
    "window": {"incarnation": "<from the window>", "sequence": "<from the window>"},
    "revision": "1"
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/AddGuardedFlowSpec

Replay-complete signal

After a planned restart, the End-of-RIB grace window holds End-of-RIB toward configured Graceful Restart helpers. A controller listed in [global] gr_eor_replay_owners releases it early, once its replay is done:

  1. Read the daemon incarnation I from ControlService.CheckLiveness (or LeaseGeneration.incarnation from a leased add) before replaying.
  2. Re-add the full desired state.
  3. Call MarkReplayComplete(owner, I).

The signal is sent through the RIB queue after the controller's earlier injections, and each add commits before its RPC returns, so every route added before the call reaches the helpers ahead of the released End-of-RIB. Release needs every listed controller (AND); the window's deadline still releases End-of-RIB if one stays silent. Windows belong to the configured neighbors from daemon start, so the release also covers a neighbor whose session is not up yet: when it establishes, its initial table ends in End-of-RIB once the other convergence gates allow it.

This signal releases only the replay grace window. It does not release selection deferral or other convergence and refresh holds. Local RTBH unicast (/32, /128 or BLACKHOLE 65535:666) and FlowSpec injection are eligible during selection deferral without this signal; other injected unicast waits for selection to become available. Ordinary policy and admission checks still apply.

ResultMeaning
OK RELEASEDThis owner was the last one awaited; the replay grace hold was released. Other convergence gates still apply.
OK RECORDEDRecorded; awaiting lists the listed owners that have not signalled
OK NOT_EXPECTEDThe owner is not in gr_eor_replay_owners; nothing changed (logged at WARN)
OK NOT_HOLDINGNo End-of-RIB is held: a cold boot, no window configured, or the window already ended. Nothing is released; the signal is still recorded for this incarnation
FAILED_PRECONDITION, ErrorInfo reason INCARNATION_MISMATCHI is not the current incarnation: the daemon restarted. Nothing changed; read I again and replay again

A repeated signal for the same owner changes nothing. The RPC is operator_only and outside the v1 stable surface. Like the lease owner, the owner name is a label, not an authenticated identity: any operator credential can signal for any owner. The signal proves only that the controller replayed its own desired state.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"owner": "gobgp-bridge", "incarnation": "<from CheckLiveness>"}' \
  localhost:50051 rustbgpd.v1.InjectionService/MarkReplayComplete

Inject a FlowSpec rule

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "afi_safi": "ADDRESS_FAMILY_IPV4_FLOWSPEC",
    "components": [
      { "type": 1, "prefix": "203.0.113.0/24" },
      { "type": 4, "value": "=80" }
    ],
    "actions": [
      { "traffic_rate": { "rate": 0.0 } }
    ]
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/AddFlowSpec

Withdraw a FlowSpec rule

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "afi_safi": "ADDRESS_FAMILY_IPV4_FLOWSPEC",
    "components": [
      { "type": 1, "prefix": "203.0.113.0/24" },
      { "type": 4, "value": "=80" }
    ]
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/DeleteFlowSpec

FlowSpec component lists must be non-empty, in strictly ascending type-code order with no type repeated, and limited to the supported RFC 8955 / RFC 8956 unicast component set. The daemon does not reorder components; an out-of-order or repeated type is rejected with INVALID_ARGUMENT. Each injected or withdrawn rule must also encode to at most 4095 NLRI payload bytes; larger rules are rejected with INVALID_ARGUMENT. Prefix lengths must be at most 32 for IPv4 or 128 for IPv6; oversized lengths are rejected rather than clamped. IPv4 prefix offsets must be zero. For IPv6, use length and offset both zero for an all-address match; otherwise offset < length <= 128. The API canonicalizes skipped leading bits to zero before forming the rule key. These checks apply to global and VPN adds, deletes and export-disposition queries.

FlowSpec injection contract

A local rule is identified by (afi_safi, rd, components), with an empty RD for global SAFI 133. AddFlowSpec is an upsert on that key, so a controller can re-announce its whole rule set on every reconcile pass:

AddFlowSpecResponse.outcomeMeaning
FLOW_SPEC_INJECT_OUTCOME_CREATEDNo local rule had this key.
FLOW_SPEC_INJECT_OUTCOME_REPLACEDA local rule with this key had different actions or communities; the new payload replaced it.
FLOW_SPEC_INJECT_OUTCOME_UNCHANGEDAn identical local rule already existed. Nothing is redistributed.
FLOW_SPEC_INJECT_OUTCOME_UNSPECIFIEDThe daemon predates the field.

The outcome compares the new rule with the previous local rule only. A received rule with the same key does not affect it, even when that received rule is the selected one: replacing an out-selected local rule still reports REPLACED, although nothing changes on the wire.

OK confirms that the rule was accepted into the local Adj-RIB-In (peer 0.0.0.0). Selection and outbound distribution run in the same RIB turn, before the reply. OK does not mean that a peer received or installed the rule, and a received rule with the same key can out-select it. Injected rules are process-local: after a daemon restart, the controller must inject them again.

Graceful Restart selection deferral after a planned restart does not hold a local rule, leased or not (ADR-0141 amendment). While deferral holds the FlowSpec family, only local rules are selection candidates: a re-injected rule is selected and sent to Established peers at once, and a peer whose session comes up later gets it in its initial table. Rules received from peers wait for the deferral to release. So does the family's End-of-RIB, so a Graceful Restart helper keeps the stale rules from the previous session until then. When deferral releases, the ordinary FlowSpec best-path order chooses between a local rule and a received rule with the same key; a received rule that wins replaces the local one on the wire, and the local rule then reads selected: false and not_selected.

DeleteFlowSpec removes only a rule added through AddFlowSpec; it never removes a received rule. A key with no local rule returns NOT_FOUND by default. Set allow_missing: true to get OK with outcome NOT_PRESENT instead, so a reconciling controller can treat "already gone" as drift rather than a failure. The same selection and distribution timing as AddFlowSpec applies to a successful delete.

DeleteFlowSpecResponse.outcomeMeaning
FLOW_SPEC_DELETE_OUTCOME_DELETEDA local rule with this key was removed from the local Adj-RIB-In.
FLOW_SPEC_DELETE_OUTCOME_NOT_PRESENTNo local rule had this key; returned only with allow_missing.
FLOW_SPEC_DELETE_OUTCOME_UNSPECIFIEDThe daemon predates the field.

A daemon that predates these fields ignores allow_missing: a missing rule returns NOT_FOUND, and a present rule is deleted with outcome UNSPECIFIED. Because such a daemon returns OK only after removing a rule, UNSPECIFIED on success means the rule was deleted; it never means the rule was absent.

To list the injected global rules, call RibService.ListFlowSpecRoutes with received_peer_address: "0.0.0.0". Set family 13 or 14 explicitly to list injected IPv4 or IPv6 VPN rules. The received view returns every local rule in the requested family scope, including one a received rule currently out-selects (selected: false), with route.peer_address set to 0.0.0.0. Selection deferral never holds a local rule, so selected: false on a local rule means a received rule with the same key is selected. A rule in a peer's received view can also read selected: false because deferral still holds its family after a planned restart; NeighborState.selection_deferral shows an active row for the family while it does. Validation reads disabled by default and local when [flowspec] validation is enabled; local rules never report feasible or infeasible.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"received_peer_address": "0.0.0.0"}' \
  localhost:50051 rustbgpd.v1.RibService/ListFlowSpecRoutes

rbgp flowspec add prints the outcome, for example FlowSpec rule added (unchanged), and its --json result carries outcome (created, replaced, unchanged, or unknown for an older daemon). rbgp flowspec delete reports the delete outcome the same way: its --json result carries outcome (deleted, not_present, or unknown for an older daemon). With --allow-missing, a missing rule prints FlowSpec rule not present and exits 0; without the flag a missing rule is still an error. An older daemon's success prints FlowSpec rule deleted (the daemon did not report an outcome). rbgp flowspec received 0.0.0.0 shows injected global rules; add -a l3vpn_ipv4_flowspec or -a l3vpn_ipv6_flowspec for VPN rules.

The global IPv4/IPv6 modes of AddFlowSpec, DeleteFlowSpec, and the selected, local-intent and advertised listings belong to the scoped v1 controller contract. Remote received-candidate mode, Config.flowspec, and the shared ReceivedFlowSpecRouteEntry.path_id, .validation, .reason, .pending fields and FlowSpecValidationStatus enum remain alpha. The gRPC promotion does not promote FlowSpec CLI commands or their output. The same pre-v1 compatibility rules apply during 0.x; once v1.0 is tagged, removal of the inventoried surfaces is no earlier than 2.0. Follow the controller upgrade guidance for older servers, view acknowledgements and desired-state replay. The bounded dual-stack controller qualification exercises 100 local rules against FRR 10.7.1, including retained intent, committed export policy, peer replay, and restart reconciliation. It does not qualify receive-side feasibility validation, GR/LLGR retention, or dataplane enforcement.

The dated receipt preserves the as-run driver hash and observations. Its 30-second convergence and 90-second session polling windows checked elapsed time only after failed observations; a successful observation could finish after the window. It therefore establishes functional convergence, not a strict latency bound. The current driver also rejects success at or after the deadline, covered by an offline clock-controlled regression. These are acceptance deadlines; in-flight observation commands retain their own timeouts. The current FRR oracle also rejects additional match components in both table paths and detailed rows. An offline recheck of all 26 retained snapshots passed with those checks, covering 980 paths and their matching detailed rows without changing the original receipt or driver identity.

VPN FlowSpec controller API

Families ADDRESS_FAMILY_L3VPN_IPV4_FLOWSPEC (13) and ADDRESS_FAMILY_L3VPN_IPV6_FLOWSPEC (14) originate IPv4 and IPv6 VPN FlowSpec with explicit RD identity and Route Target attributes. The existing plain, leased and guarded add/delete RPCs, ListFlowSpecRoutes, ListLeasedKeys ListFlowSpecExportDispositions and BatchListFlowSpecExportDispositions retain that scope. These additions are outside v1; the global controller contract above is unchanged. ADR-0146 records the original IPv4-only design. The IPv6 extension keeps that origination contract, using RFC 8955 §8 for VPN scope and RFC 8956 §§2–3 for AFI 2 / SAFI 134 and IPv6 components. This API does not create a local VRF or provide receive/reflection, router installation or traffic enforcement guarantees.

The pinned GoBGP qualification covers RD/RT preservation, replacement, withdrawal, family isolation and 239/240-byte NLRI framing. Nonzero IPv6 prefix offsets do not interoperate with GoBGP 4.11.0: its codec uses the full prefix length instead of the RFC 8956 pattern length. Offset-zero IPv6 and IPv4 checks passed; router installation and forwarding remain unqualified.

MessageScope fields
AddFlowSpecRequest, including leased/guarded wrappersrd (7), route_targets (8)
DeleteFlowSpecRequestrd (6)
DeleteGuardedFlowSpecRequestrd (5)
LeasedFlowSpecKeyrd (3)
ListFlowSpecExportDispositionsRequestrd (6)
FlowSpecRouteEntryrd (13), route_targets (14)

Both VPN families require an RD of type 0, 1 or 2. Structured input accepts asn16:u32, a.b.c.d:u16 and asn32:u16; 0x plus 16 hexadecimal digits preserves an exact supported encoding. A small-ASN type-2 RD reads back in raw hex so re-injection retains its type. Global families reject a nonempty RD or typed route_targets. Components use their selected AFI's grammar, including source-prefix matches. Family 13 rejects IPv6 prefixes, nonzero prefix offsets and the IPv6 Flow Label component (type 13). Family 14 accepts IPv6 prefixes, valid prefix offsets and Flow Label, with the IPv6 upper-layer protocol and fragment semantics of RFC 8956; it rejects IPv4 prefixes. In families 4 and 14, a fragment (type 12) value may set only IsF (0x02), FF (0x04) and LF (0x08); DF (0x01) is IPv4-only, and it or any reserved bit is rejected. The rule plus its eight-octet RD must fit in 4,095 bytes, leaving at most 4,087 bytes for components. Invalid scope or payload is rejected with INVALID_ARGUMENT before mutation.

A VPN add requires at least one scope RT, typed in route_targets or raw in extended_communities. Supported scope RTs have exact types 0x00, 0x01 or 0x02 and subtype 0x02. Non-transitive raw forms (0x40–0x42) remain passthrough values and do not satisfy this requirement. A redirect action is not a scope RT. Typed RTs accept the same administrator grammar as FlowSpecRedirect.route_target: AS2, IPv4, AS4 and RFC 5396 asdot+. A small-ASN AS4 RT reads back as 0.ASN:value to preserve its encoding. Both families use the existing FlowSpec actions; API acceptance does not establish a receiver's support for an action or combination.

Rows return scope RTs both typed and raw. Re-inject each RT in one representation: retain route_targets and remove their raw twins, or leave route_targets empty and retain the raw values. With distinct scope RTs, an otherwise identical payload is UNCHANGED in either representation. Raw RT duplicates remain accepted and appear in both read-back lists; replay such rows using the raw list with route_targets empty. Repeated typed RTs, including aliases for the same encoded value, and typed/raw duplicates return INVALID_ARGUMENT. Removing duplicates changes the payload: a plain or same-owner leased retry can be REPLACED, while a guarded retry under the same revision returns REVISION_MISMATCH. Keep the existing typed-or-raw action rule too. Global raw-community behavior remains unchanged.

Identical components in global scope, RD A and RD B are separate keys, as are rules in different AFIs. An RT-only plain or same-owner leased update replaces one key's attributes. It sends a replacement to eligible peers and withdraws from peers whose export policy now rejects the rule. A guarded RT change under the held revision returns REVISION_MISMATCH: delete that revision, then add the new payload under a new revision. Changing the RD creates a new key; retire the old identity explicitly. One owner's lease and 16,384-key cap span all of its RDs and families; admission revisions remain scoped to each key.

The CLI uses the same identity and scope attributes:

rbgp flowspec add -a l3vpn_ipv4_flowspec --rd 64500:40 --route-target 64500:777 \
  --match "dest=192.0.2.0/24 port==80" --action drop
rbgp flowspec add -a l3vpn_ipv6_flowspec --rd 64500:40 --route-target 64500:777 \
  --match "dest=2001:db8::/48 port==80" --action drop
rbgp flowspec received 0.0.0.0 -a l3vpn_ipv6_flowspec
rbgp flowspec delete -a l3vpn_ipv6_flowspec --rd 64500:40 \
  --match "dest=2001:db8::/48 port==80"

Repeat --route-target for multiple RTs. Each peer must explicitly enable the corresponding VPN family; see the controller configuration.

The release floor is 0.82.0: it is the first published release containing this API. HealthResponse.daemon_version alone does not establish support. Pin a build containing this contract and require the read-only local-intent probe for each required family, which needs no peer:

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"afi_safi": 13, "received_peer_address": "0.0.0.0"}' \
  localhost:50051 rustbgpd.v1.RibService/ListFlowSpecRoutes

Use afi_safi: 14 for the IPv6 probe. A supporting daemon acknowledges received_view: true, even when the result is empty. A daemon that does not recognize the requested family returns INVALID_ARGUMENT. A transport or authentication failure is not that capability result. Never retry a refused VPN request as global FlowSpec, or send an RD with a global family: an older daemon can ignore the unknown RD field and operate on the global key. A family requiring an RD is refused without one on the new API, protecting old clients that echo lease keys.

Inject an EVPN Type 2 (MAC/IP) route

AddEvpnRoute and DeleteEvpnRoute accept the required rd in the shared RD input grammar. The raw form, 0x/0X plus 16 hex digits, preserves all eight bytes, including RD types 3 and above. The RD type is independent of the EVPN route_type, which accepts 2, 3, and 5.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "route_type": 2,
    "rd": "65000:100",
    "ethernet_tag": 0,
    "mac": "02:00:00:aa:bb:cc",
    "ip": "10.0.0.5",
    "label": 100,
    "next_hop": "10.0.0.2",
    "route_targets": ["65000:100"]
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/AddEvpnRoute

disable_vxlan_encap defaults to false — the RFC 8365 §5.1.2 VXLAN Encapsulation extended community (tunnel-type=8) is attached automatically. Set disable_vxlan_encap: true for MPLS-over-GRE deployments. The injection API supports route_type 2 (MAC/IP), 3 (IMET), and 5 (IP Prefix). Type 5 injection can use the default interface-less gateway-zero shape or an explicit overlay-index Gateway Address. Native Gate 9 Type 5 origination from [[evpn_ip_vrfs]] shipped in v0.18.0 (slice 6 PR A #77): the daemon dumps kernel routes per IP-VRF table_id, classifies them (connected/static/manual only — routes installed by other routing daemons or whose output device is the L3 VXLAN are filtered), and originates a Type 5 per surviving prefix when the IP-VRF's readiness probe says Ready. Remote Type 5 import + L3 FIB programming (kernel route + neighbor + L3VXLAN FDB) shipped in v0.18.0 (slice 6 PR B #78) through the transactional L3OwnedState model with four-phase apply ordering, Router MAC conflict detection, and foreign-state preservation; RTNLGRP_IPV4_ROUTE / RTNLGRP_IPV6_ROUTE multicast (#79) drives sub-second withdraw on tenant ip addr del. Native Type 1/4 multi-homing origination is driven by [[ethernet_segments]]; the injection API does not expose those route types yet (the RR still reflects them when received from peers).

Inject an EVPN Type 3 (IMET) route

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "route_type": 3,
    "rd": "65000:100",
    "ethernet_tag": 0,
    "ip": "10.0.0.2",
    "next_hop": "10.0.0.2"
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/AddEvpnRoute

Inject an EVPN Type 5 (IP Prefix) route

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "route_type": 5,
    "rd": "65000:5000",
    "ethernet_tag": 0,
    "prefix": "10.50.0.0",
    "prefix_length": 24,
    "label": 5000,
    "next_hop": "192.0.2.10",
    "router_mac": "02:00:00:00:50:00",
    "route_targets": ["65000:5000"]
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/AddEvpnRoute

By default, Type 5 injection is interface-less: ESI and Gateway IP are encoded as zero, label carries the L3VNI in the RFC 8365 VXLAN label slot, ethernet_tag must be 0, and next_hop is the VTEP loopback. Set optional gateway to inject a controller-supplied overlay-index Type 5 route with a non-zero unicast Gateway Address; the prefix, gateway, and next-hop must use the same IP family. Non-zero ESI overlay-index injection is not exposed. router_mac is required when VXLAN encapsulation is enabled (the default) and is advertised as the RFC 9135 Router MAC extended community. Omit it when disable_vxlan_encap is true. At least one route_targets entry is required for Type 5 injection.

Withdraw an EVPN route

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "route_type": 2,
    "rd": "65000:100",
    "ethernet_tag": 0,
    "mac": "02:00:00:aa:bb:cc",
    "ip": "10.0.0.5"
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/DeleteEvpnRoute

The withdrawal key (route type + RD + ethernet tag + MAC + optional IP for Type 2; route type + RD + ethernet tag + originator IP for Type 3; route type + RD + ethernet_tag=0 + prefix/prefix length for Type 5) matches the EVPN route identity used by rustbgpd. Type 5 gateway is payload, not part of the local route key. Omit ip when withdrawing a MAC-only Type 2 route or the key will not match. Requests that include key fields from another route type are rejected with INVALID_ARGUMENT. Returns NOT_FOUND if no such route was previously injected.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{
    "route_type": 5,
    "rd": "65000:5000",
    "ethernet_tag": 0,
    "prefix": "10.50.0.0",
    "prefix_length": 24
  }' \
  localhost:50051 rustbgpd.v1.InjectionService/DeleteEvpnRoute

ControlService

Daemon lifecycle, health checks, and metrics.

RPCDescription
CheckLivenessEmpty authenticated request; Read tier. A response means only the gRPC handler answered, without actor readiness or topology. Its one field, incarnation, is drawn at random at daemon start (the lease incarnation) and changes on every start. Outside the narrow v1 contract; older servers return UNIMPLEMENTED, or an incarnation of zero.
GetHealthReturns health status, uptime, active peers, total routes; core actor probes are bounded by the same 200 ms deadline as HTTP /readyz
GetMetricsReturns Prometheus metrics as text; returns DEADLINE_EXCEEDED when the wait for the shared one-at-a-time render exceeds 5 s; the render itself is not cancelled
ShutdownInitiates graceful shutdown
TriggerMrtDumpTriggers an on-demand MRT TABLE_DUMP_V2 dump

Health check

GetHealth.healthy=true means the core peer-manager and RIB snapshot was obtained. It does not assert that every BGP session or the dataplane is healthy. Failure to obtain the snapshot returns an RPC error, rather than a successful healthy=false response. When the peer manager or the RIB misses the 200 ms core-probe deadline, the error is UNAVAILABLE. The miss may be transient, an actor busy for example in the short tail of a configuration reload, or persistent, a wedged actor; a caller may retry once and should treat a repeated miss as a failure. A closed actor channel, a dropped reply, or a stalled export-policy transition or selection release returns INTERNAL. GetHealth follows the same daemon gate as HTTP /readyz: once coordinated shutdown begins, or a runtime-config settlement arms its recovery fence, it returns UNAVAILABLE without querying the actors, with a google.rpc.ErrorInfo detail (domain: "rustbgpd") whose reason is DAEMON_SHUTTING_DOWN or RUNTIME_CONFIG_RECOVERY_FENCE. That state lasts until the process exits, so a retry does not help. CheckLiveness never consults the gate. active_peers counts configured peers whose session reports Established. Each session publishes its state on every FSM transition and clears it when it ends, and the peer manager counts from that published state without querying any session, so a session busy writing a large export burst is still counted. ListNeighbors queries each session and marks a session that does not answer in time stale.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.ControlService/GetHealth

For a handler-liveness probe that needs only the Read tier, call CheckLiveness or run rbgp health --liveness, which prints alive. It does not check actor readiness. The response's incarnation identifies one daemon process lifetime, so a client that probes periodically sees a restart even when no probe failed.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.ControlService/CheckLiveness
rbgp health --liveness

If [global.telemetry] prometheus_addr is configured, the same HTTP listener also exposes unauthenticated probe endpoints:

curl -fsS http://127.0.0.1:9179/livez
curl -fsS http://127.0.0.1:9179/readyz

/livez only proves the process is accepting HTTP connections. /readyz returns 200 ready when PeerManager and RIB respond within 200 ms total, or 503 not ready: <reason> when either core actor is unavailable, drops its reply, or times out. During an actor-owned export-policy transition the dedicated read-only RIB lane stays healthy for bounded progress, then returns 503 not ready: RIB export-policy transition stalled if ownership reaches 30 seconds; commit or cleaned-up fallback restores readiness immediately. A selection-deferral release shares that bound and returns 503 not ready: RIB selection-deferral release stalled once it runs for 30 seconds; readiness returns when the release finishes. It does not require peers or routes to exist.

Authoritative export-policy replacement and rollback service this same RIB readiness lane between construction, per-peer work, and cleanup steps. These operations preserve Loc-RIB cardinality, so readiness replies report its exact count while ordinary route queries and mutations remain queued. Nested replacements retain the original command's 30-second transition-age limit.

Get Prometheus metrics via gRPC

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.ControlService/GetMetrics

Graceful shutdown

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"reason": "maintenance window"}' \
  localhost:50051 rustbgpd.v1.ControlService/Shutdown

Trigger MRT dump

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.ControlService/TriggerMrtDump

EvpnService

Local EVPN state and bounded controls for this VTEP. Empty read responses are normal when the daemon is acting purely as an EVPN route reflector — RR mode does not declare local instances. The same [[evpn_instances]] table that this service exposes is the input to the Linux kernel reconciler (Gate 7b, ADR-0054 — programs remote-MAC FDB entries downward), the local-MAC originator + Type 3 IMET emitter (Gate 7b+1, ADR-0055 — emits Type 2 / Type 3 routes upward from kernel-learned state), the Gate 8 segment/DF orchestrator, and the Gate 9 Type 5 / IP-VRF path. The originators and dataplane actors bypass this gRPC surface; they translate kernel/RIB events directly into reconcile inputs and RibUpdate::InjectEvpn / WithdrawEvpn against the RIB. See ADR-0052 for the original boundary, ADR-0054/ADR-0055 for the dataplane + origination boundaries, and ADR-0063 for the runtime mutation semantics used by both ApplyEvpnRuntime and SIGHUP reload.

RPCDescription
GetEvpnRuntimeReturn the committed EVPN runtime generation, lifecycle, mutation state, configured EVI/IP-VRF/ES counts, and a concise status message
ListEvpnInstancesList configured local EVPN instances sorted by VNI (vni, rd, resolved route_targets including any auto-derived RT, local_vtep_ip, optional bridge, optional local bridge_vlan, advertise_svi_mac flag, originated_local_macs_count, L2 dataplane readiness_state, not_ready_reason when NotReady, remote_route_drop_counts, current_apply_failure_count, and bounded latest_permanent_apply_error); response-level unscoped_apply_failure_count and latest_unscoped_permanent_apply_error cover host-wide L2 operations even with no EVI
ListEvpnNexthopsList Linux dataplane reconciler-owned ADR-0059 FDB nexthop groups (per-VNI groups with ESI / Ethernet Tag / kernel group ID, per-VTEP member nexthop IDs + gateways, MAC refs) plus top-level L2 and L3 orphan-NH and pending-delete counts and the drift_recovery_disabled latch — read-only operator visibility
ListEthernetSegmentsList configured Ethernet Segments sorted by ESI, joined with live multi-homing state: composed drain reasons, advertised DF preference/Don't-Preempt beside the administrative values (they differ while RFC 9785 recovery inherits another PE's preference), any pending recovery wait with its remaining milliseconds, per-member DF role and BUM forwarding action, same-ESI local-bias eligibility, whole-port AC-gate state/interface, and matching FDB-NHG group / MAC-ref counts — read-only ADR-0083/0085 diagnose visibility
ListIpVrfsList configured IP-VRFs / L3VNI tenants (name, l3vni, rd, resolved route_targets including any auto-derived RT, local_vtep_ip, router_mac, optional evpn_instance link, readiness state, originated_routes_count, installed_routes_count, remote_prefix_drop_counts) — Gate 9 / ADR-0058
ListManagedNetdevsList configured ADR-0091 managed EVPN bridge, fixed-VNI VXLAN, SVD / collect-metadata VXLAN, VLAN upper, VRF, and L3VXLAN rows joined with the latest Linux link snapshot, plus rustbgpd-stamped orphan/unsafe rows for the configured owner. Reports class, name, desired flag, ownership stamp, state (desired-absent, owned-safe, foreign-present, owned-unsafe, orphaned, or unknown), observed ifindex, bridge vlan_filtering, VXLAN/SVD/L3VXLAN vni / local / dstport / learning / collect-metadata / vnifilter / master attributes, VLAN upper vlan, VRF table_id, L3VXLAN router_mac, observed rustbgpd ownership stamps, and reason text. Bridge, fixed-VNI VXLAN, SVD VXLAN, VLAN upper, VRF, and L3VXLAN lifecycle execution is active in the dataplane actor; this RPC remains read-only status.
GetIpVrfDetail view of a single IP-VRF including the seven readiness predicates (not_ready_reasons) when readiness_state != Ready and scoped remote Type 5 projection-drop counts
ListDuplicateMacQuarantinesList at most 4096 active duplicate-MAC local-origin quarantine keys from one actor-published snapshot, ordered by VNI and raw MAC. omitted is exact and complete is true exactly when no rows were omitted.
ClearDuplicateMacQuarantineClear one RFC 7432 §15.1 duplicate-MAC local-origin quarantine by (vni, mac). Returns cleared=false when no active quarantine exists; read-only listeners reject it.
ApplyEvpnRuntimeValidate or apply a full candidate EVPN runtime model through the ADR-0063 coordinator. validate_only=true returns the plan without mutation; no-op applies succeed. Supported live changes include single L2VNI/IP-VRF/Ethernet-Segment add/delete/redefine, additive build-up, atomic tenant teardown, ip_vrf relink, and decomposable mixed edits ordered as deletes -> redefines -> ip_vrf relinks -> adds. L2VNI add/delete republishes the current instance table to the segment actor so later ES add/redefine can bind a VNI added at runtime, including the first segment on a daemon started without one; ES-member L2VNI redefine rebuilds the segment actor's Type 1/4 routes from the candidate instance snapshot. L3VNI/device/table IP-VRF identity changes remain restart-required by design. Unsupported dependency cycles fail closed before commit; mid-sequence convergence failures stop after already committed generations; unrestored failures pin the coordinator and increment evpn_runtime_decomposed_fail_stops_total.

No per-instance create or delete RPC exists; instance changes go through ApplyEvpnRuntime as a full candidate. GetEvpnRuntime now reports the daemon-owned ADR-0063 coordinator generation. At startup this is generation 1, lifecycle active, and mutation state idle when the coordinator is available. ApplyEvpnRuntime accepts a full candidate rustbgpd TOML document so the daemon can reuse the normal config parser, validator, and EVPN table resolution. Because that TOML may contain unrelated credentials, audit logs record only its byte length and mode. Runtime mutation is not a shared-table swap: it drives the live IMET controller, the MAC-only/MAC+IP/SVI Type 2 originators, the Type 5/IP-VRF originator, and the Linux dataplane supervisor through ordered convergence commands with rollback on partial failure.

Supported non-noop shapes converge live and commit the next generation: single L2VNI/IP-VRF/Ethernet-Segment add/delete/redefine, additive build-up, atomic tenant teardown, ip_vrf relink, and decomposable mixed edits. The mixed-edit decomposer applies primitive commits in a fixed order — deletes, redefines, ip_vrf relinks, then adds — so operators may observe multiple runtime generations for one SIGHUP or ApplyEvpnRuntime request. ES add/redefine can reference a member VNI added by an earlier live L2VNI add when the segment actor is already running; ES-member L2VNI redefine rebuilds Type 4 / EAD-per-ES / EAD-per-EVI routes from the candidate instance snapshot while retaining the stable ESI label. L3VNI/device/table IP-VRF identity changes remain restart-required by design. Unsupported dependency cycles fail closed before commit. If a later primitive step or actor command fails after earlier steps committed, the sequence fail-stops there: the committed generations stay visible and an ERROR log names the step. If the failing step leaves unrestored or unacknowledged effects, the coordinator pins mutation_state=Failed and evpn_runtime_decomposed_fail_stops_total increments. A fully compensated step leaves the prior committed model authoritative; it does not undo earlier primitive commits. SIGHUP still fences that partial sequence for recovery.

ApplyEvpnRuntime failure status

A failed ApplyEvpnRuntime status states what the failure left behind:

StatusMeaning
FAILED_PRECONDITIONNo new divergence from the failing primitive step. Either the candidate was refused before any side effect, or every effect from the failing primitive converge was rolled back to its previously committed model. Earlier primitive commits in a decomposed apply remain committed. A rolled-back failure is not a no-effect refusal: earlier publishes, such as an acknowledged Type 3 IMET originate and its compensating withdraw, can be observed before the rollback, and a retry can repeat those transient changes.
INTERNALKnown divergence. A rollback step did not restore the committed model, or the failing step may have taken effect without an acknowledgement (for example, a Type 3 inject whose RIB acknowledgement timed out or whose reply was dropped). The message says the state was not restored; live EVPN state may need repair or a restart.
UNAVAILABLEDaemon shutdown cut the apply off after it published to the EVPN actors. Those publishes are not rolled back, because the same shutdown drains the actors next. Below operator_only, UNAVAILABLE also reports that the config directory changed while the candidate's policy sources were read; nothing was applied, and a retry can succeed.

The failing step does not advance the committed generation; earlier primitive commits in a decomposed apply remain committed and are named in the error. A refusal before convergence or a fully compensated failure preserves the coordinator's prior state. Unrestored or unacknowledged effects pin mutation_state=Failed until a later apply succeeds. A rollback counts as restored only when every actor the step published to holds the committed snapshot again and every Type 3 IMET route it changed has been put back with a RIB acknowledgement.

Operators configure instances via the [[evpn_instances]] TOML block. SIGHUP reload submits EVPN table edits through the same coordinator for supported ADR-0063 shapes. Unsupported dependency cycles, L3VNI/device/table IP-VRF identity changes, or missing EVPN actors fail closed before commit. Actor convergence failures inside a decomposed sequence fail-stop on the last committed generation and keep the drift visible instead of silently advancing the config snapshot.

Get EVPN runtime status

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.EvpnService/GetEvpnRuntime

Or via CLI:

rbgp evpn runtime           # human format
rbgp evpn runtime --json    # JSON output

List local EVPN instances

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.EvpnService/ListEvpnInstances

Or via CLI:

rbgp evpn instances           # human format
rbgp evpn instances --json    # JSON output
rbgp evpn diagnose            # instance / Type 2 / Type 3 / metric summary

The human CLI includes readiness=ready|not-ready|unbound|unknown, originated-local-macs=N, and bridge-vlan=N when the instance has a local bridge VLAN binding; not-ready rows include the single L2 readiness probe reason. JSON exposes the same fields as readiness, originated_local_macs_count, not_ready_reason, and bridge_vlan (null when absent); gRPC exposes the enum as readiness_state and the local VLAN binding as optional bridge_vlan. Unbound means no bridge is configured for that L2VNI. Unknown means the instance is bridge-bound but no dataplane verdict is on file yet, usually cold start before the first reconcile report or an RR-only / dataplane-disabled deployment. originated_local_macs_count counts MAC-only Type 2 routes currently originated by this daemon for the instance and accepted by the RIB. bridge_vlan is local Linux attribution only, never the EVPN Ethernet Tag. When present, it selects ADR-0089's traditional VNI-per-broadcast-domain VLAN-aware path: the probe requires vlan_filtering=1, exactly one VXLAN member for the instance VNI, and the configured VLAN on both the bridge and that VXLAN member; remote-MAC FDB rows are then programmed with NDA_VLAN. A vlan_filtering=1 bridge without bridge_vlan remains NotReady.

service_interface is vlan_based or vlan_aware_bundle, as configured, and ethernet_tag is the Ethernet Tag the instance originates and imports L2 routes under: 0 for vlan_based, the member tag for a VLAN-aware bundle member. The human CLI adds service=vlan-aware-bundle ethernet-tag=N for bundle members only; JSON always carries both fields and reports vlan_based for a daemon that predates them.

remote_route_drop_counts lists, by reason, the remote Type 1 EAD-per-EVI, Type 2 and Type 3 IMET routes that select the instance but that the VTEP does not program: ethernet_tag_mismatch, vni_mismatch or multihoming_unsupported, as described for evpn_l2_remote_route_drops. It reports the same current values as the evpn_l2_remote_route_drops{vni,reason} gauge, sorted by reason; a reason with no drops is omitted. The routes stay in Adj-RIB-In and are still reflected. The human CLI adds remote-route-drops=[ethernet_tag_mismatch=2] when the list is non-empty, and JSON exposes it as remote_route_drop_counts ([] when empty).

current_apply_failure_count counts still-current Linux L2 operations that failed for this VNI, including those suppressed after a permanent error or deferred by transient backoff. latest_permanent_apply_error is a bounded diagnostic for the latest still-current permanent failure; it is empty when none remains. These fields do not change bridge readiness. Host-wide BUM port, AC gate, and managed-netdev operations have no VNI attribution; the response-level unscoped count and bounded latest permanent error expose them even when there are no configured EVIs. rbgp evpn instances --json retains its array of EVI rows; use rbgp evpn diagnose --json for the host-wide overview. The same current state is exported as evpn_current_apply_failures metrics.

List EVPN FDB nexthop groups

ADR-0059 operator-visibility surface. Returns the Linux dataplane reconciler's owned FDB nexthop-group state: one row per group with VNI, ESI, Ethernet Tag, kernel group ID, per-VTEP member nexthop IDs, and MAC refs. The response also includes orphan tagged nexthop count, pending-delete count, and whether periodic drift recovery latched off after a permanent dump failure. orphan_nexthops_count and pending_delete_count cover L2 FDB-NHG nexthops; l3_orphan_nexthops_count and l3_pending_delete_count report the same state for L3 (all-active Type 5) FDB nexthops, which share the retry queue.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.EvpnService/ListEvpnNexthops

Or via CLI:

rbgp evpn nexthops          # human format
rbgp evpn nexthops --json   # JSON output

An empty groups list is normal on RR-only deployments, single-homed VTEPs, or multi-homed VNIs with apply_aliasing_ecmp = false — the top-level count fields and drift_recovery_disabled are always populated regardless.

List Ethernet Segments / multi-homing state

ADR-0083 / ADR-0085 diagnose surface. Returns one row per configured [[ethernet_segments]] entry, optionally filtered by ESI. Each row joins the committed ES config with the latest segment/dataplane snapshots: drain reasons (operator / link), DF role and BUM action per member VNI, same-ESI local-bias eligibility, the single-active whole-port AC-gate state/interface, and matching owned FDB-NHG group / MAC-ref counts. Empty runtime fields mean the segment actor or dataplane has not published that snapshot yet; the RPC itself is read-only.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"esi":"00:11:22:33:44:55:66:77:88:99"}' \
  localhost:50051 rustbgpd.v1.EvpnService/ListEthernetSegments

Or via CLI:

rbgp evpn es list
rbgp evpn es list 00:11:22:33:44:55:66:77:88:99 --json

List IP-VRFs / L3VNI tenants

Gate 9 / ADR-0058 surface. Returns one row per [[evpn_ip_vrfs]] entry with the readiness verdict the EVPN reconcile actor most recently published, plus the Type 5 origination / install counters and current scoped remote Type 5 projection-drop counts. The drop counts reuse the bounded reason labels from evpn_ip_vrf_remote_prefix_drops{vrf,reason} and omit per-route prefixes, gateways, next-hops, MACs, RDs, and RTs.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.EvpnService/ListIpVrfs

Or via CLI:

rbgp evpn vrfs                  # human format
rbgp evpn vrfs --json           # JSON output
rbgp evpn vrfs vrf1             # single-VRF detail (matches GetIpVrf)

List managed EVPN netdevs

ADR-0091 managed-netdev lifecycle/status surface. Returns configured [managed_netdevs] bridge, fixed-VNI VXLAN, SVD / collect-metadata VXLAN, VLAN upper, VRF, and L3VXLAN rows joined with the latest Linux link snapshot, plus rustbgpd-stamped orphan links observed by the dataplane actor. This is read-only status: a row can be desired-absent, foreign-present, owned-unsafe, owned-safe, orphaned, or unknown. Bridge, fixed-VNI VXLAN, SVD VXLAN, VLAN upper, VRF, and L3VXLAN rows are active lifecycle intent inside the dataplane reconciler. The RPC itself never mutates links.

Bridge rows expose observed vlan_filtering. Fixed-VNI and SVD VXLAN rows expose observed vni, local, dstport, learning-disabled, collect-metadata, vnifilter, and bridge-master fields when the Linux link snapshot reports them. VRF rows expose observed table_id and up. L3VXLAN rows expose observed vni, local, dstport, learning-disabled, collect-metadata, vnifilter, vrf master, up, and router_mac. VLAN upper rows expose observed parent bridge, VLAN id, and link-up state.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.EvpnService/ListManagedNetdevs

Or via CLI:

rbgp evpn managed-netdevs
rbgp evpn managed-netdevs --json

Get IP-VRF detail

Returns the same row as ListIpVrfs plus, when readiness_state is not Ready, the not_ready_reasons list — one entry per failing ADR-0058 §3 predicate, such as vrf table_id mismatch (observed 0, configured 100) or l3vxlan device down. These are human-readable lines, not machine tokens; structured consumers should use readiness_state and the row's field values. remote_prefix_drop_counts reports the current bounded receive-side Type 5 projection drops for this IP-VRF.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"name": "vrf1"}' \
  localhost:50051 rustbgpd.v1.EvpnService/GetIpVrf

Clear duplicate-MAC quarantine

Clears local-origin suppression for one (VNI, MAC) after an operator has confirmed the loop condition is gone. The RPC does not clear every quarantine and does not remove Loc-RIB/RR visibility; if the MAC is still locally present, the originator immediately replays the live MAC-only or MAC+IP state through the normal recovery path.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"vni": 100, "mac": "aa:bb:cc:dd:ee:ff"}' \
  localhost:50051 rustbgpd.v1.EvpnService/ClearDuplicateMacQuarantine

Or via CLI:

rbgp evpn clear-duplicate-mac --vni 100 --mac aa:bb:cc:dd:ee:ff
rbgp evpn clear-duplicate-mac --vni 100 --mac aa:bb:cc:dd:ee:ff --json
rbgp evpn duplicate-mac-quarantines
rbgp evpn duplicate-mac-quarantines --json

Drain or undrain an Ethernet Segment

SetEthernetSegmentDrain is the ADR-0084 maintenance control for one configured Ethernet Segment. It is an operator-tier mutation; a read-only listener returns PERMISSION_DENIED.

Request fields:

  • esi — the Ethernet Segment Identifier as 10 colon-separated hex octets, for example 00:11:22:33:44:55:66:77:88:99. A malformed ESI returns INVALID_ARGUMENT; an ESI with no configured [[ethernet_segments]] entry returns NOT_FOUND.
  • drained — true adds the operator drain reason, false removes it.

Draining withdraws the segment's Type 4 (ES), EAD-per-ES and EAD-per-EVI routes, so this PE leaves DF election, and withdraws the local Type 2 MAC/MAC+IP routes of its member VNIs while suppressing new local-MAC origination. Undraining re-originates the ES and EAD routes, re-runs DF election and replays the cached local MAC/MAC+IP state.

Drain reasons compose (ADR-0085). This RPC adds or removes only the operator reason; it never clears a link reason held by the segment's bound interface. An operator undrain while the bound link is down therefore leaves the segment drained, and origination resumes when the attachment circuit recovers. An operator drain on a segment that is already link-drained records the reason without withdrawing anything new.

Response fields:

  • drained — the composed state after the request: true while any drain reason is held.
  • changed — false when the operator reason already matched the request. Repeating a request is an idempotent no-op.
  • member_vni_count — the number of member VNIs whose local Type 2 origination the drain governs.
  • message — a human-readable summary of the route classes withdrawn or re-originated and of any remaining drain reasons.
  • reasons — the drain reasons held after the request, as lowercase strings (operator, link); empty when the segment is not drained.

Drain state is in memory only. A daemon restart clears it and replays the configured state, so re-apply a drain after a restart that happens during maintenance. UNAVAILABLE means the daemon's Ethernet Segment drain control is not running.

An esi = "auto-lacp" segment leaves the runtime while its bond has no usable LACP partner, for example after carrier loss. Its operator reason stays on the last derived ESI meanwhile, so a segment that returns under the same partner is still drained. While the segment is absent the RPC returns NOT_FOUND for that ESI. A different partner is a new segment and starts undrained. Removing the segment from the config drops the drain.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"esi": "00:11:22:33:44:55:66:77:88:99", "drained": true}' \
  localhost:50051 rustbgpd.v1.EvpnService/SetEthernetSegmentDrain

Or via CLI:

rbgp evpn es drain 00:11:22:33:44:55:66:77:88:99
rbgp evpn es undrain 00:11:22:33:44:55:66:77:88:99 --json
rbgp evpn es list 00:11:22:33:44:55:66:77:88:99   # drain reasons and DF role

See ADR-0084 and ADR-0085.

Apply EVPN runtime candidate

Validates a full candidate rustbgpd TOML document against the committed EVPN runtime model and returns a plan summary. Use validate_only=true to inspect added/deleted/redefined/unchanged EVPN instances, IP-VRFs, and Ethernet Segments — plus the ip_vrf_references_changed flag, which is the only non-empty plan signal for a pure ip_vrf relink — without changing the committed generation. A dry-run rejects exactly what a commit of the identical candidate would reject, including the actor-availability preconditions: an L2VNI add validated on an RR-only daemon (which spawns no EVPN dataplane actors) fails with the same FAILED_PRECONDITION the commit would return.

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d @ localhost:50051 rustbgpd.v1.EvpnService/ApplyEvpnRuntime <<'JSON'
{
  "candidate_toml": "[global]\nasn = 65000\nrouter_id = \"10.0.0.1\"\nlisten_port = 179\n\n[global.telemetry]\nlog_format = \"json\"\n\n[security.grpc]\nenforcement = \"tier\"\n\n[[evpn_instances]]\nvni = 100\nrd = \"65000:100\"\nroute_targets = [\"65000:100\"]\nlocal_vtep_ip = \"10.0.0.1\"\n",
  "validate_only": true
}
JSON

A non-validate_only request commits when the candidate is a no-op, a single L2VNI add, a single L2VNI delete that is not an Ethernet Segment member, a single L2VNI redefine with unchanged ip_vrf link metadata, a single IP-VRF add, a single standalone IP-VRF delete with no L2VNI links, a single IP-VRF redefine with unchanged L3VNI/device/table identity, a single Ethernet Segment add/delete/redefine, additive build-up, an atomic tenant teardown, or an ip_vrf relink against the committed model; the response carries the committed generation and outcome. L3VNI/device/table IP-VRF identity changes remain restart-required by design. Unsupported dependency cycles, an ES referencing an unknown member VNI, or an ES apply with no running segment actor are rejected with FAILED_PRECONDITION before commit; decomposable mixed edits may commit multiple generations and fail-stop on a later primitive convergence failure as described above.


BfdService

Read-only inspection of single-hop and multihop BFD sessions (ADR-0067, RFC 5880/5881/5883). Sessions themselves are configured via [[bfd_profiles]] + [neighbors.bfd] (see configuration.md). Member attachments apply on SIGHUP; profile definitions require a restart. There is no mutating BFD RPC, and config transactions do not apply BFD attachment changes.

RPCDescription
GetBfdSessionsList BFD sessions (peer address, state, last diagnostic, strict flag, remote-AdminDown cause, multihop mode flag), optionally filtered to one peer_address; a filter that matches no session and names no known peer returns NOT_FOUND (unknown peers)
# All BFD sessions
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  localhost:50051 rustbgpd.v1.BfdService/GetBfdSessions

# One peer
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"peer_address": "10.0.0.2"}' \
  localhost:50051 rustbgpd.v1.BfdService/GetBfdSessions

state is a BfdSessionState (BFD_SESSION_STATE_{ADMIN_DOWN,DOWN,INIT,UP}). remote_administrative_down is an explicit-presence boolean: true explains that the peer disabled BFD and RFC 5882 section 4.1 permits BGP even though the local BFD state remains DOWN; false means a current daemon observed no such cause. An absent field means the serving daemon predates this visibility and the cause is unknown—clients must not default absence to false. Live state-change events are available on EventService.WatchEvents with EVENT_CATEGORY_BFD (opt-in). RFC 5882 BGP coupling — strict (withhold BGP until BFD Up) and non-strict (tear BGP down on BFD-down before the hold timer) — is driven by PeerManager from these sessions; it is not exposed as a separate RPC.


RpkiService

ValidateRouteOrigin is a sensitive_read, outside-v1 diagnostic over the latest authoritative VrpTable. It accepts a bare IP address, an explicitly present prefix length, and a nonzero origin ASN. Host bits are normalized in the response. CIDR text in prefix, omitted or out-of-family prefix lengths, malformed addresses, and AS0 queries return INVALID_ARGUMENT.

rbgp rpki validate 192.0.2.129/24 64496

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{"prefix":"192.0.2.129","prefix_length":24,"origin_asn":64496}' \
  localhost:50051 rustbgpd.v1.RpkiService/ValidateRouteOrigin

The valid, invalid, or not_found verdict is computed from the complete table before diagnostic truncation. covering_vrps contains at most 256 effective duplicate-collapsed rows, authorizers first, followed by deterministic non-authorizers. complete and exact omitted describe that listing. AS0 VRPs remain visible but always have authorizes: false. Before the first authoritative snapshot the RPC returns FAILED_PRECONDITION; a received empty snapshot is authoritative and returns not_found with a complete empty list. This surface does not expose cache provenance, readiness, raw RTR data, or cache management.

ListCaches exposes configured RTR endpoints in canonical address order, current transport connectivity, and the latest atomically accepted End of Data epoch. accepted is present for an accepted empty table and absent before the first accepted epoch or after expiry/fatal flush. Protocol version, session ID, and serial are optional for compatibility with legacy embedded update producers. Counts are derived from the retained per-cache contribution, and age_seconds is monotonic whole seconds. Results are capped at 256 rows with exact complete/omitted; an unconfigured daemon returns a complete empty list. A closed actor returns UNAVAILABLE, while the two-second whole-query budget returns DEADLINE_EXCEEDED.

rbgp rpki caches

grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
  -d '{}' localhost:50051 rustbgpd.v1.RpkiService/ListCaches

ASPA provider and path diagnostics

LookupAspa and VerifyAsPath are sensitive_read methods outside the narrow v1 contract. Each call clones the current authoritative validation snapshot once, releases the watch borrow, and uses that immutable ASPA table throughout. No snapshot epoch, per-cache provenance, or freshness claim is attached: those metadata are not present in the merged table.

rbgp rpki aspa 64497
rbgp --json rpki verify-path --role peer --neighbor-asn 64496 "64496 64497"

LookupAspa takes a nonzero customer_asn. It returns found plus at most 256 sorted, deduplicated provider_asns from the effective merged table; complete and exact omitted describe truncation. A missing customer has found: false; a present empty provider set has found: true. AS0 providers remain visible. An authoritative empty table yields a complete missing result.

VerifyAsPath takes segments of kind SEQUENCE or SET, an explicit nonzero neighbor_asn, and local_role. The role describes the receiving speaker: CUSTOMER selects downstream verification; PROVIDER, PEER, ROUTE_SERVER, RS_CLIENT, and explicit NONE select upstream verification. Only RS_CLIENT exempts the first-AS neighbor comparison. UNSPECIFIED and unknown roles or segment kinds are invalid arguments. There is no caller-controlled exemption.

The request is limited to 4096 nonzero ASNs across at most 4096 nonempty segments. An empty segment list represents an empty path. Empty paths, any AS_SET, and nonexempt first-AS mismatches produce INVALID without an invalid_hop. The validation result otherwise comes directly from the shared ASPA verifier; invalid_hop, when present, is its first proven NotProviderPlus customer/provider pair. Consecutive prepends retain the verifier's existing compression semantics. The verdict uses the complete table, independently of the provider-lookup display limit.

This is hypothetical eBGP IPv4/IPv6-unicast verification of an effective four-octet AS_PATH, after AS4 reconstruction. It does not evaluate a complete UPDATE, peer admission, other address families, or import policy. Live ingress may treat an AS_SET or first-AS mismatch as a withdrawal before reaching ASPA. An absent authoritative ASPA table returns FAILED_PRECONDITION from both methods; an authoritative empty table still runs the verifier, so structural invalidity is not hidden as UNKNOWN. Malformed or oversized requests return INVALID_ARGUMENT before table lookup. Successful diagnostic verdicts, including invalid, produce CLI exit 0; malformed CLI input exits 64 before connecting, and operational RPC failures exit 1.

The CLI accepts whitespace-separated decimal ASNs and {ASN ASN} sets in a quoted literal, with a 65536-byte text limit. Both calls use its complete 30-second unary response deadline. Add --json for machine-readable results.


Proto File

The full proto definition is at proto/rustbgpd.proto. You can generate typed clients for Python, Go, Rust, Node.js, or any language with protobuf/gRPC support.

Source on GitHub

On this page

Pinning the proto to a releaseService overviewAuthentication and TLSListener Access MatrixError TaxonomyOperator-read deadlinesScoped neighbor identitygnmi.gNMIGlobalServiceConfigServiceNeighborServiceRemote ASN mode and the session ASNAdministrative stateInterface-only neighborsAdd a neighborList all neighborsGet a single neighbor's stateDisable a neighborEnable a neighborReset a neighbor's sessionDelete a neighborTrigger SoftResetInRefresh one peer's outbound routesReplay one peer's unicast routes with terminal EoRsPolicyServiceExplain an import decisionList a peer's rejected routesCreate or replace a named policyAttach a global import chainAttach a per-neighbor export chainCreate a named neighbor setDelete a named policyPeerGroupServiceCreate or replace a peer groupAssign a neighbor to a peer groupRibServiceUnknown peers in peer-scoped viewsPrefix-SID inspection on VPN and EVPN routesRuntime observability surfacesList received routes (Adj-RIB-In)List best routes (Loc-RIB)List advertised routes (Adj-RIB-Out)Explain one advertised route decisionLongest-prefix lookup in the global Loc-RIBAddress family filteringPaginationWatch route changes (streaming)List recent route eventsList FlowSpec routesBounded VPN, labeled, RTC, BGP-LS and EVPN best pagesRoute Distinguisher identityList EVPN routesExplain an exact EVPN routeInspect an explicit SRv6 Argument pairList BGP-LS routesList ORR topology nodes and linksList BLACKHOLE discard statusList general FIB route statusEventServiceWatch unified eventsInjectionServiceInject an IPv4 routeInject an IPv6 routeNext-hop selfWithdraw a routeUnicast injection contractExport read-backBatch read-backFlowSpec read-backFlowSpec batch read-backLeased injectionReconcile an owner's keysConnecting a controllerGuarded FlowSpec mutationsReplay-complete signalInject a FlowSpec ruleWithdraw a FlowSpec ruleFlowSpec injection contractVPN FlowSpec controller APIInject an EVPN Type 2 (MAC/IP) routeInject an EVPN Type 3 (IMET) routeInject an EVPN Type 5 (IP Prefix) routeWithdraw an EVPN routeControlServiceHealth checkGet Prometheus metrics via gRPCGraceful shutdownTrigger MRT dumpEvpnServiceApplyEvpnRuntime failure statusGet EVPN runtime statusList local EVPN instancesList EVPN FDB nexthop groupsList Ethernet Segments / multi-homing stateList IP-VRFs / L3VNI tenantsList managed EVPN netdevsGet IP-VRF detailClear duplicate-MAC quarantineDrain or undrain an Ethernet SegmentApply EVPN runtime candidateBfdServiceRpkiServiceASPA provider and path diagnosticsProto File