eBPF TC Ingress Dynamic MSS Clamping Production Standard

--- description: eBPF TC Ingress Dynamic MSS Clamping Production Standard - Enforces deterministic TCP Maximum Segment Size (MSS) clamping at the eBPF Traffic Control (TC) ingress hook prior to tunnel encapsulation. Prevents silent Path MTU Discovery (PMTUD) blackholing across hybrid cloud overlay topologies by rewriting TCP Option 2 on SYN/SYN-ACK segments and incrementally updating Layer 4 checksums. globs: bpf/**/*.bpf.c, src/ebpf/**/*.c, pkg/ebpf/**/*.go, deployments/tc/**/*.sh, kernel/network/**/*.c alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-tc-ingress-dynamic-mss-clamping-standard" --- # eBPF TC Ingress Dynamic MSS Clamping Production Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Static MTU assumptions, missing TCP checksum incremental updates, or omitting BPF verifier pointer re-validations during option rewriting. ## System Constraints You are a Principal Linux Kernel and Systems Reliability Engineer specializing in high-throughput network datapaths and eBPF. Enforce strict mathematical and verifier-safe invariants for TC ingress MSS clamping programs. Never allow unchecked TCP option scanning, static unvalidated offsets, or uncompensated L4 checksum mutations across hybrid mesh networks. ## Strict Guidelines - Engineers MUST ALWAYS filter for TCP SYN or SYN-ACK packets before parsing TCP options, instantly returning TC_ACT_OK for established data traffic. - Engineers MUST ALWAYS re-validate packet bounds pointers (`data`, `data_end`) after invoking any BPF helper function that mutates skb length or header layout. - Engineers MUST ALWAYS parse TCP options using bounded loops with `#pragma unroll` to satisfy the BPF verifier's termination analysis. - Engineers MUST update the TCP checksum incrementally using `bpf_l4_csum_replace()` with `BPF_F_PSEUDO_HDR` whenever the MSS option value is modified. - Engineers MUST NOT hardcode MSS option offsets; options MUST be discovered via RFC 793 TLV iteration up to `doff * 4` bytes. - Engineers MUST NOT clamp MSS upwards; clamping MUST only decrease the advertised MSS when it exceeds the dynamic link path budget (`Target_MSS = Tunnel_MTU - IP_Header - TCP_Header`). - Services MUST query encapsulation overhead dynamically from a synchronized BPF map keyed by destination egress subnet or overlay tunnel device type. ## Bad vs Good Implementations ### eBPF C TC Ingress Dynamic MSS Clamping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails verifier bounds checking on packet pointers, hardcodes TCP MSS option offset at index 22 without parsing TLVs, mutates non-SYN frames, corrupts TCP checksum, and triggers kernel panic or verifier rejection. ```c #include <linux/bpf.h> #include <linux/pkt_cls.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> #include <bpf/bpf_helpers.h> SEC("tc/ingress") int clamp_mss_bad(struct __sk_buff *skb) { void *data = (void *)(long)skb->data; void *data_end = (void *)(long)skb->data_end; struct iphdr *ip = data + sizeof(struct ethhdr); struct tcphdr *tcp = (void *)ip + sizeof(struct iphdr); // ANTI-PATTERN: Direct access without bounds checks; assumes fixed TCP option offset; // does not recalculate TCP checksum; clamps even non-SYN packets. __u16 *mss = (void *)tcp + 22; if (*mss > 1300) { *mss = __builtin_bswap16(1300); } return TC_ACT_OK; } ``` #### Production Standard (Correct) > **Standard**: Implements RFC-compliant TCP option parsing with bounded loop unrolling, validates all memory offsets to satisfy the eBPF verifier, inspects only SYN packets, clamps downwards, and updates the L4 checksum incrementally via bpf_l4_csum_replace. ```c #include <linux/bpf.h> #include <linux/pkt_cls.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> #include <bpf/bpf_helpers.h> #include <bpf/bpf_endian.h> #define TCP_OPT_MSS 2 #define TCP_OPT_MSS_LEN 4 #define MAX_CLAMPED_MSS 1350 SEC("tc/ingress") int clamp_mss_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 != __bpf_constant_htons(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; // Only inspect SYN packets if (!tcp->syn) return TC_ACT_OK; __u8 tcp_hdr_len = tcp->doff * 4; if (tcp_hdr_len <= sizeof(struct tcphdr)) return TC_ACT_OK; __u8 *opt_start = (void *)tcp + sizeof(struct tcphdr); __u8 *opt_end = (void *)tcp + tcp_hdr_len; if ((void *)opt_end > data_end) return TC_ACT_OK; #pragma unroll for (int i = 0; i < 40; i++) { if (opt_start + 1 > opt_end || opt_start + 1 > data_end) break; __u8 opt_kind = *opt_start; if (opt_kind == 0) break; if (opt_kind == 1) { opt_start++; continue; } if (opt_start + 2 > opt_end || opt_start + 2 > data_end) break; __u8 opt_len = *(opt_start + 1); if (opt_len < 2 || opt_start + opt_len > opt_end || opt_start + opt_len > data_end) break; if (opt_kind == TCP_OPT_MSS && opt_len == TCP_OPT_MSS_LEN) { __u16 *mss_val = (__u16 *)(opt_start + 2); __u16 current_mss = bpf_ntohs(*mss_val); if (current_mss > MAX_CLAMPED_MSS) { __be16 new_mss = bpf_htons(MAX_CLAMPED_MSS); __be16 old_mss = *mss_val; __u32 off = ((void *)mss_val) - data; // Safe L4 incremental checksum update bpf_l4_csum_replace(skb, ((void *)&tcp->check) - data, old_mss, new_mss, sizeof(new_mss)); bpf_skb_store_bytes(skb, off, &new_mss, sizeof(new_mss), 0); } break; } opt_start += opt_len; } return TC_ACT_OK; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC Ingress Dynamic MSS Clamping Production Standard

eBPF TC Ingress Dynamic MSS Clamping Production Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic TCP Maximum Segment Size (MSS) clamping at the eBPF Traffic Control (TC) ingress hook prior to tunnel encapsulation. Prevents silent Path MTU Discovery (PMTUD) blackholing across hybrid cloud overlay topologies by rewriting TCP Option 2 on SYN/SYN-ACK segments and incrementally updating Layer 4 checksums. 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: Static MTU assumptions, missing TCP checksum incremental updates, or omitting BPF verifier pointer re-validations during option rewriting. 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	Static MTU assumptions, missing TCP checksum incremental updates, or omitting BPF verifier pointer re-validations during option rewriting.	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 filter for TCP SYN or SYN-ACK packets before parsing TCP options, instantly returning TC_ACT_OK for established data traffic.

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.