Linux host integration and side effects

Network and bridge control

api/network_api.py retains process-wide pyroute2 IPRoute and NDB objects. It reads addresses, link flags, routes and bridge membership through netlink, and uses NDB/pyroute2 to create or remove bridges. Resetting interfaces executes ethtool and changes MTU/profile values. These operations affect the host's live connectivity; API errors must be treated as operational failures, not merely input validation failures.

utilities/interface_bridge_helpers.py is the low-level read layer. It checks interface presence/up state, reads sysfs operational/carrier/admin/MTU values, obtains Ethernet profile data using ethtool, caches profile data, and reads bridge members from sysfs. It deliberately supplies best-effort information when a driver or platform cannot report every property.

bridge_link_state_manager.py owns optional event-driven bridge watchers. Each watcher tracks Ethernet profile and member readiness, uses failure and recovery holdoffs to avoid flapping, and adjusts selected peer state so an inline bridge reacts coherently to member link loss. BridgeLinkStateManager indexes watchers, enables/disables them, reports individual/all status, and stops all during shutdown.

eBPF/tc telemetry

bridge_telemetry.py manages the lifecycle of the telemetry helper. Its update_sessions method reconciles currently requested bridge ports with the subprocess; stop terminates it and get_debug_snapshot provides operator diagnostics. It does not itself parse kernel events.

ebpf_bridge_events.py is the helper process. It builds BPF source, attaches tc programs to requested interfaces, reads perf events, and writes JSON-safe event payloads. Events cover ingress raw capture plus egress/drop metadata, including interfaces, MAC/IP information, packet identity, event/reason names, and timing. It cleans existing clsact qdiscs/program attachment as part of setup/cleanup. This requires an appropriate kernel, BCC Python bindings/toolchain, tc, and privileges.

tools/ebpf/mark_packet_id.c is related kernel-side support for packet marking; the mark is decoded by utilities/packet_mark.py and used in tracker correlation.

nftables

The mounted api/nft_manager.py uses pip-nftables to list JSON/text rulesets, normalize them into stable table/chain/rule models, parse rule priorities/text, and delete a rule by handle. Its raw-command endpoint forwards textual nft commands. It therefore needs capability to inspect and change the host nftables ruleset.

Two alternative implementations exist but are currently unmounted:

api/nft_api.py is bridge-family oriented. It models meta, Ethernet, IP, port, conntrack, verdict, reject, log, and raw expressions; can generate previews, list rules with authoritative handles, add/delete/update rules, and uses the nft CLI.
api/nftables_api.py is a stateless typed replacement API. It models matches and actions, chooses a pyroute2 binding when viable or a CLI wrapper otherwise, ensures table/chain presence, reconstructs readable rules, and replaces a chain's ruleset. Its own source warns that a running asyncio loop may force CLI fallback.

Do not mount more than one firewall router without an explicit API versioning and conflict review: all manipulate shared kernel state and have overlapping concepts.

NFQUEUE script services

api/packet_scripting_api.py manages executable Python scripts. It makes these directories at import time: /srv/fw-scripts, /srv/fw-scripts/venvs, and the repository's backend/example_scripts. Scripts are named <name>.py; requirements are <name>-requirements.txt; virtual environments are per-script. Units use the deterministic name fw-script-<name>-q<queue>.service and are written under /etc/systemd/system.

The module discovers services through systemctl, writes/parses unit ExecStart, runs daemon-reload, starts/stops/enables/disables units, creates virtualenvs, and uses pip to install user-provided requirements. Startup can copy protected example scripts and optionally deploy them from <name>.deploy.json. This API is a remote code/service-management surface and requires strict authentication plus host-level least privilege.

External subprocesses

Integration	Commands/facility	Used by
tshark	long-lived `tshark` subprocesses	DPI enrichment
nftables	`nft` CLI and/or pip-nftables bindings	firewall APIs
Ethernet control	`ethtool`	interface profile/reset
system services	`systemctl`, virtualenv, pip	script lifecycle
BPF/tc	BCC, tc, qdisc/program attachment	bridge telemetry

Failures are generally logged and translated to endpoint failures or degraded capture. Operators should collect /api/sniffer/debug, service logs, nftables state, and interface state when investigating a problem.

4.8 KiB Raw Permalink Blame History