Skip to content

Add four advanced runnable eBPF tutorial tools - #224

Open
yunwei37 wants to merge 14 commits into
mainfrom
feat/four-production-ebpf-tutorials
Open

Add four advanced runnable eBPF tutorial tools#224
yunwei37 wants to merge 14 commits into
mainfrom
feat/four-production-ebpf-tutorials

Conversation

@yunwei37

@yunwei37 yunwei37 commented Jul 22, 2026

Copy link
Copy Markdown
Member

What changed

This PR adds four runnable eBPF tools with English and Chinese tutorials:

  • 55-dns-egress builds a minimal DNS-derived IP allowlist. It correlates DNS queries and responses, rejects unsolicited or mismatched responses, keeps learned A records for their TTL, and enforces the result at cgroup/connect4.
  • 56-tc-flow-index uses BPF objects, refcounts, and two rbtrees to maintain identity and traffic-ordered views of the same TC egress flow records.
  • 57-oom-watch profiles recorded memcg reclaim intervals and sampled kernel stacks, then correlates the accumulated profile with OOM victim selection and victim exit.
  • 60-afxdp-dump implements an exclusive, receive-only AF_XDP path with direct UMEM and ring management, packet filtering, frame recycling, and native-to-generic XDP fallback.

Each lesson includes a compact CLI, a deterministic integration test, the mechanism-relevant source and a link to the complete implementation, requirements, representative output from a real run, and primary upstream references.

The repository-local writing workflow keeps a single writer for reader-facing prose and avoids a mandatory second prose review for content-only work. It still requires implementation-aware fact checking of source excerpts, commands, behavior, versions, requirements, output, and relevant validation evidence.

Why

The examples fill four technical gaps in the tutorial series: DNS-derived connect policy, refcounted graph ownership with multiple indexes, reclaim profiling before an OOM kill, and a first standalone AF_XDP receive path. Each tool keeps the main kernel mechanism visible while still accepting a real cgroup or interface in normal mode.

Validation

  • Clean host builds passed for all four lesson implementations.
  • Integration tests passed for all four lessons as root on x86_64 Linux 7.2.0-rc4 built from kernel commit 1590cf0329716306e948a8fc29f1d3ee87d3989f.
  • The DNS demo passed its complete query-correlation, poisoning-resistance, live-TTL, and expired-TTL path.
  • AF_XDP passed native driver mode and explicit generic/SKB mode, including 65 packets through a 64-frame UMEM and a non-matching pass-through check.
  • Documentation unit tests and source-block validator tests pass.
  • Generated TOCs and compatibility tables are current.
  • Internal links, prohibited dash punctuation, merge markers, and git diff --check pass.

@yunwei37 yunwei37 changed the title Add four production-shaped eBPF tutorial tools Add four advanced runnable eBPF tutorial tools Jul 22, 2026
@yunwei37

Copy link
Copy Markdown
Member Author

Final dedicated review for exact head 41dff7e: NO BLOCKERS.\n\nReviewed the four tutorial implementations and bilingual rewrites, conflict resolution in the three repository-local skills, source-block synchronization, scope, version metadata, and KVM validation evidence. The reader-focused rewrite preserves complete kernel and user-space source while making the narrative follow each tool's real data flow. All four host builds and KVM scenarios passed; the final DNS refactor was rerun in KVM. No conflict markers, history deletion, relative-link regressions, or infrastructure/model/prompt leakage were found.

@yunwei37

Copy link
Copy Markdown
Member Author

Independent external review for exact head 41dff7e: NO BLOCKERS.\n\nThe review independently checked the three skill conflict resolutions, all four English/Chinese tutorials, byte-exact embedded source, program types and minimum-kernel claims, public sample-output provenance, CI scope, absolute links, and leakage constraints. It confirmed that the AF_XDP article now shows only output emitted by the public tool, all core kernel and user-space source remains complete, and the change set is proportional to four runnable advanced tutorials. The only nonblocking qualification is that the newest 6.16/7.1 APIs were exercised end to end on the shared Linux 7.2-rc4 KVM kernel rather than separately on every declared minimum kernel.

@yunwei37
yunwei37 marked this pull request as ready for review July 22, 2026 09:42
@yunwei37

yunwei37 commented Jul 26, 2026

Copy link
Copy Markdown
Member Author

Exact-head follow-up review is complete for f2f3ab9.

The review found that the content-only workflow had removed technical-fidelity checks and that several rewritten passages no longer matched the implementations. The final head now:

  • keeps the single-writer/no-second-prose-review path while restoring implementation-aware checks for source excerpts, commands, behavior, versions, requirements, output, and validation evidence;
  • describes lesson 60 as an exclusive AF_XDP receiver rather than passive packet capture and removes unsupported production-use claims;
  • qualifies lesson 57 around recorded/matched reclaim intervals and verifier risk;
  • fixes the lesson 56 four-file count and refreshes the PR body/generated titles.

Two independent final reviews found no actionable issues on the exact head. Documentation unit tests, source-block validator tests, generated indexes, internal links, punctuation/merge-marker scans, and git diff --check pass locally. CI is running on the final commit; there are no unresolved review threads.

AI-generated response; a maintainer will review and follow up later

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants