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/GetGlobalThe 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.protoEach 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
| Service | RPCs | Purpose |
|---|---|---|
GlobalService | GetGlobal | Daemon identity |
ConfigService | DiffRuntimeConfig, PlanConfigTransaction, StreamPlanConfigTransaction, StreamApplyConfigTransaction, ApplyConfigTransaction, ConfirmConfigTransaction, AbortConfigTransaction, GetConfigTransactionStatus, GetLastSighupReload, GetEffectiveConfig, ListConfigHistory, PreviewConfigRollback, RollbackConfigTransaction | Candidate-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 |
NeighborService | AddNeighbor, DeleteNeighbor, ListNeighbors, GetNeighborState, EnableNeighbor, DisableNeighbor, SoftResetIn, RefreshOutbound, ReplayOutbound, ResetNeighbor, SetGracefulShutdown, AddDynamicNeighbor, DeleteDynamicNeighbor, ListDynamicNeighbors | Peer 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 |
PolicyService | ListPolicies, GetPolicy, SetPolicy, DeletePolicy, ListNeighborSets, GetNeighborSet, SetNeighborSet, DeleteNeighborSet, GetGlobalPolicyChains, GetNeighborPolicyChains, SetGlobalImportChain, SetGlobalExportChain, ClearGlobalImportChain, ClearGlobalExportChain, SetNeighborImportChain, SetNeighborExportChain, ClearNeighborImportChain, ClearNeighborExportChain, ExplainImportPolicy, ListRejectedRoutes, TestPolicy, ComparePolicy, GetPolicyStats, GetValidationPolicyPosture, ListConditionalAdvertisements | Named 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 |
PeerGroupService | ListPeerGroups, GetPeerGroup, SetPeerGroup, DeletePeerGroup, SetNeighborPeerGroup, ClearNeighborPeerGroup | Peer-group CRUD and neighbor membership assignment |
RibService | ListReceivedRoutes, 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, ListRouteEvents | Query-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 |
BfdService | GetBfdSessions | BFD session inspection (single-hop and multihop) for configured static neighbors, interface-only bindings and dynamic-range sessions |
RpkiService | ValidateRouteOrigin, ListCaches, LookupAspa, VerifyAsPath | Bounded 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 |
EventService | WatchEvents, ListEvpnEvents, ListSessionEvents, ListPolicyEvents | Unified 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 |
InjectionService | AddPath, DeletePath, ListPathExportDispositions, BatchListPathExportDispositions, ListFlowSpecExportDispositions, BatchListFlowSpecExportDispositions, AddFlowSpec, DeleteFlowSpec, AddLeasedPath, AddLeasedFlowSpec, RenewLease, ListInjectionLeases, ListLeasedKeys, IssueMutationWindow, AddGuardedFlowSpec, DeleteGuardedFlowSpec, RenewGuardedLease, MarkReplayComplete, AddEvpnRoute, DeleteEvpnRoute | Programmatic route, FlowSpec, and EVPN injection, with optional owner leases, guarded FlowSpec mutations and a controller replay-complete signal |
ControlService | CheckLiveness, GetHealth, GetMetrics, Shutdown, TriggerMrtDump | Health, metrics, lifecycle, MRT dumps |
EvpnService | GetEvpnRuntime, ListEvpnInstances, ListEvpnNexthops, ListEthernetSegments, ListIpVrfs, ListManagedNetdevs, GetIpVrf, ListDuplicateMacQuarantines, ClearDuplicateMacQuarantine, SetEthernetSegmentDrain, ApplyEvpnRuntime | Local 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.gNMI | Capabilities, Get, Set, Subscribe | OpenConfig 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:
| Pattern | Config | Auth |
|---|---|---|
| Unix domain socket | [global.telemetry.grpc_uds] with path + mode | File-system permissions on the socket path |
| Plaintext TCP + bearer token | [global.telemetry.grpc_tcp] with address and optional token_file | Bearer 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_file | Client 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 \
capabilitiesA 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.
| Service | Read-only RPCs | Mutating RPCs rejected on read_only |
|---|---|---|
GlobalService | GetGlobal | — |
ConfigService | DiffRuntimeConfig, PlanConfigTransaction, StreamPlanConfigTransaction, GetConfigTransactionStatus, GetLastSighupReload, GetEffectiveConfig, ListConfigHistory, PreviewConfigRollback | StreamApplyConfigTransaction, 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 |
NeighborService | ListNeighbors, GetNeighborState, ListDynamicNeighbors | AddNeighbor, DeleteNeighbor, EnableNeighbor, DisableNeighbor, SoftResetIn, RefreshOutbound, ReplayOutbound, ResetNeighbor, AddDynamicNeighbor, DeleteDynamicNeighbor, SetGracefulShutdown |
PolicyService | ListPolicies, GetPolicy, ListNeighborSets, GetNeighborSet, GetGlobalPolicyChains, GetNeighborPolicyChains, ExplainImportPolicy, ListRejectedRoutes, TestPolicy, ComparePolicy, GetPolicyStats, GetValidationPolicyPosture, ListConditionalAdvertisements | SetPolicy, DeletePolicy, SetNeighborSet, DeleteNeighborSet, SetGlobalImportChain, SetGlobalExportChain, ClearGlobalImportChain, ClearGlobalExportChain, SetNeighborImportChain, SetNeighborExportChain, ClearNeighborImportChain, ClearNeighborExportChain |
PeerGroupService | ListPeerGroups, GetPeerGroup | SetPeerGroup, DeletePeerGroup, SetNeighborPeerGroup, ClearNeighborPeerGroup |
RibService | All read/list/explain RPCs (incl. ListFibTables) | SetFibTable, DeleteFibTable |
EventService | All RPCs | None |
EvpnService | GetEvpnRuntime, ListEvpnInstances, ListEvpnNexthops, ListEthernetSegments, ListIpVrfs, ListManagedNetdevs, GetIpVrf, ListDuplicateMacQuarantines | ClearDuplicateMacQuarantine, SetEthernetSegmentDrain, ApplyEvpnRuntime |
BfdService | GetBfdSessions | None |
RpkiService | ValidateRouteOrigin, ListCaches, LookupAspa, VerifyAsPath | None |
gnmi.gNMI | Capabilities, Get, Subscribe | Set (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) |
InjectionService | ListInjectionLeases, ListLeasedKeys, ListPathExportDispositions, BatchListPathExportDispositions, ListFlowSpecExportDispositions, BatchListFlowSpecExportDispositions | AddPath, DeletePath, AddFlowSpec, DeleteFlowSpec, AddLeasedPath, AddLeasedFlowSpec, RenewLease, IssueMutationWindow, AddGuardedFlowSpec, DeleteGuardedFlowSpec, RenewGuardedLease, MarkReplayComplete, AddEvpnRoute, DeleteEvpnRoute |
ControlService | CheckLiveness, GetHealth, GetMetrics | Shutdown, TriggerMrtDump |
Error Taxonomy
The API uses gRPC status codes consistently across services:
| Code | Meaning |
|---|---|
UNAUTHENTICATED | Listener authentication failed: missing bearer token, non-ASCII authorization metadata, or a token mismatch |
PERMISSION_DENIED | The 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_ARGUMENT | Client-supplied request data is malformed, missing, out of range, uses an unsupported enum value, or combines incompatible filters |
NOT_FOUND | A named or targeted resource does not exist: peer, policy, neighbor set, peer group, IP-VRF, route-event target, or injected route |
ALREADY_EXISTS | A create request targets an existing resource, such as duplicate neighbor creation or an exact-duplicate dynamic-neighbor range |
FAILED_PRECONDITION | The 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_EXCEEDED | A bounded actor or session read did not complete before its operation deadline; this does not mean the targeted runtime state is absent |
UNAVAILABLE | A required actor or session task exited, or a required actor, command channel, or persistence queue is unavailable, closed, or back-pressured |
UNIMPLEMENTED | The 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 |
INTERNAL | An 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 path | Existing backend wait budget |
|---|---|
| Peer-manager operator reads | 2 s per request to the peer manager, including channel admission and reply |
ListNeighbors / GetNeighborState RIB summaries | A 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 |
GetPolicyStats | One 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 |
GetHealth | One 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 reads | No 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:
| Message | Interface fields |
|---|---|
Route (received, best, advertised and explain rows) | peer_interface |
RouteEvent | peer_interface, previous_peer_interface, target_peer_interface |
EvpnRouteEvent | peer_interface, previous_peer_interface |
RouteSourceIdentity | peer_interface |
ExplainAdvertisedRouteResponse | peer_interface (target), route_peer_interface (selected route's source) |
OrrExplainCandidate | peer_interface |
ExplainBestPathResponse | peer_interface |
PathExportDispositionEntry | peer_interface |
ExplainImportPolicyResponse, ImportExplainMatch, ListRejectedRoutesResponse | peer_interface |
SessionEvent, NotificationEvent, PolicyEvent | peer_interface |
FibRouteStatus, BlackholeDiscard, DataplaneRouteEvent | peer_interface |
BfdSession, BfdSessionEvent | peer_interface |
PolicyChainStats | peer_interface (empty on the global row) |
TestPolicyDiff, TestPolicyRejectedRoute | peer_interface (beside peer) |
TcpAoKeyState | peer_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).
| Selector | Result |
|---|---|
192.0.2.1, 2001:db8::1 | Unchanged |
fe80::1%eth0, or fe80::1 with interface eth0 | Selects the neighbor on eth0 |
fe80::1 with no interface | INVALID_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 interface | INVALID_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 eth1 | INVALID_ARGUMENT |
fe80::1%eth1 when the configured neighbor on fe80::1 uses eth0 | NOT_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.
| RPC | Description |
|---|---|
GetGlobal | Returns 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/GetGlobalpolicy_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:aggregatefor the neighbor-widemax_prefixes, or the bound's canonical family label such asipv4_unicast,l3vpn_ipv4_unicastorl2vpn_evpn.stage:acceptedfor a bound counted after import policy, orreceivedfor themax_prefixes_received_*bounds counted before it. Only the unicast families have areceivedrow.
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.
| RPC | Description |
|---|---|
DiffRuntimeConfig | Validate candidate TOML and compare it against the daemon's live runtime config snapshot |
PlanConfigTransaction | Validate candidate TOML, return a runtime snapshot token, and classify v1 transaction support without mutating daemon state |
StreamPlanConfigTransaction | Outside-v1 authenticated client stream for plan-only candidates larger than the unary ceiling; returns the unchanged plan plus an optional ephemeral plan token |
StreamApplyConfigTransaction | Outside-v1 authenticated operator stream that consumes an exact streamed-plan binding and invokes the existing transaction executor |
ApplyConfigTransaction | Operator-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 |
ConfirmConfigTransaction | Confirm a pending confirmed transaction before its timer expires |
AbortConfigTransaction | Abort a pending confirmed transaction and roll back immediately |
GetConfigTransactionStatus | Return redacted confirmed-transaction lifecycle state |
GetLastSighupReload | Outside-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) |
GetEffectiveConfig | Return the effective running config as normalized TOML — defaults resolved, selected default-empty policy lists omitted, secrets redacted (rbgp config effective) |
ListConfigHistory | List 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. |
PreviewConfigRollback | Outside-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. |
RollbackConfigTransaction | Restore 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 reporteffective 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"
}
JSONPlan 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"
}
JSONUse 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:
| Field | Type | Meaning |
|---|---|---|
status | ConfigTransactionConfirmationStatus | Lifecycle state (see below). |
confirm_id | string | The operator-supplied handle for the transaction. |
timeout_seconds | uint32 | Effective confirm timeout applied (echoed). |
deadline_unix_seconds | uint64 | Absolute 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_sections | repeated string | Sections the confirmed apply committed. |
runtime_snapshot_token | string | Post-commit token for the pending change. |
human_text | string | Redacted human-readable summary. |
ConfigTransactionConfirmationStatus values:
| Value | Meaning |
|---|---|
..._UNSPECIFIED | Default zero value; not emitted in normal responses. |
..._NONE | No confirmed transaction is currently tracked. |
..._PENDING | Applied 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. |
..._CONFIRMED | Made permanent by ConfirmConfigTransaction. |
..._ABORTED | Rolled back by AbortConfigTransaction. |
..._AUTO_REVERTED | Timer expired; the pre-commit snapshot was re-applied. |
..._AUTO_REVERT_FAILED | Timer expired but the rollback re-apply failed; manual correction required. |
..._ABORT_FAILED | Abort 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"
}
JSONApply 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"
}
JSONApply 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
}
JSONInspect 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/ConfirmConfigTransactionAbort 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/AbortConfigTransactionThe 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-003NeighborService
Peer lifecycle management. Supports static peers from config and dynamic peers added at runtime.
| RPC | Description |
|---|---|
AddNeighbor | Add 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 |
DeleteNeighbor | Remove 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 |
ListNeighbors | List all peers with session state and counters |
GetNeighborState | Get detailed state for a single peer |
EnableNeighbor | Re-enable a previously disabled peer |
DisableNeighbor | Administratively disable a peer (sends NOTIFICATION: Cease / Administrative Shutdown, inside a Cease / Hard Reset when the peer negotiated RFC 8538 Notification GR) |
SoftResetIn | Request inbound route refresh (RFC 2918/7313) for one or more families |
RefreshOutbound | Re-emit one peer's current exportable outbound inventory across all negotiated families, without resetting the session |
ReplayOutbound | Schedule one Established peer's negotiated IPv4/IPv6 unicast replay with terminal UPDATE EoRs; outside the v1 contract |
ResetNeighbor | Administratively reset one enabled peer's session (Cease/Administrative Reset with an optional shutdown communication) |
AddDynamicNeighbor | Add a [[dynamic_neighbors]] prefix range at runtime; persists the accepted change atomically before returning and rolls back runtime on persistence failure |
DeleteDynamicNeighbor | Remove 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 |
ListDynamicNeighbors | List configured dynamic-neighbor ranges (prefix, peer group, remote ASN, description) |
SetGracefulShutdown | RFC 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:
| Mode | Meaning | remote_asn |
|---|---|---|
REMOTE_ASN_MODE_UNSPECIFIED | NUMERIC, the behavior before the field existed | the configured ASN, non-zero |
REMOTE_ASN_MODE_NUMERIC | the peer must send exactly remote_asn | the configured ASN, non-zero |
REMOTE_ASN_MODE_EXTERNAL | any ASN except the local one; an iBGP OPEN is refused | 0 |
REMOTE_ASN_MODE_INTERNAL | the local ASN | 0 |
- On
AddNeighbor,EXTERNALorINTERNALwith a non-zeroremote_asnisINVALID_ARGUMENT.remote_asn = 0is rejected only forNUMERICandUNSPECIFIED, and an unknown mode is rejected. ListNeighborsandGetNeighborStatereturn the configured mode withremote_asn = 0for a non-numeric mode, so the configured intent round-trips and is never replaced by a resolved or negotiated number.EXTERNALis 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 runtimeDisableNeighbor(rbgp neighbor <addr> disable).EnableNeighborclears it.CONFIG_ADMIN_DOWN: the neighbor's configuredadmin_down.MAX_PREFIX_LATCHED: a max-prefix shutdown latch.EnableNeighbor, or the single automatic attempt thatmax_prefix_restart_secondsarms, 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. OnlyEnableNeighborclears 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 reportsmax_prefix_actionshutdownand 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_addressis the IPv6 link-local address bound to it, without a scope, and is empty until an address is bound.NeighborState.discovery_stateisINTERFACE_MISSING,LINK_DOWN,AWAITING_DISCOVERYorBOUND, andUNSPECIFIEDfor every other neighbor.ListNeighborslists 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
interfaceselects that interface's interface-only neighbor. So doesfe80::x%swp1(orfe80::xwithinterfaceswp1) for any link-localx, 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 staysINVALID_ARGUMENT.GetNeighborStateanswers for it bound or not. Actions that need a session (enable, disable, reset, soft reset, refresh, replay) returnFAILED_PRECONDITIONuntil an address is bound.SetGracefulShutdownapplies 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):
AddNeighborwith an emptyNeighborConfig.addressand aninterfaceadds an interface-only neighbor, includingremote_asn_modeEXTERNALorINTERNAL. Discovery starts on the interface and a peer is created once an address is learned. An interface that already has one returnsALREADY_EXISTS.- The first interface-only neighbor needs
CAP_NET_RAWand the link monitor. Without themAddNeighborreturnsFAILED_PRECONDITION, naming the cause, with nothing changed. A static link-localAddNeighborat an interface-only neighbor's learned endpoint, its address on the same interface, bound or still reserved, returnsALREADY_EXISTS. One at that address on another interface returnsFAILED_PRECONDITIONwithbmp_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). DeleteNeighborwith an empty address and aninterfacedeletes 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 returnsNOT_FOUND. Deleting its bound peer by address returnsFAILED_PRECONDITION, naming the interface selector.- A
SetPeerGroupedit 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. SetNeighborPeerGroupandClearNeighborPeerGrouptake aninterfacefield. 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 forDeleteNeighbor.
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/AddNeighborFor 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/AddNeighborList all neighbors
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
localhost:50051 rustbgpd.v1.NeighborService/ListNeighborsGet a single neighbor's state
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
-d '{"address": "10.0.0.2"}' \
localhost:50051 rustbgpd.v1.NeighborService/GetNeighborStateDisable a neighbor
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
-d '{"address": "10.0.0.2", "reason": "maintenance"}' \
localhost:50051 rustbgpd.v1.NeighborService/DisableNeighborEnable a neighbor
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
-d '{"address": "10.0.0.2"}' \
localhost:50051 rustbgpd.v1.NeighborService/EnableNeighborReset 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/ResetNeighborResetNeighbor 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 returnFAILED_PRECONDITION(enable the peer instead of resetting it). - A session that is not
Establishedis still accepted:Connect/Activedrop back toIdlewithout a NOTIFICATION and follow the static or dynamic lifecycle above. For an enabled static peer already inIdle, 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,OpenSentorOpenConfirm. - 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
EventServicewith 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 asshutdown_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/DeleteNeighborTrigger 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/SoftResetInRefresh 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/RefreshOutboundscheduled: 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/ReplayOutboundReplayOutbound 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.
| RPC | Description |
|---|---|
ListPolicies | List all named policy definitions |
GetPolicy | Return one named policy definition |
SetPolicy | Create or replace a named policy definition |
DeletePolicy | Delete a named policy definition (rejected while referenced) |
ListNeighborSets / GetNeighborSet | List or fetch a named neighbor set |
SetNeighborSet / DeleteNeighborSet | Create/replace or delete a named neighbor set |
GetGlobalPolicyChains | Return global import/export chain assignments |
SetGlobalImportChain / SetGlobalExportChain | Replace 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 / ClearGlobalExportChain | Remove the global chain assignment |
GetNeighborPolicyChains | Return one neighbor's import/export chain assignments |
SetNeighborImportChain / SetNeighborExportChain | Replace one neighbor's chain assignment |
ClearNeighborImportChain / ClearNeighborExportChain | Remove one neighbor's chain assignment |
ExplainImportPolicy | Explain 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. |
ListRejectedRoutes | List 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. |
TestPolicy | Dry-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. |
ComparePolicy | Compare 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. |
GetPolicyStats | Read 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. |
GetValidationPolicyPosture | Conservatively 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. |
ListConditionalAdvertisements | List 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/ExplainImportPolicyEach 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/ListRejectedRoutesEach 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/SetPolicyAttach a global import chain
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
-d '{"policy_names": ["reject-bogons", "tag-internal"]}' \
localhost:50051 rustbgpd.v1.PolicyService/SetGlobalImportChainAttach 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/SetNeighborExportChainCreate 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/SetNeighborSetDelete a named policy
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
-d '{"name": "tag-internal"}' \
localhost:50051 rustbgpd.v1.PolicyService/DeletePolicyPeerGroupService
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.
| RPC | Description |
|---|---|
ListPeerGroups | List all peer-group definitions |
GetPeerGroup | Return one peer-group definition |
SetPeerGroup | Create or replace a peer-group definition |
DeletePeerGroup | Delete a peer-group definition (rejected while referenced) |
SetNeighborPeerGroup | Assign one neighbor to a peer group |
ClearNeighborPeerGroup | Remove 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/SetPeerGroupAssign 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/SetNeighborPeerGroupRibService
Query the routing information base. Its route surface is query-only; stream live
route changes through EventService.WatchEvents.
| RPC | Description |
|---|---|
ListReceivedRoutes | Adj-RIB-In: all routes received from peers |
ListBestRoutes | Loc-RIB: best route per prefix after path selection |
ListAdvertisedRoutes | Adj-RIB-Out: routes advertised to a specific peer |
ExplainAdvertisedRoute | Dry-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. |
ExplainBestPath | Show all candidates for a prefix with decisive comparison reasons; optional peer_address field scopes to that peer's Add-Path send view |
LookupBestPath | Outside-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 |
ListFlowSpecRoutes | FlowSpec 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 |
ListEvpnRoutes | Deprecated whole-table EVPN Loc-RIB view, outside v1; use ListBestEvpnRoutes for bounded best pages |
ListReceivedEvpnRoutes | Bounded accepted post-policy EVPN Adj-RIB-In for one source neighbor, filterable by type / RD |
ListAdvertisedEvpnRoutes | Bounded committed EVPN Adj-RIB-Out for one destination neighbor, filterable by type / RD |
ExplainEvpnRoute | Exact typed EVPN candidate selection, optional destination export trace and caller-selected SRv6 Argument pair inspection, with installed and committed state kept distinct |
ListBgpLsRoutes | Deprecated whole-table selected BGP-LS / BGP-LS VPN view, outside v1; use ListBgpLsRibRoutes with view = BEST |
ListVpnRoutes | Deprecated whole-table selected VPNv4/VPNv6 view, outside v1; use ListVpnRibRoutes with view = BEST |
ListLabeledRoutes | Deprecated whole-table selected labeled-unicast view, outside v1; use ListLabeledRibRoutes with view = BEST |
ListRtcRoutes | Deprecated whole-table selected RT-Constrain view, outside v1; use ListRtcRibRoutes with view = BEST |
ListVpnRibRoutes | Scoped RR-only L3VPN: bounded best/received/advertised pages with typed family, prefix, RD and peer filters |
ListLabeledRibRoutes | Scoped RR-only labeled-unicast: bounded best/received/advertised pages with typed family, prefix and peer filters |
ListRtcRibRoutes | Scoped RR-only RT-Constrain: bounded best/received/advertised pages with membership and peer filters |
ListBgpLsRibRoutes | Scoped 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 |
ListBestEvpnRoutes | Bounded 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 |
ListTopologyNodes | Deprecated whole-graph RFC 9107 ORR node view, outside v1; use ListOrrTopologyNodes |
ListTopologyLinks | Deprecated whole-graph RFC 9107 ORR link view, outside v1; use ListOrrTopologyLinks |
ListOrrTopologyNodes | Scoped RR-only: bounded pages of RFC 9107 ORR topology nodes built from the BGP-LS Adj-RIB-In union |
ListOrrTopologyLinks | Scoped RR-only: bounded pages of RFC 9107 ORR topology links — IGP adjacencies, link addresses, and metrics (the SPF input) |
ListOrrStatus | RFC 9107 ORR per-vantage status — configured vantages, their resolved topology nodes, and the peers bound to them |
ListBlackholeDiscards | RFC 7999 BLACKHOLE kernel-discard install status when [global] honor_blackhole = true and [global] install_blackhole_discard = true |
ListFibRoutes | ADR-0061 general unicast Linux FIB route status for configured [[fib_tables]] |
ListFibTables | List 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) |
SetFibTable | Create-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) |
DeleteFibTable | Remove a [[fib_tables]] entry by name at runtime; NOT_FOUND if absent (mutating) |
ListRouteEvents | Recent 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.
| Need | Surface | Shape | Retention / loss behavior |
|---|---|---|---|
| Live unicast route deltas | EventService.WatchEvents with EVENT_CATEGORY_ROUTE | Streaming event feed | Live-only; WatchEvents emits stream_lagged when slow subscribers miss events |
| Recent unicast route timeline | ListRouteEvents / rbgp events | Bounded history query | In-memory 4096-event ring, process-local, oldest entries evicted |
| Live session lifecycle | EventService.WatchEvents with EVENT_CATEGORY_SESSION | Streaming event feed | Live-only; no replay after reconnect |
| Recent session lifecycle | EventService.ListSessionEvents / rbgp events sessions | Bounded history query | In-memory 4096-event ring shared by all peers, process-local; the response reports evicted_total and oldest_retained_unix_ms |
| Live policy mutation summaries | EventService.WatchEvents with EVENT_CATEGORY_POLICY | Streaming event feed | Live-only; slow subscribers can lag and miss events |
| Recent policy mutation summaries | EventService.ListPolicyEvents / rbgp events policy | Bounded history query | In-memory 4096-event ring, process-local, oldest entries evicted |
| Live EVPN route best-path deltas | EventService.WatchEvents with EVENT_CATEGORY_EVPN | Streaming event feed | Live-only; slow subscribers can lag and miss events |
| Recent EVPN route timeline | EventService.ListEvpnEvents / rbgp events evpn | Bounded history query | In-memory 4096-event ring, process-local, oldest entries evicted |
| RFC 7999 discard programming | ListBlackholeDiscards / rbgp rib blackholes | Snapshot | Current reconcile snapshot only; retryable limit blocks are REJECTED with active_limit_exceeded or install_rate_limited |
| ADR-0061 general Linux FIB programming | ListFibRoutes / rbgp rib fib | Snapshot | Current reconcile snapshot plus persisted owned-state semantics |
| ADR-0061 FIB route apply outcomes | EventService.WatchEvents with EVENT_CATEGORY_DATAPLANE and BGP_EVENT_TYPE_DATAPLANE_ROUTE_* / rbgp events watch --category dataplane | Streaming event feed | Live via WatchEvents; no replay and no bounded List* history API |
| EVPN L2/L3 dataplane readiness and managed-netdev ownership status | EvpnService (ListEvpnInstances, ListEvpnNexthops, ListEthernetSegments, ListIpVrfs, ListManagedNetdevs) / rbgp evpn ... | Snapshot | Latest daemon or dataplane report snapshot |
| BGP-LS topology objects | ListBgpLsRibRoutes / rbgp rib bgpls | Bounded pages | Selected Loc-RIB, accepted input or committed export; raw BGP-LS NLRI/TLV bytes preserved |
| ADR-0067 BFD session state | BfdService.GetBfdSessions / rbgp bfd | Snapshot | Current BFD actor snapshot |
| Live BFD session state changes | EventService.WatchEvents with EVENT_CATEGORY_BFD and BGP_EVENT_TYPE_BFD_SESSION_* / rbgp events watch --category bfd | Streaming event feed | Live-only; opt-in (not in the default route+session set); slow subscribers can lag |
| Alerting / counters | Prometheus /metrics | Cumulative counters and gauges | Process 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/ListReceivedRoutesList best routes (Loc-RIB)
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
localhost:50051 rustbgpd.v1.RibService/ListBestRoutesList 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/ListAdvertisedRoutesExplain 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/ExplainAdvertisedRouteThis 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/ExplainAdvertisedRouteThe 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/LookupBestPathrbgp 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/ListBestRoutespage_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/WatchEventsEach 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/ListRouteEventsListRouteEvents 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/ListFlowSpecRoutesADDRESS_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_target | Extended community |
|---|---|
ASN:value, ASN up to 65535, 32-bit value | Redirect 2-octet AS (0x8008) |
a.b.c.d:value, 16-bit value | Redirect IPv4 address (0x8108, RFC 7674) |
ASN:value, ASN above 65535, 16-bit value | Redirect 4-octet AS (0x8208, RFC 7674) |
high.low:value (RFC 5396 asdot+), 16-bit value | Redirect 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_flowspecClients 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 100The 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/ListAdvertisedEvpnRoutesThe 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/ListBestEvpnRoutesFor 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 selector | Proto selector | Required key fields beyond RD | Ethernet Tag |
|---|---|---|---|
ead-per-es | ead_per_es | --esi | CLI fixes it to MAX_ET; RPC requires 4294967295 |
ead-per-evi | ead_per_evi | --esi, --ethernet-tag | Required; MAX_ET is rejected |
mac-ip | mac_ip | --mac; optional --ip | --ethernet-tag defaults to 0 |
imet | imet | --originator-ip | --ethernet-tag defaults to 0 |
es | es | --esi, --originator-ip | Not part of the Type 4 key |
ip-prefix | ip_prefix | --prefix in canonical CIDR form | --ethernet-tag defaults to 0; nonzero tags are supported |
smet | smet | --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/ExplainEvpnRouteThe 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:
| Field | Meaning |
|---|---|
received | Accepted post-policy Adj-RIB-In route from received_from, if retained. Omitted when no source is requested or no accepted route is retained. |
candidate_count | Number of currently retained accepted candidates across sources. |
best | Installed Loc-RIB route. |
selection_best | Winner of a fresh comparison over the retained candidates, without installing it. |
compared | Requested 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_reason | Decisive reason why selection_best beats compared; absent without a pair. |
selection_deferred | EVPN selection is currently deferred; the installed best may differ from fresh selection or be absent. |
export | Present 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.9Both 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.
| Status | Meaning |
|---|---|
COMPOSED / composed | A candidate SID combines the IMET LOC:FUNC with the selected companion's Argument. |
LOC_FUNC_ONLY / loc_func_only | A candidate LOC:FUNC SID with zero Argument bits, including when no usable companion Argument is present or the IMET Argument length is zero. |
CONFLICT / conflict | Both relevant Argument lengths are nonzero and differ; no candidate SID. This concerns the requested pair, not route selection. |
UNAVAILABLE / unavailable | Required SID, structure, label or transposition input cannot be used; no candidate SID. |
AMBIGUOUS / ambiguous | Multiple 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/ListBgpLsRibRoutesListBgpLsRibRoutes 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.
List ORR topology nodes and links
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/ListOrrTopologyLinksListOrrTopologyNodes 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/ListBlackholeDiscardsReturns 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 100Returns 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.
| RPC | Description |
|---|---|
WatchEvents | Server-streaming: unified typed event stream sourced from structured daemon events |
ListSessionEvents | Unary: recent session lifecycle events from the peer manager's bounded in-memory history |
ListPolicyEvents | Unary: recent policy / neighbor-set / peer-group / chain mutation events from the peer manager's bounded in-memory history |
ListEvpnEvents | Unary: 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/ListEvpnEventsWatchEvents 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:
| Category | Compatible event types |
|---|---|
| Route | BGP_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 |
| Session | 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, BGP_EVENT_TYPE_MAX_PREFIX_WARNING, BGP_EVENT_TYPE_NOTIFICATION_SENT, BGP_EVENT_TYPE_NOTIFICATION_RECEIVED, BGP_EVENT_TYPE_STREAM_LAGGED |
| Policy | BGP_EVENT_TYPE_POLICY_CHANGED (never BGP_EVENT_TYPE_STREAM_LAGGED) |
| Dataplane | BGP_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) |
| EVPN | BGP_EVENT_TYPE_EVPN_ROUTE_ADDED, BGP_EVENT_TYPE_EVPN_ROUTE_WITHDRAWN, BGP_EVENT_TYPE_EVPN_ROUTE_BEST_CHANGED, BGP_EVENT_TYPE_STREAM_LAGGED |
| BFD | BGP_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:
| Type | Meaning |
|---|---|
BGP_EVENT_TYPE_ROUTE_ADDED | Best path for a prefix was added |
BGP_EVENT_TYPE_ROUTE_WITHDRAWN | Best path for a prefix was withdrawn |
BGP_EVENT_TYPE_ROUTE_BEST_CHANGED | Best path for a prefix changed |
BGP_EVENT_TYPE_SESSION_STATE_CHANGED | BGP FSM state changed; payload carries old/new state and session role |
BGP_EVENT_TYPE_SESSION_ESTABLISHED | FSM reached Established |
BGP_EVENT_TYPE_SESSION_LOST | FSM left Established; severity is WARNING |
BGP_EVENT_TYPE_PEER_ADDED | Peer 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_REMOVED | Peer 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_ENABLED | Operator enabled a configured peer |
BGP_EVENT_TYPE_PEER_DISABLED | Operator disabled a configured peer |
BGP_EVENT_TYPE_NOTIFICATION_SENT | rustbgpd sent a BGP NOTIFICATION; payload carries direction, code, subcode, description, session role, and optional RFC 9003 shutdown reason |
BGP_EVENT_TYPE_NOTIFICATION_RECEIVED | rustbgpd received a BGP NOTIFICATION from the peer; payload carries the same metadata |
BGP_EVENT_TYPE_BFD_SESSION_UP | BFD session transitioned to Up |
BGP_EVENT_TYPE_BFD_SESSION_DOWN | BFD session transitioned to Down |
BGP_EVENT_TYPE_BFD_SESSION_STATE_CHANGED | BFD 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:
| Type | Meaning |
|---|---|
BGP_EVENT_TYPE_STREAM_LAGGED | Source-scoped route, session, per-route dataplane, EVPN, or BFD loss on the live stream. |
Policy event types:
| Type | Meaning |
|---|---|
BGP_EVENT_TYPE_POLICY_CHANGED | Runtime 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:
| Type | Meaning |
|---|---|
BGP_EVENT_TYPE_DATAPLANE_STATUS_CHANGED | FIB / 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_INSTALLED | ADR-0061 FIB runtime successfully installed or replaced one route |
BGP_EVENT_TYPE_DATAPLANE_ROUTE_WITHDRAWN | ADR-0061 FIB runtime successfully removed one owned route |
BGP_EVENT_TYPE_DATAPLANE_ROUTE_FAILED | ADR-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).
| RPC | Description |
|---|---|
AddPath | Inject a route with specified attributes |
DeletePath | Withdraw a previously injected route |
ListPathExportDispositions | Per-peer export disposition of one injected unicast route; see export read-back |
BatchListPathExportDispositions | The same for up to 1000 injected unicast route keys per paged walk; see batch read-back |
ListFlowSpecExportDispositions | The same for one injected FlowSpec rule; see FlowSpec read-back |
BatchListFlowSpecExportDispositions | The same for up to 1000 injected FlowSpec rule keys per paged walk; see FlowSpec batch read-back |
AddFlowSpec | Inject a FlowSpec rule with actions |
DeleteFlowSpec | Withdraw a previously injected FlowSpec rule |
AddLeasedPath / AddLeasedFlowSpec | Inject a route or FlowSpec rule under an owner's lease; see leased injection |
RenewLease | Renew an owner's lease generation |
ListInjectionLeases | List the injection lease table |
ListLeasedKeys | List the keys one lease owner holds; see reconcile an owner's keys |
IssueMutationWindow / AddGuardedFlowSpec / DeleteGuardedFlowSpec / RenewGuardedLease | Window- and revision-fenced FlowSpec mutations; see guarded FlowSpec mutations |
MarkReplayComplete | Signal that a controller finished replaying after a planned restart; see replay-complete signal |
AddEvpnRoute | Inject 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 |
DeleteEvpnRoute | Withdraw 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/AddPathInject 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/AddPathOptional 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.
| Prefix | Next hop sent on each session |
|---|---|
| IPv4 | The 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 |
| IPv6 | The 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 --checkwarns 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_hopinbgp_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/AddPath4294902426 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/DeletePathUnicast 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.outcome | Meaning |
|---|---|
PATH_INJECT_OUTCOME_CREATED | No local route had this key. |
PATH_INJECT_OUTCOME_REPLACED | A local route with this key had a different next hop or attributes; the new route replaced it. |
PATH_INJECT_OUTCOME_UNCHANGED | An identical local route already existed. The stored route, including its RPKI validation state, is kept and nothing is redistributed. |
PATH_INJECT_OUTCOME_UNSPECIFIED | The 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.outcome | Meaning |
|---|---|
PATH_DELETE_OUTCOME_DELETED | A local route with this key was removed from the local Adj-RIB-In. |
PATH_DELETE_OUTCOME_NOT_PRESENT | No local route had this key; returned only with allow_missing. |
PATH_DELETE_OUTCOME_UNSPECIFIED | The 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.
disposition | Meaning |
|---|---|
PATH_EXPORT_DISPOSITION_COMMITTED | This 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_WITHHELD | The route is not exported to this peer; reason says why. |
PATH_EXPORT_DISPOSITION_PENDING | Export has not settled; reason names what is outstanding. |
PATH_EXPORT_DISPOSITION_NOT_ESTABLISHED | The 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.
reason | Disposition | Meaning |
|---|---|---|
family_suppressed:<reason> | Withheld | The 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_negotiated | Withheld | The session did not negotiate the route's family. This takes precedence over any pending reason. |
not_selected | Withheld | Another path is this peer's selected route, or the route ranks beyond the peer's Add-Path send_max. |
export_policy | Withheld | Export policy, or the RFC 8212 default deny, rejects the route; for a per-client-best peer, the policy denies every candidate. |
outbound_prefix_limit | Withheld | The peer's outbound prefix limit is reached. |
exact_export_rejected:<reason> | Withheld | The 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_rule | Withheld | Another export gate stops the route, such as split horizon, NO_ADVERTISE, LLGR, an ORF filter, OTC or conditional advertisement. |
selection_deferred | Pending | Graceful 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_resync | Pending | Outbound delivery to the peer is resynchronizing. |
orf_pending | Pending | The peer negotiated ORF and has not sent its first ROUTE-REFRESH. |
not_yet_committed | Pending | The route is staged but the Adj-RIB-Out does not hold it yet. |
not_established | Not established | The 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 statement | deny_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 deny | empty |
| Later statement's deny after a statement that tested RPKI permitted | empty |
| RFC 8212 default deny, per-client-best deny of every candidate | empty; 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_policyof 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 itsNOT_ESTABLISHEDrow 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/ListPathExportDispositionsBatch 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_ARGUMENTbefore any work. Split a larger set across walks. - Entries per page.
page_size0 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_ESTABLISHEDrows 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/BatchListPathExportDispositionsFlowSpec 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:
reason | Disposition | FlowSpec meaning |
|---|---|---|
family_not_negotiated | Withheld | The session did not negotiate the rule's FlowSpec family. |
not_selected | Withheld | A received rule with the same key is selected (no explain_code), or no rule is selected (no_best_route). |
export_policy | Withheld | Export policy, or the RFC 8212 default deny, rejects the rule. |
export_rule | Withheld | A 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_rejected | Withheld | The session's encoder refuses the rule. |
outbound_resync, not_yet_committed | Pending | As for unicast. |
not_established | Not established | As 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/ListFlowSpecExportDispositionsFlowSpec 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 = falseand no rows; the call does not fail withNOT_FOUND. - A malformed key does not fail the call either. A key that
ListFlowSpecExportDispositionswould refuse withINVALID_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 withfound = false, no rows anderrorset:codeisinvalid_keyandmessagebegins withkeys[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_ARGUMENTnaming 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_sizecounts 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
ABORTEDwhen 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 changesListPathExportDispositionschecks. A malformed key never has a rule, so it never aborts a walk. - The
next_page_tokenis bound to the keys exactly as sent, in order,include_configuredand the daemon process. A token from another key list or from another export-disposition RPC returnsINVALID_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/BatchListFlowSpecExportDispositionsLeased 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}.
| Rule | Behaviour |
|---|---|
owner | 1-64 bytes of [A-Za-z0-9._-], else INVALID_ARGUMENT |
lease_seconds | 5-3600, else INVALID_ARGUMENT |
| Leased add, owner has a live lease | Joins it; the deadline becomes max(current, now + lease_seconds) and never moves earlier |
| Leased add, no live lease | Starts a new generation; at most 64 live owners, else RESOURCE_EXHAUSTED |
| Leased add of a key the owner does not hold | At 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 owner | FAILED_PRECONDITION (OWNER_MISMATCH) |
| Leased add on a key held by no owner | FAILED_PRECONDITION (KEY_UNOWNED); delete the unowned entry first, or add under another path_id |
| Unowned add on an owned key | FAILED_PRECONDITION (OWNER_MISMATCH) |
DeletePath/DeleteFlowSpec | owner 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:
generation | keys | Meaning |
|---|---|---|
| absent | any | The owner has no live lease. Re-add the whole desired state; any keys listed are expired and awaiting withdrawal. |
| present | some | The 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. |
| present | none | A 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:
- List its owner's keys page by page, restarting the walk on
ABORTED. - 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.
- Delete each listed key it no longer wants with
DeletePathorDeleteFlowSpec, passing itsowner. - 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/ListLeasedKeysTo 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-pop1Without 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/RenewLeaseConnecting 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.sockwith insecure channel credentials. Such a socket authorizes its clients as the implicitlocal-operatorprincipal; no token or roles entry is needed. Set the channel's default authority to a host name such aslocalhost: 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]on127.0.0.1withtoken_fileand aprincipalmapped tooperatorin[security.grpc.roles], and sendauthorization: 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.
| RPC | Behaviour |
|---|---|
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.
| Refusal | Status |
|---|---|
Malformed owner, window_seconds outside 1..=120, revision 0, missing window, rule, lease or generation, lease_seconds outside 5..=3600 | INVALID_ARGUMENT |
| Window expired, unknown, another owner's or another process's | FAILED_PRECONDITION, WINDOW_NOT_LIVE |
| Present rule at another revision, or at the same revision with another payload; delete of another revision | FAILED_PRECONDITION, REVISION_MISMATCH |
| Rule held by another owner, guarded or not, or by no owner | FAILED_PRECONDITION, OWNER_MISMATCH or KEY_UNOWNED |
| Renewal of a generation that is not live | FAILED_PRECONDITION, GENERATION_NOT_LIVE |
| Window cap reached | RESOURCE_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/AddGuardedFlowSpecReplay-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:
- Read the daemon incarnation
IfromControlService.CheckLiveness(orLeaseGeneration.incarnationfrom a leased add) before replaying. - Re-add the full desired state.
- 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.
| Result | Meaning |
|---|---|
OK RELEASED | This owner was the last one awaited; the replay grace hold was released. Other convergence gates still apply. |
OK RECORDED | Recorded; awaiting lists the listed owners that have not signalled |
OK NOT_EXPECTED | The owner is not in gr_eor_replay_owners; nothing changed (logged at WARN) |
OK NOT_HOLDING | No 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_MISMATCH | I 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/MarkReplayCompleteInject 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/AddFlowSpecWithdraw 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/DeleteFlowSpecFlowSpec 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.outcome | Meaning |
|---|---|
FLOW_SPEC_INJECT_OUTCOME_CREATED | No local rule had this key. |
FLOW_SPEC_INJECT_OUTCOME_REPLACED | A local rule with this key had different actions or communities; the new payload replaced it. |
FLOW_SPEC_INJECT_OUTCOME_UNCHANGED | An identical local rule already existed. Nothing is redistributed. |
FLOW_SPEC_INJECT_OUTCOME_UNSPECIFIED | The 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.outcome | Meaning |
|---|---|
FLOW_SPEC_DELETE_OUTCOME_DELETED | A local rule with this key was removed from the local Adj-RIB-In. |
FLOW_SPEC_DELETE_OUTCOME_NOT_PRESENT | No local rule had this key; returned only with allow_missing. |
FLOW_SPEC_DELETE_OUTCOME_UNSPECIFIED | The 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/ListFlowSpecRoutesrbgp 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.
| Message | Scope fields |
|---|---|
AddFlowSpecRequest, including leased/guarded wrappers | rd (7), route_targets (8) |
DeleteFlowSpecRequest | rd (6) |
DeleteGuardedFlowSpecRequest | rd (5) |
LeasedFlowSpecKey | rd (3) |
ListFlowSpecExportDispositionsRequest | rd (6) |
FlowSpecRouteEntry | rd (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/ListFlowSpecRoutesUse 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/AddEvpnRoutedisable_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/AddEvpnRouteInject 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/AddEvpnRouteBy 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/DeleteEvpnRouteThe 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/DeleteEvpnRouteControlService
Daemon lifecycle, health checks, and metrics.
| RPC | Description |
|---|---|
CheckLiveness | Empty 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. |
GetHealth | Returns health status, uptime, active peers, total routes; core actor probes are bounded by the same 200 ms deadline as HTTP /readyz |
GetMetrics | Returns 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 |
Shutdown | Initiates graceful shutdown |
TriggerMrtDump | Triggers 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/GetHealthFor 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 --livenessIf [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/GetMetricsGraceful shutdown
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
-d '{"reason": "maintenance window"}' \
localhost:50051 rustbgpd.v1.ControlService/ShutdownTrigger MRT dump
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
localhost:50051 rustbgpd.v1.ControlService/TriggerMrtDumpEvpnService
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.
| RPC | Description |
|---|---|
GetEvpnRuntime | Return the committed EVPN runtime generation, lifecycle, mutation state, configured EVI/IP-VRF/ES counts, and a concise status message |
ListEvpnInstances | List 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 |
ListEvpnNexthops | List 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 |
ListEthernetSegments | List 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 |
ListIpVrfs | List 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 |
ListManagedNetdevs | List 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. |
GetIpVrf | Detail 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 |
ListDuplicateMacQuarantines | List 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. |
ClearDuplicateMacQuarantine | Clear 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. |
ApplyEvpnRuntime | Validate 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:
| Status | Meaning |
|---|---|
FAILED_PRECONDITION | No 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. |
INTERNAL | Known 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. |
UNAVAILABLE | Daemon 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/GetEvpnRuntimeOr via CLI:
rbgp evpn runtime # human format
rbgp evpn runtime --json # JSON outputList local EVPN instances
grpcurl -plaintext -import-path . -proto proto/rustbgpd.proto \
localhost:50051 rustbgpd.v1.EvpnService/ListEvpnInstancesOr via CLI:
rbgp evpn instances # human format
rbgp evpn instances --json # JSON output
rbgp evpn diagnose # instance / Type 2 / Type 3 / metric summaryThe 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/ListEvpnNexthopsOr via CLI:
rbgp evpn nexthops # human format
rbgp evpn nexthops --json # JSON outputAn 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/ListEthernetSegmentsOr via CLI:
rbgp evpn es list
rbgp evpn es list 00:11:22:33:44:55:66:77:88:99 --jsonList 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/ListIpVrfsOr 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/ListManagedNetdevsOr via CLI:
rbgp evpn managed-netdevs
rbgp evpn managed-netdevs --jsonGet 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/GetIpVrfClear 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/ClearDuplicateMacQuarantineOr 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 --jsonDrain 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 example00:11:22:33:44:55:66:77:88:99. A malformed ESI returnsINVALID_ARGUMENT; an ESI with no configured[[ethernet_segments]]entry returnsNOT_FOUND.drained—trueadds theoperatordrain reason,falseremoves 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:truewhile any drain reason is held.changed—falsewhen theoperatorreason 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/SetEthernetSegmentDrainOr 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 roleApply 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
}
JSONA 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.
| RPC | Description |
|---|---|
GetBfdSessions | List 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/GetBfdSessionsstate 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/ValidateRouteOriginThe 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/ListCachesASPA 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.