xk6-bgp

k6 extension for BGP benchmarking

xk6-bgp drives real BGP sessions against a target BGP daemon (FRR, GoBGP, RustyBGP, …). Establish sessions, advertise and withdraw prefixes, and measure how fast the daemon delivers UPDATEs end-to-end — all from a k6 script.

A minimal UPDATE delivery scenario: one Peer advertises prefixes, another Peer (which the DUT reflects to) waits for them and emits bgp_prefix_received_duration.

import bgp from 'k6/x/bgp';

export const options = { vus: 1, iterations: 1 };

export default function () {
  const sender = new bgp.Peer({
    localAs:  65001,
    peerAs:   65000,
    routerId: '10.0.0.1',
    target:   __ENV.TARGET,
    families: ['ipv4-unicast'],
    tags:     { peer: 'sender' },
  });
  const receiver = new bgp.Peer({
    localAs:  65002,
    peerAs:   65000,
    routerId: '10.0.0.2',
    target:   __ENV.TARGET,
    families: ['ipv4-unicast'],
    tags:     { peer: 'receiver' },
  });

  receiver.open();
  sender.open();

  const routes = [];
  for (let i = 0; i < 1000; i++) routes.push(`10.99.${i >> 8}.${i & 0xff}/32`);

  const adv = sender.advertise({
    family:  'ipv4-unicast',
    nextHop: '10.0.0.1',
    localAs: 65001,
    routes,
  });

  try {
    const res = receiver.waitForPrefixes({
      prefixes:     routes,
      timeout:      '10s',
      sentAtMonoNs: adv.sentAtMonoNs,
    });
    console.log(`received: matched=${res.matched}`);
  } catch (e) {
    console.error(`waitForPrefixes: ${e}`);
  }

  receiver.close();
  sender.close();
}

./k6 run -e TARGET=10.0.0.99:179 examples/ipv4_unicast.js

The examples directory contains scripts demonstrating various scenarios:

• smoke.js — minimal one-peer advertise/withdraw smoke test
• ipv4_unicast.js — IPv4-unicast UPDATE delivery between two Peers
• ipv6_unicast.js — IPv6-unicast variant
• ipv4_addpath.js — RFC 7911 ADD-PATH delivery of multiple paths per prefix
• mup.js — ipv4-mup advertise of all four MUP route types
• srv6_l3vpn.js — l3vpn-ipv4 advertise with RT + SRv6 L3 Service TLV (End.DT4 SID)
• route_refresh.js — RFC 2918 ROUTE-REFRESH with RFC 7313 EoRR-demarcated replay measurement
• throughput.js — single-peer advertise throughput sweep over COUNT prefixes
• multi_peer.js — many-peer benchmark
• session_up.js — OPEN → Established scaling under many concurrent peers

For local smoke without a real BGP daemon, see cmd/fakebgpd — a minimal reflector bundled for end-to-end tests.

Each Peer represents one BGP session over TCP/179. A typical flow:

• peer.open() — TCP-connect, send OPEN, exchange capabilities, reach Established. Returns { sessionUpUs } with the OpenSent → Established duration in microseconds, the same value pushed to the bgp_session_up metric.
• peer.advertise({...}) / peer.withdraw({...}) — send MP_REACH / MP_UNREACH UPDATEs (auto-chunked to fit BGP_MAX_MESSAGE_LENGTH, or the RFC 8654 ceiling when both sides negotiated Extended Messages).
• peer.waitForPrefixes({...}) — block until the expected prefixes arrive on this Peer or the timeout fires (throws on timeout).
• peer.close() — send Cease NOTIFICATION and tear the session down.

A Peer is single-use. Calling open() again after close() throws "Peer is single-use; construct a new bgp.Peer to reconnect". Construct a new bgp.Peer instance per iteration when you need a fresh session.

Negotiated by default in OPEN:

• MP-BGP for the declared families
• Extended Messages (RFC 8654)
• Route Refresh (RFC 2918)
• Graceful Restart with N-bit (RFC 4724 + RFC 8538)
• 4-octet AS (RFC 6793)

Opt-in via capabilities:

• Enhanced Route Refresh (RFC 7313) — enhancedRouteRefresh: true. When both sides advertise it, inbound BoRR/EoRR demarcations are recognized and peer.waitForRouteRefreshEnd can measure a refresh replay end-to-end (see docs/route_refresh.md).
• ADD-PATH (RFC 7911) — addPath: { '<family>': 'receive' | 'send' | 'both' } per family. Each direction takes effect only when the peer advertised the matching opposite direction. With receive negotiated, observed-set keys become "<prefix>:<pathId>" for that family (see waitForPrefixes); with send negotiated, routes may carry a pathId (routes without one go out as Path Identifier 0), and a pathId on a session that did not negotiate send is an error.

When a peer does not advertise the 4-octet AS capability, xk6-bgp follows RFC 6793 § 4.2.2: AS_PATH is sent with 2-octet AS numbers (a non-mappable local AS becomes AS_TRANS with the real value in AS4_PATH), and received 2-octet AS_PATHs are decoded accordingly.

The JS API is synchronous: each Peer method blocks the calling VU until the underlying I/O completes. BGP benchmark scripts run sequentially per VU (open → advertise → wait → close), so this matches the natural shape of every example here. k6 runs each VU on its own goroutine, so blocking in one VU does not block others.

bgp.barrier(name, count) is a process-wide barrier shared across VUs. Call .arrive() before timing-sensitive sections (e.g. wait for all VUs to reach Established before any of them advertises) so that the benchmark measures the steady-state throughput rather than ramp-up artifacts. Barriers are single-use — pick a fresh name per rendezvous if a script needs to barrier multiple times.

.arrive(timeout) takes an optional timeout (k6 duration string or seconds number) and throws when it elapses. Always pass one in scripts where a VU can fail before its arrive() (a failed open(), typically) — without a timeout the remaining VUs block until the scenario's maxDuration. A timed-out arrival still counts toward count, so one aborted VU does not wedge the rest a second time.

The Trend metrics carry microsecond samples. They don't end in _us (k6 convention is to document the unit in the metric table rather than embed it in the name). BGP delivery latencies are typically sub-millisecond, so storing them as ms would round many samples to 0.

Default tags: plane=control, peer=<tags.peer from JS, if set>. You can attach additional tags via the tags option on the Peer constructor.

Under k6's Prometheus remote-write output, names are prefixed with k6_ and Counters get a _total suffix appended, so the metrics above show up as k6_bgp_session_up_*, k6_bgp_prefix_received_duration_*, k6_bgp_route_refresh_duration_*, k6_bgp_prefix_sent_total, k6_bgp_prefix_received_total in Prometheus.

The xk6 build tool builds a k6 binary that includes the xk6-bgp extension:

go install go.k6.io/xk6/cmd/xk6@latest
xk6 build --with github.com/higebu/xk6-bgp@v0.1.0

The minimum Go toolchain is the one k6 itself requires (currently Go 1.25, dictated by go.k6.io/k6 v1.7). xk6 will tell you if your local toolchain is too old.

To track the development branch instead of a release, replace @v0.1.0 with @latest (master HEAD) or a specific commit hash. master may be broken at any time. The version reported by bgp.version is read from the module's embedded build info; override it at build time via GOFLAGS:

GOFLAGS='-ldflags=-X github.com/higebu/xk6-bgp.Version=v0.1.0-local' \
  xk6 build --with github.com/higebu/xk6-bgp@latest

Issues and pull requests are welcome. Commit messages follow Conventional Commits — see CLAUDE.md. The commitlint GitHub Action enforces the format on PR commits. Run the local lint with:

golangci-lint run ./...

Licensed under the Apache License, Version 2.0.