mirror of
https://github.com/lgcosta/pf-linux-port.git
synced 2026-11-12 22:38:03 -03:00
lgcosta
928322edf7
The manual is the from-zero path on Debian 13 (trixie): packages, the 7.3.4 kernel tree, pf.ko, the userland, the libvirt lab, the gate suite, the stress test and running PF on the host itself. Every command in it was executed on the lab's Debian 13.7 host, including the toolchain report and the kernel.org checksum. Trixie ships gcc 14 and no gcc-15; the kernel and pf.ko build with gcc 14 unpatched, so the manual documents that instead of the gcc >= 15 the generic install guide asks for.
PF-on-Linux documentation (English)
Documentação em português: docs/pt-BR/README.md.
This is the user documentation set for the port of the OpenBSD 8.0 PF
packet filter to Linux 7.3.4 — the real PF engine (pf.c, pf_norm.c,
pf_table.c, pf_lb.c, hfsc.c, …) running as the out-of-tree module
pf.ko, driven by the real OpenBSD pfctl over the /dev/pf ioctl ABI.
Index
| Doc | What it covers |
|---|---|
| guide.md | One-page architecture: components, data path, control plane, milestones |
| install.md | Apply/build/install recipe (kernel, module, tools) |
| build.md | Build pipeline in detail: fetch → vendorize → kernel → module → pfctl |
| vm-lab.md | The libvirt validation lab: topology, recreate/run, what each of the 15 gates proves |
| feature-matrix.md | Per-feature status: VERIFIED-in-VM / VERIFIED-offline / COMPILES-untested / NOT-ENABLED |
| pf-guide.md | Daily use: what works today in /etc/pf.conf, and the deviations to know about |
| screencast.md | The narrated videos (English and Portuguese): phases, pipeline, how to re-record |
| patches.md | Linux core patch set (currently empty) + rules and template for future 000N-*.patch |
| caveats.md | Known divergences from OpenBSD behavior and current limitations |
Sources of truth
The docs describe the code as it exists in this tree. When in doubt, the authoritative references are:
docs/superpowers/specs/2026-11-11-pf-linux-port-design.md— designdocs/superpowers/plans/2026-11-11-pf-linux-port.md— milestone plan (tasks T1–T19)docs/porting-notes.md— staging log + the deviation record (the truth about compat-layer divergences)
Feature-status vocabulary used across these docs:
- VERIFIED-in-VM — exercised end-to-end in the libvirt lab; the gate that proves it is named (see vm-lab.md).
- VERIFIED-offline — proven by a fixture or ABI test, not by traffic.
- COMPILES-untested — the code is built into
pf.ko/pfctlbut no gate has exercised it. - NOT-ENABLED — the code exists but the feature is off in this build.
- OUT-OF-SCOPE — non-goal by design (spec §3).
The lab suite is 15/15 green (./scripts/vm-run-tests.sh).