rustbgpd

An API-first BGP daemon in Rust, built for programmable route-server and control-plane use cases. gRPC is the primary interface for all peer lifecycle, routing, and policy operations. The config file bootstraps initial state; after startup, gRPC owns the truth. No restarts to add peers, change policy, or inject routes.

Status: public alpha. Feature-complete for the initial route-server and control-plane target. Dual-stack BGP/MP-BGP, Add-Path, GR/LLGR, RPKI/RTR, ASPA path verification, FlowSpec, BMP, MRT, and full gRPC/CLI management are implemented. Kernel FIB integration and broader router features remain future work. Validated with 1166 workspace tests, fuzz targets, and 22 automated interop suites against FRR 10.3.1, BIRD 2.0.12, GoBGP 4.3.0, and StayRTR.

Alpha expectations: The config format and gRPC API are not yet frozen. Breaking changes are possible between minor versions. The daemon runs on Linux (the primary target); other platforms are not tested. See Project Status for details.

Why rustbgpd

• API-first control plane -- full gRPC control surface across 7 services plus a thin CLI (rustbgpctl) with colored tables, dynamic column alignment, and human-readable uptimes. Dynamic peer management, route injection, policy CRUD, peer groups, streaming events, and daemon control without restarts.
• Explicit architecture -- pure FSM with no I/O, single-owner RIB with no locks, bounded channels between tasks. No Arc<RwLock> on routing state. See ARCHITECTURE.md.
• Dual-stack and modern protocol support -- MP-BGP, Add-Path, Extended Next Hop, Extended Messages, GR/LLGR/Notification GR, Route Refresh/Enhanced Route Refresh, FlowSpec, Route Reflector, large and extended communities.
• Operational visibility -- Prometheus metrics, BMP export to collectors, MRT TABLE_DUMP_V2 snapshots, birdwatcher-compatible looking glass REST API, structured JSON logging, per-peer counters, best-path explain.
• Evidence-driven correctness -- fuzz targets on the wire decoder, property tests on the FSM, automated containerlab interop against FRR, BIRD, GoBGP, and StayRTR, extensive workspace tests, architecture decision records for every protocol and design choice.
• Reusable wire codec -- rustbgpd-wire has zero internal dependencies and is independently publishable. Anyone building BGP tooling in Rust can use it without the daemon.

Good fit

• DDoS mitigation platforms — FlowSpec + RTBH route injection from automation
• Hosting provider prefix management — API-driven customer prefix announcements
• Internet exchange route servers — transparent mode, Add-Path, RPKI, per-member policy
• SDN / network automation controllers — programmable BGP control plane
• Route collectors and looking glasses — structured data via gRPC, MRT, BMP, birdwatcher-compatible REST API
• Lab and test environments — clean API, structured logs, containerlab interop

See docs/USE_CASES.md for detailed deployment scenarios with architecture diagrams, example configs, and API workflows.

Not the best fit today

• Full general-purpose router deployments requiring FIB integration
• EVPN / VPN datacenter fabric overlays
• Environments that need the breadth of FRR's multi-decade feature surface
• Operators who want a CLI-first operational model

See docs/COMPARISON.md for a detailed feature comparison with FRR, BIRD, GoBGP, and OpenBGPd.

Try it (60 seconds)

The fastest way to see rustbgpd in action. Spins up the daemon with an FRR peer that advertises sample IPv4 and IPv6 prefixes — no real routers needed.

cd examples/docker-compose
docker compose up -d

Once both containers are running (a few seconds):

# See the FRR peer come up
docker compose exec rustbgpd rustbgpctl -s http://127.0.0.1:50051 neighbor

# Browse the RIB
docker compose exec rustbgpd rustbgpctl -s http://127.0.0.1:50051 rib

# Live TUI dashboard — sessions, prefix counts, message rates
docker compose exec rustbgpd rustbgpctl -s http://127.0.0.1:50051 top

Press q to exit the TUI. When you're done: docker compose down.

Install

From source

# Prerequisites: Rust 1.88+, protobuf-compiler
sudo apt-get install -y protobuf-compiler   # Debian/Ubuntu
cargo build --workspace --release

# Binaries are at target/release/rustbgpd and target/release/rustbgpctl

Docker

docker build -t rustbgpd .

Quick start (bare metal)

For running rustbgpd on a real host with real peers.

1. Configure

# Copy and edit the minimal example
cp examples/minimal/config.toml config.toml
$EDITOR config.toml   # set your ASN, router ID, and peer address

The minimal example sets runtime_state_dir to a user-writable path and includes prometheus_addr for metrics. For a route-server deployment, start from examples/route-server/config.toml instead. Full reference: docs/CONFIGURATION.md.

2. Validate and run

# Validate config without starting the daemon
./target/release/rustbgpd --check config.toml

# Preview what a config reload (SIGHUP) would change
./target/release/rustbgpd --diff new-config.toml config.toml

# Start the daemon
./target/release/rustbgpd config.toml

3. Verify

# The minimal example uses /tmp/rustbgpd as state dir, so point the CLI there:
export RUSTBGPD_ADDR=unix:///tmp/rustbgpd/grpc.sock

rustbgpctl health
rustbgpctl neighbor
rustbgpctl rib
rustbgpctl top       # live TUI dashboard

In production with the systemd unit, the default UDS path (/var/lib/rustbgpd/grpc.sock) matches the CLI default — no env var needed.

4. Operate

# Add a peer at runtime (persisted to config file automatically)
rustbgpctl neighbor 10.0.0.5 add --asn 65005

# Explain why a route was selected as best
rustbgpctl rib --prefix 10.0.0.0/24 --explain

# Reload config after editing the file
kill -HUP $(pidof rustbgpd)

# Graceful shutdown (writes GR marker, notifies peers)
rustbgpctl shutdown

# Enable shell completions (bash example)
rustbgpctl completions bash > /etc/bash_completion.d/rustbgpctl
# Or use pre-generated: examples/completions/

gRPC defaults to a local Unix domain socket. For remote access, prefer an mTLS proxy — see examples/envoy-mtls/ and docs/SECURITY.md.

Docker (standalone)

docker run -d --name rustbgpd \
  -v $(pwd)/config.toml:/etc/rustbgpd/config.toml:ro \
  -v rustbgpd-state:/var/lib/rustbgpd \
  -p 179:179 -p 9179:9179 \
  rustbgpd

Or use systemd with examples/systemd/rustbgpd.service.

gRPC API

Seven services cover the full operational surface:

| Service | RPCs | Purpose | |---------|------|---------| | GlobalService | GetGlobal, SetGlobal | Daemon identity and configuration | | NeighborService | AddNeighbor, DeleteNeighbor, ListNeighbors, GetNeighborState, EnableNeighbor, DisableNeighbor, SoftResetIn | Peer lifecycle + inbound soft reset | | PolicyService | ListPolicies, GetPolicy, SetPolicy, DeletePolicy, List/Get/Set/DeleteNeighborSet, Get*Chain, Set*Chain, Clear*Chain | Named policy CRUD, neighbor sets, and global/per-neighbor chain attachment | | PeerGroupService | ListPeerGroups, GetPeerGroup, SetPeerGroup, DeletePeerGroup, SetNeighborPeerGroup, ClearNeighborPeerGroup | Peer-group CRUD and neighbor membership assignment | | RibService | ListReceivedRoutes, ListBestRoutes, ListAdvertisedRoutes, ExplainAdvertisedRoute, ExplainBestPath, ListFlowSpecRoutes, WatchRoutes | RIB queries, explain, and streaming | | InjectionService | AddPath, DeletePath, AddFlowSpec, DeleteFlowSpec | Programmatic route and FlowSpec injection | | ControlService | GetHealth, GetMetrics, Shutdown, TriggerMrtDump | Health, metrics, lifecycle, MRT dumps |

# Stream route changes in real time over the default UDS listener
grpcurl -plaintext -unix /var/lib/rustbgpd/grpc.sock \
  -import-path . -proto proto/rustbgpd.proto \
  rustbgpd.v1.RibService/WatchRoutes

Full API reference: docs/API.md

Design choices

rustbgpd is intentionally built around:

• gRPC-driven control instead of a large interactive CLI surface
• A pure FSM crate with no I/O -- (State, Event) -> (State, Vec<Action>)
• Single-owner routing state instead of shared mutable state across tasks
• Bounded channels for all inter-task communication -- backpressure, not locks
• Explicit protocol feature boundaries with ADRs and test-backed development

Designed around an API-first operating model similar to GoBGP, with a smaller and more explicit internal architecture.

Deployment examples

| Example | Description | |---------|-------------| | examples/docker-compose/ | Quick-start with Docker Compose — rustbgpd + FRR peer with sample routes | | examples/minimal/ | Smallest working config — single eBGP peer | | examples/route-server/ | IXP route server with RPKI, Add-Path, policy chains | | examples/ddos-mitigation/ | FlowSpec + RTBH for automated DDoS mitigation | | examples/hosting-provider/ | iBGP route injector for customer prefix management | | examples/route-collector/ | Passive collector with MRT dumps and BMP export | | [`example