rustbgpdCookbook — scenario-driven deployment recipes
Choose a complete rustbgpd deployment recipe.
Choose a complete rustbgpd deployment recipe.
Each recipe here is a complete deployment shape: a working config, the
verification commands with the output shape to expect, the metrics to
watch, and the failure modes with the explain commands that debug them.
The configs are derived from the interop fixtures under
tests/interop/configs/ that the
M-series receipts run against real peer stacks — every recipe cites the
receipts that prove its scenario (RECEIPTS.md).
Find the route-server path
| I want to… | Read this |
|---|---|
| Decide whether rustbgpd fits an IXP route-server deployment | IXP evaluation |
| Build a route server from hand-maintained member and policy configuration | IXP route server |
Keep an existing ARouteServer general.yml / clients.yml workflow | IXP filter pipeline |
| Provision from an IXP Manager v7.4 database | IXP Manager route server |
| Run a non-authoritative comparison beside the incumbent, without planning a cutover yet | Route-server shadow pilot |
| Replace an incumbent through a planned shadow trial and cutover | Route-server migration |
| Verify or troubleshoot a hand-maintained route server after deployment | IXP route server |
How the six route-server documents divide the work
| Document | Scope it owns | Scope it does not own |
|---|---|---|
| IXP evaluation | Fit assessment: capability, evidence, and product-boundary checks before choosing a deployment | Configuration generation, a running pilot, or cutover procedure |
| IXP route server | Hand-maintained member and policy configuration, validation, startup, and day-2 verification | ARouteServer or IXP Manager generation, standing incumbent comparison, or migration planning |
| IXP filter pipeline | ARouteServer input, generated datasets and configuration, validated activation, and Alice-LG integration | Hand-maintained inventories, IXP Manager lifecycle, or incumbent cutover |
| IXP Manager route server | IXP Manager export, render, receipt, activation, rollback, lock, fetch, and callback lifecycle | ARouteServer inputs or a generic incumbent-replacement plan |
| Route-server shadow pilot | A standing, receive-only comparison beside production, including its mode-specific safety boundary, comparison loop, data return, and teardown | Authoritative service or a decision to cut over |
| Route-server migration | Incumbent concept mapping, a cutover-oriented shadow trial, readiness gates, cutover, and rollback | A long-running evaluation with no planned authority transfer |
The only genuine overlap is the comparison interval shared by the shadow-pilot and migration guides. The shadow-pilot guide owns an ongoing non-authoritative evaluation; the migration guide repeats the comparison only as a gate on a planned cutover. The three provisioning guides can look similar because each produces a route-server configuration, but their input authority is mutually exclusive: hand-maintained files, ARouteServer, or IXP Manager.
IXP provisioning: three modes
An exchange provisions a rustbgpd route server in exactly one of three mutually exclusive shapes. Pick by what you already have; each row's recipe names the other two.
| Mode | You have… | The pipeline | Recipe | Proven by |
|---|---|---|---|---|
| Hand-written | nothing external — you author members and policy yourself | examples/route-server/config.toml → rustbgpd --check --strict → SIGHUP | IXP route server | M83 |
| ARouteServer-driven | arouteserver's general.yml / clients.yml and its refresh cadence | arouteserver template-context → rs-config-render → --check --strict → swap + SIGHUP, fail-stale | IXP filter pipeline | M83, M90 (11/11 BIRD differential parity) |
| IXP Manager-driven | IXP Manager v7.4 as the member and router database | Foil template → rs-config-render --input-format ixp-manager-v2 → --check --strict receipt → atomic activation with rollback → IXP Manager lock/fetch/callback lifecycle, rustbgpd@<handle>.service per handle | IXP Manager route server | M96, M97 (local gates), pinned v7.4 contract oracle |
The renderer owns the whole output directory in both automated modes, so you do not hand-edit their output, and IXP Manager mode activates only unmodified receipted candidates. Piloting any mode beside your incumbent with zero blast radius is the shadow pilot; two instances of any mode are paired route servers.
| Recipe | When this is you | Proven by |
|---|---|---|
| iBGP route reflector at scale | Replacing an iBGP full mesh; tens to 1,000 clients | M14, M76, M77, 1000-peer scale receipt |
| L3VPN route reflector | VPNv4/VPNv6 reflection for a PE fleet, RT-Constrain filtered | M74, M75, M77, VPN scale receipt |
| IXP route server | Transparent redistribution among exchange members: RPKI, RFC 9234 roles, Add-Path + per-client best-path | M83 |
| Route-server migration | Map FRR, BIRD, and ARouteServer concepts into rustbgpd and run a shadow-trial cutover | M83 |
| Route-server shadow pilot | Run rustbgpd for weeks as a receive-only, non-authoritative second route server beside production BIRD/OpenBGPD — the receive-only posture per provisioning mode (hand-written, arouteserver overlay, and what an IXP Manager site does instead), standing comparison loop, what a pilot cannot get yet, data-return contract, clean teardown | M83, M90, IXP receipt matrix; M96/M97 referenced for the cutover-shaped stack |
| IXP filter pipeline | Keep your arouteserver general.yml/clients.yml: render member filters with rs-config-render, reload fail-stale, serve Alice-LG | M83, M90 |
| IXP Manager route server | IXP Manager v7.4 provisions the route server: Foil export → render → --check --strict receipt → atomic activation → lock/fetch/callback lifecycle, paired handles, IXP Manager looking glass through the Birdwatcher surface — with the boundary stated | M96, M97 (local), pinned v7.4 contract oracle |
| MANRS IXP Action 1 | Document your MANRS IXP Programme participation: Action 1 mapped requirement-by-requirement to validated config and member-verifiable surfaces | M83, fragments pass rustbgpd --check --strict |
| Controller / monitoring feed | Streaming BMP, durable events, and MRT into a controller or collector stack | M24, M81 |
| EVPN fabric route reflector | Control-plane-only RR for a VXLAN-EVPN leaf/spine fabric | M29, M30, M82, M33 |
Policy quickstart (.rpol) | First typed policy: tests, dry-run, hot swap, explain | M80, M34 |
Operator runbooks — short, ordered checklists for a live daemon:
| Runbook | When to reach for it |
|---|---|
| Peer-flap triage | A session keeps cycling: confirm, read events, match the teardown reason, contain |
| RR pair day-2 | Routine changes on a redundant RR pair: GR sanity, adding clients, hot vs session-reset edits, commit-confirm |
| Paired route servers | Two independent RS instances: staggered config rollout, inter-RS consistency via rbgp diff advertised, RFC 8326 maintenance drain |
| Activation manual recovery | The activation or lifecycle helper returned exit 5 (ManualRecovery): confirm candidate health, keep or roll back, release the lifecycle lock, handle the receipt, resume automation |
| Shadow cutover | The step-by-step shadow trial lives in route-server-migration.md; the comparison tool it gates on is rbgp diff advertised |
Conventions:
- Addresses are examples (RFC 5737 / private ranges) — substitute your own. No config here references a hostname.
- Every config in this directory's recipes loads through the real
config loader: validated with
rustbgpd --checkand a daemon startup on the same commit that shipped them. - gRPC in the recipes stays on the default local Unix socket with tier authorization (ADR-0064). For remote access, see the mTLS guidance in the security reference.
- Start here if you haven't run the daemon at all yet:
docs/tutorials/quickstart.md, then come back for your scenario. - Debugging why a route was (not) selected, advertised, or imported?
The explain-surface catalog is
docs/how-to/explain.md.
IXP route-server evaluation matrix
One page for an exchange evaluating rustbgpd as a route server: the capabilities IXP evaluations actually score, each with its current status and a link to the config, cookbook, ADR, or measurement receipt that backs it.
iBGP route reflector at scale
Replace an iBGP full mesh with a dedicated route reflector.