eBPF TC Direct Socket Ingress Acceleration and CFS Quota Decoupling Standard

--- description: eBPF TC Direct Socket Ingress Acceleration and CFS Quota Decoupling Standard - Enforces deterministic eBPF TC (Traffic Control) direct socket assignment and sockhash redirection to bypass host TCP stack ingress traversal overhead. Eliminates CFS bandwidth quota throttling artifacts induced by softirq processing (ksoftirqd) and mitigates socket lock contention under high-PPS workloads by guaranteeing explicit socket state validation, reference count release, and non-blocking fallback handling. globs: bpf/**/*.bpf.c, bpf/**/*.h, src/ebpf/**/*.c, pkg/ebpf/**/*.go, deploy/ebpf/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-tc-direct-sockhash-ingress-standard" --- # eBPF TC Direct Socket Ingress Acceleration and CFS Quota Decoupling Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unchecked Host Stack Ingress Traversal and Unsafe Socket Redirection Without State Validation or Refcount Balancing ## System Constraints You are a Principal Linux Kernel and Systems Architect specializing in eBPF networking, Traffic Control (clsact), and container runtime network acceleration. Mandate strict invariants for socket-level ingress redirection (via BPF_MAP_TYPE_SOCKHASH and bpf_sk_assign) to eliminate CFS throttle spikes and socket lock contention without compromising kernel safety or network state machines. ## Strict Guidelines - Engineers MUST ALWAYS invoke bpf_sk_release() on sockets acquired via bpf_skc_lookup_tcp() or bpf_sk_lookup_tcp() before program termination across all execution branches to prevent kernel socket leaks. - Engineers MUST verify socket state against BPF_TCP_ESTABLISHED or BPF_TCP_LISTEN before attempting direct redirection or bpf_sk_assign(); non-matching states MUST fall back to TC_ACT_OK for standard kernel stack processing. - Engineers MUST NOT drop packets (TC_ACT_SHOT) when sockhash lookup fails or when the socket map entry is stale; programs MUST fall through to host stack processing with TC_ACT_OK to maintain connection resilience. - Programs MUST account for packet segmentation and VLAN/encapsulation tags before computing the 5-tuple hash to avoid misrouting or silent connection drops. - Services MUST pin and configure BPF maps using bpffs with explicit cgroup and NUMA node awareness to prevent cross-NUMA socket lock invalidation and cache line bouncing. - Kernel loaders MUST enforce BPF program attachment via clsact ingress with direct-action (da) flags to bypass unnecessary queue discipline (qdisc) serialization layers. ## Bad vs Good Implementations ### TC Ingress Socket Redirection and Refcount Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to validate skb bounds leading to verifier rejection; does not call bpf_sk_release on the acquired socket resulting in severe kernel memory/socket reference leaks; ignores TCP socket state allowing redirection to closing/timewait sockets; drops traffic with TC_ACT_SHOT on assignment failure instead of falling back to default network stack. ```c #include <linux/bpf.h> #include <linux/pkt_cls.h> #include <bpf/bpf_helpers.h> SEC("tc/ingress") int tc_ingress_bad(struct __sk_buff *skb) { void *data = (void *)(long)skb->data; void *data_end = (void *)(long)skb->data_end; // Insecure parsing without boundary checks struct iphdr *ip = data + sizeof(struct ethhdr); struct tcphdr *tcp = (void *)ip + sizeof(struct iphdr); struct bpf_sock_tuple tuple = {}; tuple.ipv4.saddr = ip->saddr; tuple.ipv4.daddr = ip->daddr; tuple.ipv4.sport = tcp->source; tuple.ipv4.dport = tcp->dest; // Blind lookup and assignment without refcount management or state checking struct bpf_sock *sk = bpf_skc_lookup_tcp(skb, &tuple, sizeof(tuple.ipv4), BPF_F_CURRENT_NETNS, 0); if (sk) { // Drops packet if assign fails, missing release, state ignored if (bpf_sk_assign(skb, sk, 0) != 0) { return TC_ACT_SHOT; } } return TC_ACT_OK; } ``` #### Production Standard (Correct) > **Standard**: Implements strict packet boundary checks passing kernel verifier mandates; checks socket state to ensure only valid established or listening sockets receive early assignment; reliably invokes bpf_sk_release on all paths to avoid reference leaks; guarantees graceful degradation by returning TC_ACT_OK on lookup or state failures. ```c #include <linux/bpf.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> #include <linux/pkt_cls.h> #include <bpf/bpf_helpers.h> #define BPF_TCP_ESTABLISHED 1 #define BPF_TCP_LISTEN 10 SEC("tc/ingress") int tc_ingress_good(struct __sk_buff *skb) { void *data = (void *)(long)skb->data; void *data_end = (void *)(long)skb->data_end; struct ethhdr *eth = data; if ((void *)(eth + 1) > data_end) return TC_ACT_OK; if (eth->h_proto != __builtin_bswap16(ETH_P_IP)) return TC_ACT_OK; struct iphdr *ip = (void *)(eth + 1); if ((void *)(ip + 1) > data_end || ip->protocol != IPPROTO_TCP) return TC_ACT_OK; struct tcphdr *tcp = (void *)ip + (ip->ihl * 4); if ((void *)(tcp + 1) > data_end) return TC_ACT_OK; struct bpf_sock_tuple tuple = {}; tuple.ipv4.saddr = ip->saddr; tuple.ipv4.daddr = ip->daddr; tuple.ipv4.sport = tcp->source; tuple.ipv4.dport = tcp->dest; struct bpf_sock *sk = bpf_skc_lookup_tcp(skb, &tuple, sizeof(tuple.ipv4), BPF_F_CURRENT_NETNS, 0); if (!sk) return TC_ACT_OK; if (sk->state == BPF_TCP_ESTABLISHED || sk->state == BPF_TCP_LISTEN) { // Direct socket assignment bypasses backlog queuing and CFS accounting bpf_sk_assign(skb, sk, 0); } bpf_sk_release(sk); return TC_ACT_OK; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC Direct Socket Ingress Acceleration and CFS Quota Decoupling Standard

eBPF TC Direct Socket Ingress Acceleration and CFS Quota Decoupling Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic eBPF TC (Traffic Control) direct socket assignment and sockhash redirection to bypass host TCP stack ingress traversal overhead. Eliminates CFS bandwidth quota throttling artifacts induced by softirq processing (ksoftirqd) and mitigates socket lock contention under high-PPS workloads by guaranteeing explicit socket state validation, reference count release, and non-blocking fallback handling. 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 Host Stack Ingress Traversal and Unsafe Socket Redirection Without State Validation or Refcount Balancing 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 Host Stack Ingress Traversal and Unsafe Socket Redirection Without State Validation or Refcount Balancing	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 invoke bpf_sk_release() on sockets acquired via bpf_skc_lookup_tcp() or bpf_sk_lookup_tcp() before program termination across all execution branches to prevent kernel socket leaks.

Engineers MUST ALWAYS invoke bpf_sk_release() on sockets acquired via bpf_skc_lookup_tcp() or bpf_sk_lookup_tcp() before program termination across all execution branches to prevent kernel socket leaks.

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.