eBPF XDP In-Kernel Ring Buffer Backpressure and Adaptive Drop Standard

--- description: eBPF XDP In-Kernel Ring Buffer Backpressure and Adaptive Drop Standard - Maintains bounded user-space memory and CPU usage by enforcing early in-kernel XDP packet dropping invariants before ring buffers overload during L4 volumetric DDoS events. Systems must check ring-buffer queue availability and watermarks in XDP context, executing an immediate XDP_DROP when backpressure thresholds are breached instead of attempting unmonitored BPF_MAP_TYPE_RINGBUF emissions. globs: src/**/*.{c,h,bpf.c,bpf.h}, kernel/**/*.c, bpf/**/*.c, crates/**/*.rs, pkg/**/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-xdp-ringbuf-backpressure-invariant" --- # eBPF XDP In-Kernel Ring Buffer Backpressure and Adaptive Drop Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unchecked Ring-Buffer Submissions and Unbounded User-Space Channel Ingestion Under Volumetric Floods ## System Constraints You are a Principal Systems Architect enforcing kernel-bypass resilience and eBPF XDP invariant constraints. You must enforce strict ring-buffer headroom validations, per-CPU watermark telemetry, and zero-allocation backpressure drops inside XDP programs to safeguard user-space consumers against catastrophic memory exhaustion and packet queue thrashing during high-volume DDoS attacks. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict watermark checks using atomic availability counters or `bpf_ringbuf_reserve` capacity validation before allocating metadata buffers. - Engineers MUST NOT rely on userspace drain speed or unthrottled `bpf_ringbuf_output` calls during packet processing in the XDP fast-path. - Code SHOULD enforce an exponential decay or adaptive drop window (`XDP_DROP`) immediately upon encountering ring-buffer submission failures to prevent kernel ring-buffer lock contention. - Services MUST maintain bounded memory in user-space by sizing ring-buffer consumers to handle worst-case batch drains using memory-mapped ring pages without intermediate dynamic allocations. - Components NEVER pass uninspected packet telemetry to user-space once ingress packet per second (PPS) crosses the configured mitigation headroom watermark. ## Bad vs Good Implementations ### Unbounded Ring-Buffer Emission vs In-Kernel Backpressure Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The BPF program formats event telemetry and invokes `bpf_ringbuf_output` unconditionally. Under an L4 volumetric flood, user-space cannot drain the buffer fast enough; CPU cycles are wasted preparing telemetry for dropped entries, and user-space memory exhaustion or ring overrun occurs with zero backpressure feedback to ingress. ```c // BAD: Blindly outputs metadata for every packet to ring buffer; // during a 10M PPS SYN flood, ringbuf fills instantly, drops internally, // wastes CPU cycles, and induces userspace memory thrashing. SEC("xdp") int xdp_ingress_telemetry_bad(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; struct eth_hdr *eth = data; if ((void *)(eth + 1) > data_end) return XDP_PASS; struct event_t evt = { .len = (__u32)(data_end - data) }; // Blind output: drops silently inside BPF helper, burns CPU on telemetry formatting bpf_ringbuf_output(&events_ringbuf, &evt, sizeof(evt), 0); return XDP_PASS; } ``` #### Production Standard (Correct) > **Standard**: The program checks allocation headroom via `bpf_ringbuf_reserve`. If ring space is exhausted, the packet is immediately dropped in-kernel at the XDP layer (`XDP_DROP`), preserving user-space CPU and memory while completely shedding downstream backpressure. ```c // GOOD: Enforces in-kernel watermark backpressure invariant using bpf_ringbuf_reserve. // Drops packet at NIC layer (XDP_DROP) before memory-subsystem exhaustion occurs. SEC("xdp") int xdp_ingress_telemetry_good(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; struct eth_hdr *eth = data; if ((void *)(eth + 1) > data_end) return XDP_DROP; // Check ring-buffer pressure via reservation invariant struct event_t *evt = bpf_ringbuf_reserve(&events_ringbuf, sizeof(*evt), 0); if (!evt) { // Invariant breach: user-space ring buffer is saturated. // Immediately enforce backpressure drop to protect host resources. return XDP_DROP; } evt->len = (__u32)(data_end - data); bpf_ringbuf_submit(evt, 0); return XDP_PASS; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF XDP In-Kernel Ring Buffer Backpressure and Adaptive Drop Standard

eBPF XDP In-Kernel Ring Buffer Backpressure and Adaptive Drop Standard defines an industrial-grade behavioral standard for devops engineering. Maintains bounded user-space memory and CPU usage by enforcing early in-kernel XDP packet dropping invariants before ring buffers overload during L4 volumetric DDoS events. Systems must check ring-buffer queue availability and watermarks in XDP context, executing an immediate XDP_DROP when backpressure thresholds are breached instead of attempting unmonitored BPF_MAP_TYPE_RINGBUF emissions. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unchecked Ring-Buffer Submissions and Unbounded User-Space Channel Ingestion Under Volumetric Floods Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unchecked Ring-Buffer Submissions and Unbounded User-Space Channel Ingestion Under Volumetric Floods	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS enforce strict watermark checks using atomic availability counters or `bpf_ringbuf_reserve` capacity validation before allocating metadata buffers.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.