Skip to main content

Datapath map inventory

Read-only view of what Netra intends to keep in its BPF maps under /sys/fs/bpf/netra.

This is the controller desired state that every netra-agent reconciles into pinned maps. It answers “what deny/allow/rate/policy entries are configured right now?” without requiring node SSH or bpftool.

It is not a raw dump of kernel map memory. Observability maps that the agent reads for counters (flows, TCP health, TLS SNI stats, …) are not listed here — only control-plane inventory (rules the operator can stage).

Quick start​

netractl ebpf maps # human-readable board
netractl ebpf maps --json # same payload as the API
GET /api/v1/ebpf/maps
Authorization: Bearer <NETRA_API_KEY>

MCP (read-only): netra_ebpf_maps → same JSON as the API. Resource: netra://ebpf/maps. Console: #page=ebpf-maps (web/src/pages/EbpfMaps.tsx).

What you see​

FieldMeaning
modeFast-path mode (observe / enforce)
revisionConfig generation agents sync against
pinRootAlways /sys/fs/bpf/netra
filledMaps / emptyMaps / totalEntriesRollup across inventory families
maps[]One object per logical map family

Each maps[] entry:

FieldMeaning
idStable inventory id (blocked_v4, rate, …)
titleOperator label
groupdeny · allow · rate · syn-drop · capability · policy · scope
bpfMapPin name(s) under the pin root (may be v4/v6 pair)
count / limitLive size vs compile-time max_entries
entriesHuman strings (IPs, CIDR (direction), TCP/443 (egress), …), capped at 200

Human board layout​

Netra datapath maps (controller view)
Mode observe · revision 21 · pin /sys/fs/bpf/netra
…

2 filled · 23 empty · 2 total entries

DENY
Deny IPv4 (egress) [blocked_v4] 1/4096
· 203.0.113.9
Deny DNS name [blocked_dns] 1/4096
· evil.example

Empty maps (23): allowed_v4, blocked_ports, …

Filled groups print first; empty pins are summarized at the bottom so capacity is visible without drowning the board.

Map families covered​

GroupInventory idsBPF pins (typical)
Denyblocked_v4/v6, blocked_ingress_v4/v6, blocked_cidr, blocked_ports, blocked_uids, blocked_dns, blocked_sni, blocked_commsblocked_*
Allowallowed_v4/v6, allowed_cidr, allowed_ports, allowed_uids, allowed_commsallowed_*
Raterate, conn_rate_limitsrate_v4/v6, conn_rate_limits
SYN-dropsyndrop, syndrop_cidrsyndrop_* (flags on existing denies)
Capabilitycapgatecapgate_pids (via deniedCapabilities)
Policynetpol_deny, netpol_rules, netpol_defaultnetpol_*
Scopescopescope_mode + enforced_cgroups

Limits match bpf/netra_tc.c max_entries (also exposed on GET /api/v1/ebpf/capabilities → limits). Raising a limit requires a BPF rebuild and agent roll — not a runtime knob.

How this differs from nearby commands​

Command / APIReturns entries?Purpose
ebpf maps / GET /api/v1/ebpf/mapsYes (inventory)Operator-readable desired contents
ebpf census / GET /api/v1/ebpf/censusNo (counts only)Compact deny/allow sizes
ebpf scope show / GET /api/v1/ebpf/configRaw config JSONFull wire shape agents poll
ebpf rules listDurable rule IDsEdit/history/rollback by stable id
ebpf coveragePrograms / missing pinsNode health — not entry lists
bpftool map dump on the nodeKernel memoryBreak-glass; not what CI/operators use day-to-day

Observe vs enforce​

Maps stay populated in observe mode; verdicts stay allow until a leased enforce period. Inventory is therefore useful before flipping mode: stage rules, review ebpf maps, then ebpf mode enforce 15m.

Privacy and safety​

  • Read-only. No mutate path on this endpoint or CLI.
  • No application payloads, argv/cmdline, or Secret contents.
  • Entries are the same metadata already stored in controller state (IPs, CIDRs, DNS names, SNI, ports, UIDs, process comm, selectors).
  • Not a substitute for node-local forensics when pins are missing — use ebpf coverage / netra-doctor for pin health.

Implementation​

  • Builder: internal/ebpfmaps
  • API: GET /api/v1/ebpf/maps (internal/api)
  • CLI: netractl ebpf maps [--json] (cmd/netractl/maps.go)
  • MCP: netra_ebpf_maps
  • Catalog / CI: included in cmd/netractl/commands_catalog.go