Skip to content
ruhexPublic

About

BGPLite — lightweight BGP route server with community-based filtering and HTTP management API.

Resources

Contributing

Stars

26 stars

Watchers

0 watching

Forks

Latest commit

 

History

398 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BGPLite

A BGP-4 route server for dynamic prefix provisioning. Peers register through an HTTP management API, subscribe to AS-lists, country lists, or custom prefixes, and receive them over eBGP. Prefix data comes from RIPEstat and pluggable file/HTTP sources.

BGPLite is not a router: it announces curated prefix sets, it does not forward transit traffic or maintain a full RIB/FIB. The BGP stack (wire codec, session FSM) is implemented in C# directly against RFC 4271, without BIRD/FRR/GoBGP.

Production deployment: bgp.vhex.dev.

CI CodeQL Release Docker .NET License: MIT

Features

Protocol:

  • BGP-4 messages: OPEN / UPDATE / KEEPALIVE / NOTIFICATION; route refresh (RFC 2918, capability-gated, rate-limited)
  • 4-octet ASN (RFC 6793): AS_TRANS, AS4_PATH/AS4_AGGREGATOR tunneling for 2-octet-only peers
  • Capability negotiation (RFC 5492); Graceful Restart (RFC 4724): not advertised, receiving-side retention not implemented (D6/#318)
  • Optional TCP-MD5 session authentication (RFC 2385): set an md5Password on a peer (Linux only — keyed by the peer's source IP; other platforms reject the password with HTTP 400 instead of reporting a tcpMd5 flag that never engages)
  • Communities (RFC 1997) and Large Communities (RFC 8092): per-peer tagging and outgoing filters
  • UPDATE batching (≤100 NLRI) and exact-union CIDR aggregation

Prefix provisioning:

  • Provider factory: http (any raw-file URL), file, and RIPEstat (stat.ripe.net), all with in-memory TTL caching and stale-on-failure
  • Per-source HTTP timeout and custom headers; extensible via IPrefixSourceProvider
  • Subscriptions by AS-list or country, custom prefixes, custom ASNs, per-peer user URL sources

Operations:

  • HTTP management API for peer/route/session management
  • SQLite peer store via EF Core (migrations: dotnet ef migrations add <Name> --project BGPLite.Api)
  • Docker image on GHCR; self-contained binaries (linux-x64/arm64, win-x64); automated Conventional-Commits releases

Architecture

  operator ──HTTP──► Management API (ApiPort, default 5001) + SQLite peer store
                          │ subscription
  BGP peer ──TCP/179──► BgpServer/BgpSession (FSM, timers)
                          │ resolves per-peer route set
                          ▼
                 Providers (RIPEstat / file / http, TTL cache)
                          │
                 Routing (RouteTable, aggregation, community filter)
                          ▼
                 advertise prefixes via UPDATE

Eight projects with enforced one-directional layering — the dependency matrix, layer responsibilities, and data flow are documented in docs/ARCHITECTURE.md.

Quick start

Port 179 is privileged: binding needs root or CAP_NET_BIND_SERVICE on Linux. The Docker compose example uses host networking for that reason.

Docker

docker pull ghcr.io/ruhex/bgplite:latest

cp appsettings.Example.yml appsettings.yml   # edit before running; secrets stay outside the image
docker run -d --name bgplite \
  --network host \
  -v "$PWD/appsettings.yml:/app/appsettings.yml:ro" \
  -v "$PWD/data:/app/data" \
  ghcr.io/ruhex/bgplite:latest

Or with the bundled docker-compose.yml:

cp appsettings.Example.yml appsettings.yml
docker compose up -d

Prebuilt binary

Self-contained single-file binaries are on the releases page:

tar xzf bgplite-v1.0.0-linux-x64.tar.gz
cp appsettings.Example.yml appsettings.yml
sudo ./BGPLite                                # port 179 needs root

From source

git clone https://github.com/ruhex/BGPLite && cd BGPLite
cp appsettings.Example.yml appsettings.yml   # then edit
sudo dotnet run --project BGPLite -c Release

Requires the .NET 10 SDK (global.json pins the version).

Configuration

BGPLite reads appsettings.yml. The full schema is in appsettings.Example.yml; highlights:

Bgp:
  Asn: 65444
  RouterId: 10.0.0.1
  KeepAlive: 60
  HoldTime: 180

# Peers are NOT configured here. There is no peer allow-list: any peer that completes an
# OPEN is registered automatically and gets the default prefix set (see D11 in
# docs/DESIGN_DECISIONS.md). Manage peers over the API instead:
#   curl -X POST http://127.0.0.1:5001/api/peers -H 'Content-Type: application/json' \
#        -d '{"ip":"10.0.0.2","asn":65001,"lists":["ru"]}'

RipeStat:                      # ASN → prefixes via stat.ripe.net (cached, retried)
  TimeoutSeconds: 180
  RetryAttempts: 2

PrefixSources:                 # provider factory (Kind: file | http), in-memory TTL cache
  - Kind: http
    Name: ru
    Url: "https://raw.githubusercontent.com/<org>/<repo>/main/ru.txt"
    Timeout: 30
  - Kind: file
    Name: local
    Path: extra.txt
    Community: "65444:100"

DefaultPrefixSource: ru        # served to unconfigured/auto-registered peers
  • Prefix list files: one CIDR per line (2.16.20.0/23); blank lines and # comments ignored.
  • Peer data lives in SQLite at $BGPLITE_DATA/bgplite.db (defaults to ./data).

How it works

  1. A peer is registered via POST /api/peers (IP, ASN, AS-list subscriptions and/or custom prefixes).
  2. The peer connects over BGP to port 179.
  3. On session establishment the server resolves the peer's subscription:
    • known peer — fetches prefixes for its subscriptions (cached) plus custom prefixes and advertises them; a custom prefix overrides the source prefixes it covers: covered more-specifics are not sent (#220);
    • unknown peer — auto-registers it and advertises the default prefix source.
  4. Session history is stored; live peer status is projected from Established sessions.

Management API

Listens on ApiPort (default 5001, loopback by default).

Peers are addressed by the opaque id returned on create (a peer is keyed by IP and remote ASN, so two peers behind one source IP are distinct rows).

Method Endpoint Description
GET /api/server Server identity and effective settings
GET /api/me The caller's IP plus the peers seen at it (all of them, or one with ?asn=)
POST /api/peers Register a peer
GET /api/peers/{id} Peer detail by ID; no caller scoping — use an authenticated reverse proxy
PUT /api/peers/{id} Partial update — an omitted field is left unchanged
DELETE /api/peers/{id} Delete the peer and tear down its session
GET /api/peers/{id}/prefixes Full outbound pipeline; plain text by default, ?format=json for an array. Source failure/budget expiry returns 503 without a partial list
GET /api/peers/{id}/sources List the peer's own URL prefix sources
POST /api/peers/{id}/sources Add a URL prefix source
DELETE /api/peers/{id}/sources/{sourceId} Remove a source
PATCH /api/peers/{id}/sources/{sourceId} Pause / resume a source (body is {"active": bool})
GET /api/asn-lists Available AS-lists with prefix counts
GET /api/community-scheme The community naming scheme in use
GET /api/sessions Active BGP session count
GET /api/routes Route counts by community
GET /api/as/{asn}/prefixes ?count=true returns the prefix count; without it, a hint message

All mutating routes refuse Sec-Fetch-Site: cross-site. The routes that carry a body also require Content-Type: application/json, which forces the CORS preflight that keeps cross-origin callers out.

curl -X POST http://localhost:5001/api/peers -H 'Content-Type: application/json' -d '{
  "ip": "10.0.0.2", "asn": 65001, "description": "customer-1",
  "lists": ["ru"], "customPrefixes": ["203.0.113.0/24"]
}'

RFC compliance

A section-by-section audit lives in docs/RFC_COMPLIANCE.md. Summary:

RFC Topic Status
4271 BGP-4 (base) core implemented
4893 / 6793 4-byte ASN, AS4_PATH implemented
5492 Capabilities implemented
1997 Communities implemented
4724 Graceful Restart not advertised; receiving-side retention open (#318, D6)
2918 Route Refresh implemented
2385 TCP-MD5 auth implemented on Linux; lifecycle follow-ups #555/#561
4760 / 2545 MP-BGP / IPv6 IPv4/IPv6 unicast implemented; policy follow-up #566

Known deliberate deviations are catalogued in docs/DESIGN_DECISIONS.md.

Roadmap

Work is tracked in issues, including protocol, provisioning, and lifecycle follow-ups linked from the status table above.

Contributing

See CONTRIBUTING.md for the branch model, commit conventions, and PR expectations. CI runs build, tests, dotnet format, and CodeQL on every PR; CodeRabbit posts an automated RFC-aware review.

License

MIT © Mikhail Movchan

About

BGPLite — lightweight BGP route server with community-based filtering and HTTP management API.

Resources

Contributing

Stars

26 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages