Packeteer

Packeteer

Open-source BGP path performance controller for multi-homed networks. One container, a mounted config file, and the edge router you already run.

Packeteer sits off to the side of the edge. It probes each upstream from that upstream's source address, scores loss, latency, and jitter, and learns today's exit from iBGP. In the default mode it only reports. If you later turn injection on, it advertises a better exit back to the edge for prefixes you allowlisted. If Packeteer stops, those routes go away and the router's own BGP decision stands.

The feature matrix is docs/FEATURES.md.

Safety model

Read this before you change mode.

• The default mode is observe. The file in this repository stays observe. suggest probes and recommends, and announces nothing.
• inject is a separate config: mode: inject, a non-empty allowlist, packeteer_community, local_pref, a positive hold_time, positive loss and latency thresholds, an iBGP neighbor, and announcer.type: gobgp.
• Packeteer announces a prefix only when that exact prefix is in the RIB it learned from the router. It does not invent a more-specific. A config that sets more_specific_bits is rejected. The optional more_specific block (off by default) also announces the more-specifics a neighbor already advertises inside an improvement's prefix, under a route cap (design).
• Active improvements are capped (max_improvements, default 50).
• A new improvement waits for a real gain (the thresholds) and then stays up for at least hold_time.
• Every injected route carries your community and the well-known no-export community. The edge must accept only that community from Packeteer, and must reject it on every eBGP session. no-export is the second layer.
• Packeteer withdraws its routes on shutdown, when a probe source dies, when measurements go stale (including when a probe round never finishes), when every iBGP session drops, and when a prefix the router was still advertising leaves the RIB. Graceful restart is never enabled. A kill is covered by the BGP hold timer (Packeteer proposes 90 seconds; a shorter timer from the router wins).
• This repository uses documentation prefixes (RFC 5737, RFC 3849) and the private ASN 64512. Keep real prefixes and real ASNs out of commits, issues, and logs you paste in public.

Threat model: docs/THREAT_MODEL.md. Agent rules: AGENTS.md.

Install

The image is ghcr.io/grandarcher/packeteer, linux/amd64 and linux/arm64. It runs as root inside the container so it can open raw ICMP sockets and, if you ask it to, TCP port 179. Give it NET_RAW and NET_ADMIN. It needs host networking: probes must leave from each provider's source address, the iBGP session must reach the router, and a flow collector binds host UDP ports.

Step by step: docs/quickstart.md. It goes from an empty directory to a running instance in observe, with a first run on loopback, docker run and Compose, and the stop. CI runs every command on that page against the image built from the same commit.

The short version, pinned to 0.7.0. Take the example config from the same tag as the image: the file on main can carry keys a release does not know yet, and unknown keys refuse startup. For :edge, use main in both places.

IMAGE=ghcr.io/grandarcher/packeteer:0.7.0
curl -fsSLo config.yaml https://raw.githubusercontent.com/GrandArcher/Packeteer/v0.7.0/config.example.yaml
# Edit providers and source IPs. Leave mode: observe.
mkdir -p plugins

docker run --rm \
  -v "$PWD/config.yaml:/etc/packeteer/config.yaml:ro" \
  "$IMAGE" -check

docker run -d --name packeteer --network host \
  --cap-add NET_RAW --cap-add NET_ADMIN \
  --restart unless-stopped \
  -v "$PWD/config.yaml:/etc/packeteer/config.yaml:ro" \
  -v "$PWD/plugins:/etc/packeteer/plugins:ro" \
  -v packeteer-data:/var/lib/packeteer \
  "$IMAGE"

-check prints mode: observe and check: ok (no probes sent, no BGP sessions opened). The image does not contain your config. It does contain the example at /etc/packeteer/config.example.yaml:

docker run --rm -e PACKETEER_CONFIG=/etc/packeteer/config.example.yaml \
  ghcr.io/grandarcher/packeteer:0.7.0 -check

The default config path inside the container is /etc/packeteer/config.yaml (PACKETEER_CONFIG, or -config).

Without NET_RAW, or where ICMP is filtered, the probe falls back to TCP port 443 (the log shows prober=tcp). The settings form, setup wizard, and config editor in the dashboard stay off until you set http.config_editor: true and turn on auth or basic auth (docs/ui.md, docs/auth.md). Every environment variable: docs/ENV.md.

The packeteer-data volume keeps report history (storage: {type: sqlite}, file /var/lib/packeteer/packeteer.db) across container restarts and upgrades, and the open billing period of SNMP 95th-percentile samples when telemetry is configured. Without the volume, reports and that window start empty after the container is recreated. Leave out storage to turn history off; the probe and decision loop does not depend on it, and the 95th window then lives in memory only.

docker-compose.yml runs the same container with Compose: host networking, the two capabilities, the mounts, and restart: unless-stopped (quickstart, step 5). Its image line uses :edge; change it to ghcr.io/grandarcher/packeteer:0.7.0 to pin. There is no ports: map: with host networking, http.listen is already an address on the host. Stop with docker compose stop -t 30 (see Rollback).

Minimum config

The smallest file that validates, probes, and serves the dashboard is below. Addresses are documentation ranges. Replace source_ip and next_hop with addresses that exist on your host and on your transits. Leave mode: observe.

mode: observe
asn: 64512
router_id: 192.0.2.10
providers:
  - name: transit-a
    source_ip: 192.0.2.11
    next_hop: 192.0.2.1
  - name: transit-b
    source_ip: 192.0.2.12
    next_hop: 192.0.2.2
probe:
  interval: 30s
  timeout: 2s
  packets: 10
sources:
  - type: static
    config:
      targets:
        - prefix: 198.51.100.0/24
          host: 198.51.100.1
http:
  listen: "127.0.0.1:8080"

One provider passes validation. Two is the useful case: Packeteer compares the same destination out of each. The file above omits thresholds, so both deltas stay 0 and no improvement is recorded. config.example.yaml sets min_loss_delta_pct: 1 and min_rtt_delta_ms: 15 and comments the rest of the keys.

Every key, default, and bound is in docs/CONFIG.md.

Host policy routing

A probe toward a destination is sent with that provider's source_ip. The host routing table has to send packets from that address out of the matching transit. Otherwise every provider measures the same path. If source_ip is not configured on the host, that provider is marked down and left out.

The container uses --network host, so the rules live on the host. Full steps, reverse-path filtering, IPv6, and the MikroTik equivalent: docs/policy-routing.md. The addresses in that guide are a separate subnet per transit. The minimum config above uses one documentation subnet so the YAML stays short; on a real host, source_ip and next_hop have to be the addresses in the rules.

ip addr add 192.0.2.11/24 dev eth1
ip addr add 198.51.100.11/24 dev eth2
echo "101 transit-a" >> /etc/iproute2/rt_tables
echo "102 transit-b" >> /etc/iproute2/rt_tables
ip route add default via 192.0.2.1 dev eth1 table transit-a
ip route add default via 198.51.100.1 dev eth2 table transit-b
ip rule add from 192.0.2.11 lookup transit-a priority 1001
ip rule add from 198.51.100.11 lookup transit-b priority 1002
ip route get 203.0.113.1 from 192.0.2.11
ip route get 203.0.113.1 from 198.51.100.11

Use the source_ip and next_hop values from your config. Make the rules persistent with the host's network config. On the probe interfaces, loose reverse-path filtering avoids dropping replies that arrive on a different interface than the default route:

sysctl -w net.ipv4.conf.all.rp_filter=2

Router setup

You can run observe with no BGP session. Packeteer then ranks paths and does not know which exit the router uses, so it will not recommend a move.

To learn current exits, peer iBGP, same ASN, between the router and Packeteer. In observe and suggest, Packeteer announces nothing on that session. Before inject, install both filters:

1. From Packeteer, accept only routes that carry packeteer_community.
2. Toward every eBGP neighbor, reject that community.

Leave graceful restart off on the session. Guides:

• docs/walkthrough.md — observe, suggest, inject, and roll back on a simulated FRR edge, then the same steps on a real one. CI runs every command
• docs/mikrotik.md — RouterOS 7 iBGP, filters, Traffic Flow, port mirroring, and SNMP
• docs/frr.md — FRR; the walkthrough lab runs this configuration in CI
• docs/junos.md — Juniper Junos
• docs/cisco.md — Cisco IOS and IOS-XE
• docs/routers.md — what every router guide shares, what happens when the native path disappears, and exchange peers
• docs/route-reflector.md — several edge routers, per-router provider reachability, route reflectors, Internet exchange peers, and SIGHUP reload of neighbors, thresholds, policies, and sources
• docs/multi-pop.md — several POPs (routing domains) federated over mutual TLS: inter-DC RTT in the path cost, global commit across POPs, and the central view. Lab-proven only
• docs/leak-watch.md — how Packeteer keeps its routes inside your AS: the rails, and leak_watch, which withdraws and holds out a route seen outside the AS. Lab-proven only
• docs/precedence.md — which surface owns a prefix when mitigation, inbound, outbound, a leak hold, flap quarantine, and HA all want it, how the shared cap is spent, and which test proves each pair
• docs/policy-routing.md — probe sources behind the router
• docs/ui.md — config editor and first-run wizard, custom dashboards, email report subscriptions, and improvement weights

A flow export (NetFlow, IPFIX, or sFlow) is optional. It only adds probe targets. It does not inject routes. With host networking the collector's UDP port is a host port; firewall it to the exporter.

Optional probers, target sources, and probe tuning (udp, traceroute, vip, outage, retries, dispersion): docs/operating.md.

Start in observe

1. Mount the minimum config, or config.example.yaml, with mode: observe.
2. docker run ... -check (or go run ./cmd/controller -check -config config.yaml from a checkout).
3. Start the container.
4. Open the dashboard at http://127.0.0.1:8080/ when http.listen is the default. Until the instance is fully set up it shows a setup checklist: what to add to the mounted file next (sources, bgp.neighbors, storage) and what looks broken (a provider whose probes all fail, no iBGP session). Logs show one line per probe (loss_pct, rtt_avg, jitter) and, once a session is up, bgp session state and a periodic rib ready=true.

curl -fsS http://127.0.0.1:8080/healthz
curl -fsS http://127.0.0.1:8080/readyz
curl -fsS http://127.0.0.1:8080/api/providers
curl -fsS http://127.0.0.1:8080/metrics

/healthz stays up while the process is serving. /readyz returns 503 until startup finishes, and until an iBGP session is up when bgp.neighbors is set. No neighbors means ready as soon as startup finishes.

Stay here until the numbers match what you expect from each transit. A probe failed line whose error contains probe source address unavailable means that source_ip is missing on the host or the policy route is wrong. A successful probe with high loss_pct is a measurement of that transit.

Suggest, then inject

mode: suggest recommends and announces nothing. mode: inject needs the allowlist, packeteer_community, local_pref, hold_time, non-zero thresholds, an iBGP neighbor, announcer.type: gobgp, and the router filters from the guides. The full list, what to check on the router, and the lab run: docs/operating.md and docs/walkthrough.md.

Rollback

Stopping the container withdraws every Packeteer route. Give it 30 seconds; Docker's default 10 races the withdraw.

docker stop -t 30 packeteer
# or, from the Compose directory:
docker compose stop -t 30

docker kill does not withdraw: the routes stay until the router's hold timer expires, and the Compose restart policy starts the container again. Switching back to mode: observe and restarting also withdraws. HA pairs, the other automatic withdraws, and the show commands to confirm: docs/operating.md.

Dashboard, API, and metrics

http.listen defaults to 127.0.0.1:8080. Set it to "", or set PACKETEER_HTTP_LISTEN=off, to disable it. Any other value of PACKETEER_HTTP_LISTEN replaces http.listen. The image exposes port 8080 as documentation; with host networking you do not publish it.

The server is read-only (GET and HEAD), except on-demand maintenance windows (POST and DELETE on /api/maintenance), which need basic auth or an operator and can only exclude providers, threat mitigation rules (POST and DELETE on /api/mitigations), which need basic auth or an operator and announce only when mitigation.mode is inject, the troubleshooting tools (POST on /api/troubleshoot/probe, traceroute, and whois), which measure or look up and change nothing, and /api/troubleshoot/optimize, which only queues a learned prefix for measuring, with upgrade.enabled, an admin's confirmed upgrade or rollback of the Packeteer binary (POST on /api/upgrade/check, apply, and rollback; the controller withdraws every route first, docs/ui.md), and, with auth, users and API tokens. Every change is written to the audit log and sent to the notifiers. The dashboard loads no remote assets and refreshes every 5 seconds.

Every endpoint, with its body and the role it needs, is in docs/API.md. Basic auth is off unless both PACKETEER_HTTP_USER and PACKETEER_HTTP_PASSWORD are set. Setting only one refuses to start. Set both when http.listen is not loopback. The password is not read from the config file and is not written to the log.

For more than one person, turn on auth (#32): users with roles (viewer, operator, admin) kept in the storage plugin, API tokens for scripts and Prometheus, an audit log of every change (stored, on /api/audit, and sent to the notifiers as audit.recorded), optional OIDC single sign-on, and http.allow_from to restrict client addresses. The first admin comes from PACKETEER_ADMIN_PASSWORD. Guide: docs/auth.md. Rollback: auth.enabled: false and restart.

The Prometheus metric names are listed in docs/API.md.

Scrape http://127.0.0.1:8080/metrics on the host.

PACKETEER_LOG_LEVEL=debug adds detail. log.format: json or PACKETEER_LOG_FORMAT=json switches the log to JSON.

Plugins

Almost every part of Packeteer is a plugin selected by type in the config. Unknown types and unknown keys inside a plugin config block refuse startup. The built-ins, by kind:

• Probers: icmp, tcp, udp, fixed (labs only).
• Target sources: static, flow (NetFlow, IPFIX, sFlow), traceroute, vip, outage, span (mirror port or pcap; needs NET_RAW).
• Route feeds: rib_source bmp (BMP and add-path from the routers).
• Scorers: weighted (default), commit, cost.
• Policies: rules (ignore, allow, deny, static, or VIP by prefix, origin ASN, or country) and maintenance.
• Announcers: gobgp for outbound, plus the gobgp inbound and mitigation announcers (inbound.md, mitigation.md).
• Notifiers: webhook (JSON, Slack, Teams, PagerDuty, templates), smtp, snmptrap (EVENTS.md).
• Telemetry: snmp and fixed (labs only).
• Storage: sqlite (report history, users, audit log, dashboards).
• Detection and safety: detector baseline (flow anomaly detection, anomaly.md) and leak_source bmp and rislive (leak-watch.md).
• Clusters: elector lease (active/standby, ha.md) and federation mtls (several POPs, multi-pop.md).
• Sign-in and lookups: sso oidc (auth.md) and whois rdap (troubleshooting).

Only the announcers and the plugins that feed route decisions can put a route on the session, and those are compiled in only. An exec plugin is any executable you mount at /etc/packeteer/plugins; it works in the stock image as a prober, a target source, or a notifier, speaking one JSON request and one JSON reply.

Interfaces, the exec protocol, and a shell example: docs/PLUGINS.md. Keys: docs/CONFIG.md.

FAQ

Symptoms, log lines, and fixes: docs/troubleshooting.md.

The container exits immediately. The log line refusing to start is a config or plugin error. Run -check. Unknown YAML keys, a missing provider, and an inject file that omits the allowlist or the community all fail closed.

The dashboard has no prefixes. Add a sources entry. Prefixes that sit only in the RIB are not listed. A failed probe is a source address, a missing NET_RAW, or a filter in the path. ICMP falls back to TCP port 443 when ICMP cannot run.

/readyz stays 503. Neighbors are configured and no session is established. Check ASN, reachability, and whether Packeteer should connect out (listen_port 0) or wait (passive plus listen_port). Filters do not stop the session from coming up; they stop routes.

Nothing is recommended. Thresholds are still 0, the prefix is not in the RIB, the RIB next hop matches no provider, the gain is inside the thresholds (including min_rtt_delta_pct when it is set), confirm_rounds has not been met (confirming in /api/decisions; the default 1 does not wait), or the provider is excluded.

Inject is on and the router shows no route. The prefix is not in the learned RIB, it is outside the allowlist, the cap is full, or the router rejected the community. Packeteer will not announce a prefix it has not learned.

Will a stop leak routes to transit? The route is withdrawn and tagged no-export. The eBGP community filter in the router guides is what you control if no-export is stripped. After docker stop -t 30, the community lookup on the router should be empty.

Can I put my config in this git repo? Keep it on the host you mount into the container. Do not commit real prefixes, ASNs, SNMP communities, or hook tokens.

Features

Status as of v0.7.0, from docs/FEATURES.md:

v0.1 is the outbound loop: probes, static and flow targets, an iBGP RIB, scoring with hysteresis, optional injection, the read-only UI and API, the container, and the FRR lab. v0.2 adds cost and commit control, SNMP, policies, alerts, and reports. v0.3 adds inbound optimization, BMP and add-path, multiple routers and IX, RTBH/FlowSpec mitigation, transit classification, and capped more-specific injection, all lab-proven. v0.4 adds multi-POP federation, active/standby HA and backup, RBAC/SSO/audit, flow-baseline anomaly detection that mitigates only on explicit rules, and the remaining UI rows. v0.5 is hardening on that matrix: dashboard clarity and a first-run checklist, CI-tested install and walkthrough docs, load and soak budgets with a flow-ingest fix, a MikroTik CHR lab in CI, and a scheduled router interop matrix. Those are lab-proven only. Field feedback from real observe-mode deployments (#54) is still open. v0.6 closes the gaps from the 2026-10-07 review of prefix selection, measurement, and the UI, adds flap quarantine, live apply, scale budgets up to multi-million path tables, upgrade from the UI, and a failure-mode e2e matrix; also lab-proven only. v0.7 (this release) adds exchange (IX) visibility: an exchange view, IX LAN health probes, route-server vs bilateral prefix views, transit-to-IX offload and potential-peers reports; plus dashboard widgets, Commit & Cost, Reports, search, System, and maintenance pages, link-outs, steering precedence tests, and a split of the largest Go files. Also lab-proven only. It does not relax the safety rules above.

Upgrades

Pulling a newer image and recreating the container is the plain upgrade. Your config and the packeteer-data volume carry over.

The Settings page can also upgrade in place (#196). It is off by default. It needs upgrade.enabled: true, the release public key in upgrade.public_key (CONFIG.md), an admin login (auth or basic auth), and the packeteer-data volume to keep the new version across restarts. The public key is printed in the v0.6.0 release notes. Every route is withdrawn before the switch, and a release whose signature or checksum does not match is refused. Details: docs/ui.md.

Roadmap and contributing

Questions, ideas, or just want to talk routing? Join the Packeteer Discord.

• What is done, partial, and planned: docs/FEATURES.md and the milestones.
• How to send a change: CONTRIBUTING.md. Safety and doc rules for every change: AGENTS.md.
• Plugin roadmap: out-of-process plugins with state (#286), InfluxDB and OTLP exporters (#287), a plugin author guide and community plugin list (#288), and PeeringDB and IRR record checks (#289).

Bug reports and field reports from observe-mode deployments (#54) are the most useful contribution right now.

Build from source

Go 1.26.

go build -o packeteer ./cmd/controller
./packeteer -check -config config.example.yaml
./packeteer -version
docker build -t packeteer .

go test ./..., go vet ./..., and an empty gofmt -l . are the local bar. BGP behavior is tested against the FRR lab in CI (bash lab/e2e.sh), not against a live edge. See lab/README.md. Memory, CPU, and flow-ingest budgets under a full-table-sized synthetic RIB are in docs/performance.md; CI fails when one regresses.

Layout

cmd/controller/     # entrypoint
internal/httpapi/   # health, metrics, JSON API, embedded dashboard
internal/probe/     # per-provider sourced measurements
internal/policy/    # score + hysteresis
internal/announce/  # inject-mode gate in front of the announcer plugin
internal/rib/       # learn-only iBGP view (embedded GoBGP)
internal/plugins/   # probers, target sources, scorer, announcer, notifier, telemetry
docs/CONFIG.md      # config reference
lab/                # FRR e2e lab (CI job e2e); lab/soak load and soak harness (CI job load)

Support the project

Packeteer is free and open source. If it helps your network, you can chip in to cover development and lab costs through PayPal or the Sponsor button at the top of this page.

License

Apache-2.0. See LICENSE.