Sam 05f723556e docs+tooling: land the deploy bundle docs, portproxy script, checkout pinning

deploy.sh referenced DEPLOYMENT-TYPES.md and router-bmp-config.md, which were
never committed (they lived only in a chat session's outputs). Land them under
docs/ along with PORTABILITY-FINDINGS.md covering all 12 greenfield findings,
including the two from today's deploy (chmod-777-vs-psql, telegraf docker API)
and the open router-side gap (cml tooling still targets HOST_IP:5000).

- scripts/wsl-portproxy.ps1: idempotent elevated-PS helper for the Windows
  portproxy + firewall rules; auto-detects the current WSL IP. Replaces the
  copy-paste netsh block as the primary path (raw commands kept as fallback).
- deploy.sh: plan now prints the branch @ commit (+dirty marker) so every
  deploy records exactly what it ran from; doc references point at docs/.
- README: greenfield quickstart with pinned-checkout guidance; warning on the
  manual chmod path that breaks existing Postgres trees (finding 10).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-20 16:02:36 -07:00

3.7 KiB

Raw Blame History

Router BMP configuration (IOS-XR)

How to point routers at the OpenBMP collector, and which address/port they must target depending on where the stack runs. Companion automation: cml/proxmox_bmp_config.py (applies the block below over SSH to the Proxmox lab routers) and cml/xrd-node-definition.yaml (bakes it into XRd images).

What address do routers target?

Never HOST_IP on a WSL deployment. HOST_IP is the WSL VM's NAT address — unreachable from physical routers and changed by wsl --shutdown. deploy.sh records the correct target in .env as ROUTER_FACING_IP / ROUTER_FACING_PORT:

Stack host	Routers target	Path to the collector
Native Linux	`ROUTER_FACING_IP` (= host IP) : `ROUTER_FACING_PORT`	compose port map -> collector :5000
WSL2	Windows LAN IP : `ROUTER_FACING_PORT`	`netsh portproxy` (Windows) -> WSL `HOST_IP` -> collector :5000

On WSL the Windows-side forwarding must exist first — run scripts/wsl-portproxy.ps1 in an elevated PowerShell, and re-run it after every WSL restart (the WSL address changes).

The router-facing port defaults to 1790 (the IANA-registered BMP port); the collector always listens on 5000 inside the container. The lab routers were historically configured for 5000 — until they are reconfigured, deploy with --router-port 5000 (see the open decision in docs/PORTABILITY-FINDINGS.md, finding 12).

`bmp server` block

Flat formal form (submode-free, safe to paste line-by-line at (config)# — the form proxmox_bmp_config.py applies):

bmp server 1 host <ROUTER_FACING_IP> port <ROUTER_FACING_PORT>
bmp server 1 description OpenBMP-Collector
bmp server 1 update-source MgmtEth0/RP0/CPU0/0
bmp server 1 initial-delay 60
bmp server 1 stats-reporting-period 300
bmp server 1 initial-refresh delay 60 spread 30

The initial-refresh delay/spread staggering matters at scale: it spreads the full-RIB dumps out when many routers (re)connect at once, which is the burst that sizes the whole store tier (docs/DEPLOYMENT-TYPES.md).

Activating monitoring on BGP sessions

BMP only reports sessions that are bmp-activated:

router bgp <ASN>
 neighbor-group RR-CLIENTS
  bmp-activate server 1
 !
!

Monitor on the RRs, pre-policy, not on every client session. In an RR topology the same full table is reflected to every client; activating BMP on all reflected sessions makes the collector ingest full-table x sessions copies simultaneously. Activating on the RR side only is the single biggest load reduction available.

Verification

Router side:

show bgp bmp server 1        ! state should be ESTAB, uptime climbing
show bgp bmp summary

Collector side:

docker logs obmp-collector --tail 20        # look for ROUTER_INIT / PEER_UP
docker exec -i obmp-psql psql -U openbmp -d openbmp \
  -c "SELECT name, ip_address, bgp_id, isconnected FROM routers ORDER BY name;"

Grafana: the OBMP-Operations / Inventory and Peer Detail dashboards populate within a minute of the first PEER_UP; RIB contents follow as the initial dump is consumed (large tables take longer — watch the OBMP-Telemetry / Kafka Lag dashboard drain).

Troubleshooting

Session cycles ESTAB -> idle: the collector accepted TCP but the pipeline is backpressured (Postgres write latency) — check the stack dashboards, not the router.
No TCP at all from a WSL deployment: portproxy rule missing/stale (re-run scripts/wsl-portproxy.ps1), or Windows firewall lacks the inbound allow for the router-facing port.
Router config rejected: IOS-XR BMP config is not in the NETCONF YANG schema on the lab release — apply via SSH CLI (which is why proxmox_bmp_config.py drives the CLI).

3.7 KiB Raw Blame History