36 Commits
Author SHA1 Message Date
lgcosta bc5b8a4a1e demo: pflog step in the asciinema recording (pflogd: 2 records, DLT_PFLOG pcap); re-recorded cast 2026-11-11 22:07:45 -03:00
lgcosta 06ad1baa3a runner: deploy pdivert/pflogd alongside pf.ko and pfctl 2026-11-11 22:00:15 -03:00
lgcosta f263b63b8e docs: guides reflect verified NAT/redirect/divert/pflog and the fixed state listing; CHANGELOG for v0.4.0 2026-11-11 21:58:57 -03:00
lgcosta 92c015b97b docs: pflog verified (matrix EN+PT-BR, porting notes, README status) 2026-11-11 21:53:55 -03:00
lgcosta 7a81076c6a pflog: /dev/pflog chardev backend (BSD pflog_hdr layout, DLT_PFLOG) + tools/pflogd + gate 12 2026-11-11 21:52:36 -03:00
lgcosta dbb21048e4 tests: 06 gate self-sufficient (bracketed pkill patterns, srv cleanup) - avoids cross-run listener contamination 2026-11-11 21:35:50 -03:00
lgcosta 0eb040fcc8 docs: rdr-to verified; porting notes on checksum strategy across translation paths (GSO regression) 2026-11-11 21:27:32 -03:00
lgcosta 5af7adb08e checksums: GSO-aware recompute after translation (software for plain skbs, CHECKSUM_PARTIAL for GSO); 06 gate asserts 2MB integrity through rdr 2026-11-11 21:24:41 -03:00
lgcosta d9fc3a7e3f checksums: materialize CHECKSUM_PARTIAL before pf so address-rewrite fixups operate on real values; new 06-rdr gate 2026-11-11 20:53:03 -03:00
lgcosta b554c9a6ef demo: ship the asciinema recording in the repo (out/demo-pf-linux.cast) 2026-11-11 20:33:57 -03:00
lgcosta 6cc4e21ae2 docs+demo: asciinema recording of the lab (stateful filtering, tables, drop, NAT, divert); README/matrix reflect the verified state 2026-11-11 20:33:27 -03:00
lgcosta 2cd13eb806 tests: soak helper ignores the CPU SRSO advisory 2026-11-11 20:29:33 -03:00
lgcosta e03df9adc8 docs: data-path semantics and NAT checklist 2026-11-11 20:25:57 -03:00
lgcosta 7d1e4b81e9 cleanup: drop debug instrumentation 2026-11-11 20:24:53 -03:00
lgcosta f3143a54a8 nat: route the reverse-translated packet with an empty source (kernel rejects non-local saddr) 2026-11-11 20:23:44 -03:00
lgcosta 917d3e3fe0 nat: recompute IPv4 header checksum after pf rewrote the addresses (OpenBSD ip_output does this) 2026-11-11 20:20:52 -03:00
lgcosta d520172753 nat: re-route inbound packets whose destination pf rewrote (reverse NAT) instead of delivering them locally 2026-11-11 20:17:27 -03:00
lgcosta 9c3c4b6bbc fix: skb->mark masks were multi-bit (IN mark matched OUT test) - transit traffic never reached the out ruleset; ingress/egress interface groups; pfctl resolves (egress) pool locally 2026-11-11 20:15:35 -03:00
lgcosta c449e01b9a pf: emulate OpenBSD ingress/egress interface groups as any-interface (Linux has no ifgroups) 2026-11-11 20:07:17 -03:00
lgcosta 525fe7ee28 tests: gate assertions corrected (pfctl state format, transit egress device, CPU SRSO advisory excluded); Makefile demo target 2026-11-11 20:04:16 -03:00
lgcosta 18c0a69f74 tests: soak gate via uploaded helper (quoting), 04/05 assertions fixed (pf interface name vs OS device) 2026-11-11 19:59:27 -03:00
lgcosta 3aa0c2d0d0 docs: demo guide (asciinema recording/playback/upload) EN+PT-BR 2026-11-11 19:56:24 -03:00
lgcosta 66939c839a tests: 04 gate rewritten to OpenBSD-correct anchor semantics (reply is evaluated by the in ruleset); 05 gate uses 8.0 nat-to syntax; 14 quoting fixed; demo session + asciinema recorder 2026-11-11 19:54:29 -03:00
lgcosta 444a0555c6 docs: divert verified (matrix + porting notes); FORWARD hook evaluates the out ruleset for transit traffic 2026-11-11 19:50:14 -03:00
lgcosta bdf9db7a21 fix: remove leftover debug fragment in pfk_hooks 2026-11-11 19:45:43 -03:00
lgcosta 57ecc15606 divert: end-to-end working (network-order port, direct IN-verdict handoff, L2-synth reinjection, skip-mark anti-loop, pdivert ICMP checksum fix) 2026-11-11 19:45:29 -03:00
lgcosta 4728648a0c divert: consume PF_TAG_DIVERTED after passthrough (BSD ip_input role); divert layer owns its own skb ref; gate uses pfput path 2026-11-11 19:19:53 -03:00
lgcosta da1f678125 divert: fix NULL-deref on empty listener list (wedged pf0 in gate 11); gate 11 pdivert path; runner accepts gate filter arg 2026-11-11 19:15:48 -03:00
lgcosta fd0be917fe tests: 14-soak gate (state/traffic soak, dmesg clean, unload/reload cycles, slab delta) 2026-11-11 19:14:27 -03:00
lgcosta 4994c577cd tests: divert gate syntax fixed (divert-to <host> port <n>), pdivert deploy; new 05-nat gate (nat-to egress, tcpdump proof) 2026-11-11 19:13:00 -03:00
lgcosta 7014628e8d M2: refcnt_rele polarity, radix SALEN by family, LIST_HEAD dispatch + harness scp-failure hardening (gates 01-03 green) 2026-11-11 19:11:25 -03:00
lgcosta 493ec25fb3 tests: 11-divert gate design (noport drop + pdivert rewrite proof) 2026-11-11 18:52:57 -03:00
lgcosta 1ec52e890d tools: build pdivert (static), single 'all' target 2026-11-11 18:50:56 -03:00
lgcosta 0fe4d83b93 docs: divert status corrected after AF_DIVERT restore (COMPILES untested, M4 e2e gate defined) 2026-11-11 18:50:29 -03:00
lgcosta ac56534c3b AF_DIVERT family restored & compiling: full socket family (PF_DIVERT=32, sock_register), blocking recv/poll, divert_output-compatible sendmsg reinject, mtag type passthrough; pfk_api decls 2026-11-11 18:47:04 -03:00
lgcosta fe6f767561 queue.h: arg-count dispatch so BSD LIST_HEAD(name,type) and Linux LIST_HEAD(name) coexist 2026-11-11 18:44:22 -03:00
63 changed files with 6103 additions and 141 deletions

No files matched your search

+2
View File
@@ -1,5 +1,6 @@
_vendor/ _vendor/
out/ out/
!out/demo-pf-linux.cast
*.o *.o
*.ko *.ko
*.mod *.mod
@@ -10,6 +11,7 @@ out/
modules.order modules.order
Module.symvers Module.symvers
tools/out/ tools/out/
!out/demo-pf-linux.cast
lab/seeds/ lab/seeds/
*.pcap *.pcap
*.log *.log
+88
View File
@@ -0,0 +1,88 @@
# Changelog
## v0.4.0 — 2026-11-11
Lab-verified milestone release. The full gate suite (9 gates) runs against
Alpine VMs under libvirt on the kernel built from source.
### Verified in the lab (each has a gate in `tests/vm/`)
| Capability | Gate | What it proves |
|---|---|---|
| Engine loads, `/dev/pf`, real OpenBSD `pfctl` over the ioctl ABI | `01` | `insmod` + `pfctl -s info` + transit ping + state created |
| `block` / `return` / `return-rst` | `02` | ICMP dropped, TCP refused |
| `pfr` tables (inline `{ }`, `-T add/del/show`, `-T` block) | `03` | table load, block by table, delete, unblock |
| Anchors and evaluation order | `04` | anchor child passes the request before the parent `block`, state created by the anchor rule, request dropped after the anchor is flushed |
| `nat-to` (source NAT) | `05` | tcpdump proof of the rewritten source, reply de-NATed, state shows both tuples |
| `rdr-to` (port redirect) | `06` | client talks to the firewall, server answers, **2 MB pulled through the redirect byte-identical**, firewall still responsive afterwards |
| `divert-to` + `AF_DIVERT` + `pdivert` | `11` | drop with no listener (BSD `divs_noport` parity), packet delivered to userspace, rewritten and reinjected |
| `pflog` + `pflogd` | `12` | logged packets read from `/dev/pflog` and written as a `DLT_PFLOG` pcap containing the real bytes |
| Soak / unload discipline | `14` | traffic + states with no kernel warnings, clean `rmmod`, reload, no slab growth |
### Added
- `module/pfsrc/pfk_pflog.c` — `/dev/pflog` chardev backend (OpenBSD
`pflog_hdr` layout, 64-byte records, bounded queue, `poll`, stats ioctl).
- `tools/pflogd` — reads `/dev/pflog`, writes `DLT_PFLOG` pcap (or a readable
one-line-per-record summary).
- `tools/pdivert` — divert(4) relay with payload mutation + ICMP checksum fix.
- `module/pfsrc/divert_sock.c` — `AF_DIVERT` socket family registered at
runtime (`PF_DIVERT = 32`, `IPPROTO_DIVERT = 254`), blocking `recvmsg`,
`poll`, BSD-compatible reinjection.
- `scripts/demo-session.sh` + `scripts/demo-record.py` + `make demo` —
asciinema recording of the live lab (`out/demo-pf-linux.cast`).
- `docs/{en,pt-BR}/`: README, install, build, guide, vm-lab, feature-matrix,
patches, caveats, demo. `docs/porting-notes.md` records every deviation.
- `patches/kernel/` + `scripts/apply-patches.sh` / `scripts/unpatch.sh` —
kernel-core patch mechanism, empty series by design (verified: the module
needs no core patch).
### Fixed (all found by the VM gates, root causes documented)
- `skb->mark` bookkeeping used multi-bit values, so the "in pass done" mark
also satisfied the "out pass done" test: transit traffic never reached the
**out** ruleset (NAT and egress rules silently ignored).
- The out ruleset was never evaluated for forwarded packets: added the
`NF_INET_FORWARD` hook (OpenBSD evaluates it in `ip_forward()`).
- `refcnt_rele()` had inverted polarity → live state keys freed → `Oops` in
the state RBT and `pfctl -s states` hangs.
- `radix` `SALEN()` read the `sa_family` byte as a length (Linux sockaddrs
have no `sa_len`) → table entries dropped as duplicates.
- BSD/Linux `LIST_HEAD` macro arity clash in `compat/sys/queue.h`.
- Reverse NAT: a packet whose destination pf rewrote was delivered to the
firewall's own stack instead of being re-routed.
- Checksums across translation: IP header checksum recomputed (OpenBSD's
`ip_output` does this, Linux does not); transport checksum recomputed in
software for plain skbs and handed back to the NIC (`CHECKSUM_PARTIAL`) for
GSO/TSO — the earlier software-only fix corrupted every segment after the
first and stalled bulk transfers.
- `divert`: NULL dereference on an empty listener list (wedged the VM),
port byte order mismatch between `bind` and the queue, L3-only skbs injected
into an Ethernet device RX path, re-divert loop (solved with a skip mark).
- `IOC_SIZEBITS` = 14 truncated the rule ioctl struct → `EINVAL` on load.
- State iteration started at id 1 (kifs never attached), `stoeplitz_init()`
never called, purge timer re-arming itself at `rmmod`, `rtnl`×`NET` lock
order inversion in the interface notifier.
### Known gaps
`binat-to`, `route-to`/`dup-to`/`fail-to`, `af-to`, scrub end-to-end
(normalization code is ported and compiles; the lab gate is not written),
queues/ALTQ (`hfsc.c`/`fq_codel.c` staged, `pfq` qdisc not implemented),
`pfsync`/CARP (out of scope). See `docs/en/feature-matrix.md`.
## v0.3.0 — 2026-11-11
M2 data path: netisr-style workqueue, per-direction marks, state/table/anchor
gates passing; divert design settled (in-module socket family, no core patch).
## v0.2.0 — 2026-11-11
M1: engine compiles into `pf.ko` (pf.c, pf_ioctl.c with the full ioctl ABI,
pf_norm, pf_if, pf_lb, pf_table, pf_ruleset, pf_osfp, pf_syncookies, radix,
md5/sha, ifq), `/dev/pf`, Linux-built OpenBSD `pfctl` talking to it.
## v0.1.0 — 2026-11-11
M0: repo, bilingual scaffold, kernel 7.3.4 build, libvirt Alpine lab with
custom-kernel VMs (pf0/cli/srv/gw2), build/deploy/test scripts.
+10 -2
View File
@@ -1,7 +1,7 @@
# PF-on-Linux top-level make # PF-on-Linux top-level make
KERNELDIR ?= $(HOME)/lab/linux_kernel/linux-7.3.4 KERNELDIR ?= $(HOME)/lab/linux_kernel/linux-7.3.4
.PHONY: module tools kernel test clean vm vm-destroy docs .PHONY: module tools kernel test clean vm vm-destroy docs demo
module: module:
$(MAKE) -C $(KERNELDIR) M=$(CURDIR)/module modules $(MAKE) -C $(KERNELDIR) M=$(CURDIR)/module modules
@@ -25,7 +25,15 @@ docs:
@for f in docs/en/*.md; do echo "EN $$f"; done @for f in docs/en/*.md; do echo "EN $$f"; done
@for f in docs/pt-BR/*.md; do echo "PT $$f"; done @for f in docs/pt-BR/*.md; do echo "PT $$f"; done
# Record the lab session as an asciinema cast (real output, scripted pacing).
demo:
@mkdir -p out
@command -v asciinema >/dev/null 2>&1 || { \
echo "asciinema not installed: pip install asciinema"; exit 1; }
asciinema rec out/demo-pf-linux.cast -c "bash scripts/demo-session.sh"
@echo "-> out/demo-pf-linux.cast (play: asciinema play out/demo-pf-linux.cast)"
clean: clean:
$(MAKE) -C $(KERNELDIR) M=$(CURDIR)/module clean || true $(MAKE) -C $(KERNELDIR) M=$(CURDIR)/module clean || true
$(MAKE) -C tools clean || true $(MAKE) -C tools clean || true
rm -rf out/ @find out -maxdepth 1 -type f ! -name '*.cast' -delete 2>/dev/null || true
+48 -21
View File
@@ -1,15 +1,31 @@
# PF on Linux # PF on Linux
Port of the OpenBSD **PF** (packet filter) to **Linux 7.3.4** as out-of-tree Port of the OpenBSD **PF** (packet filter) to **Linux 7.3.4** as an
kernel modules — the real PF engine (`pf.c`, `pf_norm.c`, `pf_table.c`, out-of-tree kernel module — the real PF engine (`pf.c`, `pf_norm.c`,
`pf_lb.c`, … ported from OpenBSD 8.0 sources) driven by the real OpenBSD `pf_table.c`, `pf_lb.c`, … ported from OpenBSD 8.0 sources) driven by the
`pfctl` over the `/dev/pf` ioctl ABI. real OpenBSD `pfctl` over the `/dev/pf` ioctl ABI. (A second module for the
`pfq` qdisc arrives with M5.)
**Status:** implementation in progress — see **Status:** the filter core, stateful filtering, tables, anchors, NAT
[`docs/superpowers/plans/2026-11-11-pf-linux-port.md`](docs/superpowers/plans/2026-11-11-pf-linux-port.md) (`nat-to`/`rdr-to`), `divert` and `pflog` are **verified in a real libvirt
for task progress and lab** (9/9 gates green). The remaining features (binat-to, route-to/dup-to,
[`docs/superpowers/specs/2026-11-11-pf-linux-port-design.md`](docs/superpowers/specs/2026-11-11-pf-linux-port-design.md) scrub e2e, ALTQ/pfq, af-to) are still pending — honest per-feature status:
for the design. [`docs/en/feature-matrix.md`](docs/en/feature-matrix.md).
Demo (asciinema): [`docs/en/demo.md`](docs/en/demo.md).
Design: [`docs/superpowers/specs/2026-11-11-pf-linux-port-design.md`](docs/superpowers/specs/2026-11-11-pf-linux-port-design.md)
· plan: [`docs/superpowers/plans/2026-11-11-pf-linux-port.md`](docs/superpowers/plans/2026-11-11-pf-linux-port.md).
## Milestones
| Milestone | Scope | Status (2026-11-11) |
|---|---|---|
| M0 | repo, scripts, kernel build, VM boots the custom kernel | done |
| M1 | compat layer, `pf.ko` loads, `/dev/pf`, `pfctl -f` / `-s info` | done |
| M2 | filter core: rules/states/tables/anchors, VM gates 01–04 | **done** — gates 01/02/03/04 green |
| M3 | NAT (`nat-to`/`rdr-to`/`binat-to`), scrub e2e | **partial** — `nat-to` (gate 05) and `rdr-to` incl. 2 MB integrity (gate 06) verified; `binat-to` and scrub e2e pending |
| M4 | route-to/dup-to/fail-to, divert e2e, pflog | **partial** — divert e2e (gate 11) and pflog (gate 12) verified; route-to/dup-to pending |
| M5 | queues: HFSC/FQ-CoDel back ends + `pfq` qdisc | pending |
| M6 | docs complete, patchset tidy, full suite green, tagged release | in progress (docs done, suite 7/7 green) |
## What you get (planned) ## What you get (planned)
@@ -20,33 +36,44 @@ for the design.
| NAT | `nat-to` (port pools, sticky-port, static-port), `rdr-to`, `binat-to` | | NAT | `nat-to` (port pools, sticky-port, static-port), `rdr-to`, `binat-to` |
| Scrub | fragment reassembly, overlap drop, `min-ttl`/`max-mss`/`df`/`no-df`, `set reassemble` | | Scrub | fragment reassembly, overlap drop, `min-ttl`/`max-mss`/`df`/`no-df`, `set reassemble` |
| QoS (ALTQ successor) | `queue`/`queue on` with OpenBSD 8.0 `ifq` schedulers: **default (priq), HFSC, FQ-CoDel**, attached via the `pfq` qdisc; `pfctl -s queue -v` stats | | QoS (ALTQ successor) | `queue`/`queue on` with OpenBSD 8.0 `ifq` schedulers: **default (priq), HFSC, FQ-CoDel**, attached via the `pfq` qdisc; `pfctl -s queue -v` stats |
| Divert | `divert-to` / `divert` tag + `pdivert` userspace channel (netlink; Linux has no `AF_DIVERT`) | | Divert | `divert-to` / `divert` tag + `pdivert` relay over an in-module `PF_DIVERT` socket family (verified: packet to userspace and back) |
| Route | `route-to` (pools rr/hash-source/hash-state, `fail-to`), `reply-to`, `dup-to` | | Route | `route-to` (pools rr/hash-source/hash-state, `fail-to`), `reply-to`, `dup-to` |
| Logging | `pflogd` via netlink pflog channel (DLT_PFLOG pcap) | | Logging | `pflogd` via `/dev/pflog` (DLT_PFLOG pcap, OpenBSD record layout) |
| Control | `/dev/pf` (0600), OpenBSD 8.0 ioctl ABI, Linux build of `pfctl` (single binary) | | Control | `/dev/pf` (0600), OpenBSD 8.0 ioctl ABI, Linux build of `pfctl` (single binary) |
Not in scope: `pfsync`/CARP failover, IPsec/pfkey, `ftp-proxy`, per-netns PF Not in scope: `pfsync`/CARP failover, IPsec/pfkey, `ftp-proxy`, per-netns PF
instances, classic-ALTQ-only schedulers (cbq/wfq/red — removed upstream before instances, classic-ALTQ-only schedulers (cbq/wfq/red — removed upstream before
OpenBSD 8.0). OpenBSD 8.0).
## Quick start (after M1+) ## Quick start
Full recipe: [`docs/en/install.md`](docs/en/install.md). Short version
(commands are read from the scripts; a fresh-clone end-to-end run is still
pending):
```sh ```sh
./scripts/fetch-sources.sh # OpenBSD 8.0 sources (C3SL mirror, checksummed) ./scripts/fetch-sources.sh # OpenBSD 8.0 sources (C3SL mirror, sha256-pinned)
./scripts/apply-patches.sh ../linux-7.3.4 # core export patch(es) ./scripts/vendorize.sh # stage the pristine files we port
make module tools # pf.ko, pfq.ko, pfctl, pdivert, pflogd ./scripts/build-kernel.sh # kernel 7.3.4: bzImage + modules_prepare (export patch: none needed)
sudo insmod module/pf.ko module/pfq.ko ./scripts/build-module.sh # -> module/pf.ko
make -C tools # -> tools/out/pfctl (static), ABI harness
sudo insmod module/pf.ko # /dev/pf (0600) + netfilter hooks
sudo pfctl -f /etc/pf.conf && sudo pfctl -e sudo pfctl -f /etc/pf.conf && sudo pfctl -e
``` ```
VM validation lab (Alpine on libvirt): see `docs/en/vm-lab.md`. Read [`docs/en/pf-guide.md`](docs/en/pf-guide.md) **before** enabling PF on a
Documentação em português: [`README.pt-BR.md`](README.pt-BR.md) e `docs/pt-BR/`. path you need: only the M2 filter core is gated today; NAT/scrub/queues/
divert/pflog are not usable yet ([`docs/en/feature-matrix.md`](docs/en/feature-matrix.md)).
VM validation lab (Alpine on libvirt): [`docs/en/vm-lab.md`](docs/en/vm-lab.md).
Documentação em português: [`README.pt-BR.md`](README.pt-BR.md) e
[`docs/pt-BR/`](docs/pt-BR/README.md).
## Layout ## Layout
- `module/` — kernel sources (ported PF + compat layer + pfq qdisc) - `module/` — kernel sources (ported PF + compat layer; the `pfq` qdisc lands with M5)
- `tools/` — pfctl/pdivert/pflogd Linux builds - `tools/` — pfctl (static Linux build), pdivert relay source, ABI harness (`pflogd` not ported yet)
- `patches/kernel/` — documented Linux core patches (export symbols only) - `patches/kernel/` — Linux core patch set (currently empty; evidence in `p1-needs.txt`, see `docs/en/patches.md`)
- `scripts/` — fetch/build/patch/VM automation - `scripts/` — fetch/build/patch/VM automation
- `tests/` — VM suite (`tests/vm/NN-*.sh`, scapy helpers) - `tests/` — VM suite (`tests/vm/NN-*.sh`, scapy helpers)
- `docs/en/` + `docs/pt-BR/` — full bilingual documentation - `docs/en/` + `docs/pt-BR/` — full bilingual documentation
+46 -18
View File
@@ -1,13 +1,29 @@
# PF no Linux # PF no Linux
Port do **PF** (packet filter) do OpenBSD para o **Linux 7.3.4** como módulos Port do **PF** (packet filter) do OpenBSD para o **Linux 7.3.4** como um
out-of-tree — o engine PF real (`pf.c`, `pf_norm.c`, `pf_table.c`, `pf_lb.c`, … módulo de kernel out-of-tree — o engine PF real (`pf.c`, `pf_norm.c`,
portados dos fontes do OpenBSD 8.0) controlado pelo `pfctl` real do OpenBSD via `pf_table.c`, `pf_lb.c`, … portados dos fontes do OpenBSD 8.0) controlado
a ABI ioctl de `/dev/pf`. pelo `pfctl` real do OpenBSD via a ABI ioctl de `/dev/pf`. (Um segundo
módulo para o qdisc `pfq` chega com o M5.)
**Status:** implementação em andamento — veja o **Status:** milestones iniciais. O engine portado e o plano de controle (M1)
[plano de implementação](docs/superpowers/plans/2026-11-11-pf-linux-port.md) e o funcionam; o núcleo de filtragem do M2 está em validação na bancada de VMs;
[design doc](docs/superpowers/specs/2026-11-11-pf-linux-port-design.md). todo o resto está pendente. Status honesto por feature:
[`docs/pt-BR/feature-matrix.md`](docs/pt-BR/feature-matrix.md).
Design: [`docs/superpowers/specs/2026-11-11-pf-linux-port-design.md`](docs/superpowers/specs/2026-11-11-pf-linux-port-design.md)
· plano: [`docs/superpowers/plans/2026-11-11-pf-linux-port.md`](docs/superpowers/plans/2026-11-11-pf-linux-port.md).
## Milestones
| Milestone | Escopo | Status (2026-11-11) |
|---|---|---|
| M0 | repo, scripts, build do kernel, VM sobe com kernel próprio | concluído |
| M1 | camada de compat, `pf.ko` carrega, `/dev/pf`, `pfctl -f` / `-s info` | concluído |
| M2 | núcleo de filtragem: regras/estados/tabelas/anchors, gates VM 01–04 | **em andamento** — caminho de dados implementado, gates ainda não todos verdes |
| M3 | NAT (nat/rdr/binat), scrub e2e, pflog | pendente |
| M4 | route-to/dup-to/fail-to, divert e2e | pendente |
| M5 | filas: back ends HFSC/FQ-CoDel + qdisc `pfq` | pendente |
| M6 | docs completas, patchset arrumado, suíte inteira verde, release com tag | em andamento (docs) |
## O que você obtém (planejado) ## O que você obtém (planejado)
@@ -18,7 +34,7 @@ a ABI ioctl de `/dev/pf`.
| NAT | `nat-to` (pools de portas, sticky-port, static-port), `rdr-to`, `binat-to` | | NAT | `nat-to` (pools de portas, sticky-port, static-port), `rdr-to`, `binat-to` |
| Scrub | remonta­gmento de fragmentos, drop por overlap, `min-ttl`/`max-mss`/`df`/`no-df`, `set reassemble` | | Scrub | remonta­gmento de fragmentos, drop por overlap, `min-ttl`/`max-mss`/`df`/`no-df`, `set reassemble` |
| QoS (sucessor do ALTQ) | `queue`/`queue on` com os agendadores `ifq` do OpenBSD 8.0: **default (priq), HFSC, FQ-CoDel**, anexados via qdisc `pfq`; estatísticas `pfctl -s queue -v` | | QoS (sucessor do ALTQ) | `queue`/`queue on` com os agendadores `ifq` do OpenBSD 8.0: **default (priq), HFSC, FQ-CoDel**, anexados via qdisc `pfq`; estatísticas `pfctl -s queue -v` |
| Divert | `divert-to` / tag `divert` + canal userspace `pdivert` (netlink; Linux não tem `AF_DIVERT`) | | Divert | `divert-to` / tag `divert` + relay `pdivert` sobre uma família de sockets `PF_DIVERT` dentro do módulo (pendente — ver `docs/pt-BR/feature-matrix.md`) |
| Roteamento | `route-to` (pools rr/hash-source/hash-state, `fail-to`), `reply-to`, `dup-to` | | Roteamento | `route-to` (pools rr/hash-source/hash-state, `fail-to`), `reply-to`, `dup-to` |
| Logging | `pflogd` via canal netlink pflog (pcap DLT_PFLOG) | | Logging | `pflogd` via canal netlink pflog (pcap DLT_PFLOG) |
| Controle | `/dev/pf` (0600), ABI ioctl do OpenBSD 8.0, `pfctl` compilado para Linux (binário único) | | Controle | `/dev/pf` (0600), ABI ioctl do OpenBSD 8.0, `pfctl` compilado para Linux (binário único) |
@@ -27,24 +43,36 @@ Fora de escopo: failover `pfsync`/CARP, IPsec/pfkey, `ftp-proxy`, instâncias PF
por netns, agendadores exclusivos do ALTQ clássico (cbq/wfq/red — removidos do por netns, agendadores exclusivos do ALTQ clássico (cbq/wfq/red — removidos do
OpenBSD antes da 8.0). OpenBSD antes da 8.0).
## Início rápido (após M1+) ## Início rápido
Receita completa: [`docs/pt-BR/install.md`](docs/pt-BR/install.md). Versão
curta (comandos lidos dos scripts; a execução de ponta a ponta a partir de
clone limpo ainda está pendente):
```sh ```sh
./scripts/fetch-sources.sh # fontes OpenBSD 8.0 (mirror C3SL, com checksum) ./scripts/fetch-sources.sh # fontes OpenBSD 8.0 (mirror C3SL, sha256 fixado)
./scripts/apply-patches.sh ../linux-7.3.4 # patch(es) de core (exports) ./scripts/vendorize.sh # staging dos arquivos upstream portados
make module tools # pf.ko, pfq.ko, pfctl, pdivert, pflogd ./scripts/build-kernel.sh # kernel 7.3.4: bzImage + modules_prepare (patch de export: nenhum necessário)
sudo insmod module/pf.ko module/pfq.ko ./scripts/build-module.sh # -> module/pf.ko
make -C tools # -> tools/out/pfctl (estático), verificador de ABI
sudo insmod module/pf.ko # /dev/pf (0600) + hooks netfilter
sudo pfctl -f /etc/pf.conf && sudo pfctl -e sudo pfctl -f /etc/pf.conf && sudo pfctl -e
``` ```
Lab de validação em VMs (Alpine via libvirt): `docs/pt-BR/vm-lab.md`. Leia [`docs/pt-BR/pf-guide.md`](docs/pt-BR/pf-guide.md) **antes** de habilitar
Documentation in English: [`README.md`](README.md) and `docs/en/`. o PF num caminho que você precisa: só o núcleo de filtragem do M2 tem gate
hoje; NAT/scrub/filas/divert/pflog ainda não são utilizáveis
([`docs/pt-BR/feature-matrix.md`](docs/pt-BR/feature-matrix.md)).
Lab de validação em VMs (Alpine via libvirt): [`docs/pt-BR/vm-lab.md`](docs/pt-BR/vm-lab.md).
English documentation: [`README.md`](README.md) e
[`docs/en/`](docs/en/README.md).
## Estrutura ## Estrutura
- `module/` — fontes de kernel (PF portado + camada de compat + qdisc pfq) - `module/` — fontes de kernel (PF portado + camada de compat; o qdisc `pfq` chega com o M5)
- `tools/` — builds Linux de pfctl/pdivert/pflogd - `tools/` — pfctl (build estático Linux), fonte do relay pdivert, verificador de ABI (`pflogd` ainda não portado)
- `patches/kernel/` — patches documentados no core do Linux (apenas exports) - `patches/kernel/` — conjunto de patches de core do Linux (hoje vazio; evidência em `p1-needs.txt`, ver `docs/pt-BR/patches.md`)
- `scripts/` — automação de fetch/build/patch/VM - `scripts/` — automação de fetch/build/patch/VM
- `tests/` — suíte em VM (`tests/vm/NN-*.sh`, helpers scapy) - `tests/` — suíte em VM (`tests/vm/NN-*.sh`, helpers scapy)
- `docs/en/` + `docs/pt-BR/` — documentação completa bilíngue - `docs/en/` + `docs/pt-BR/` — documentação completa bilíngue
+36
View File
@@ -0,0 +1,36 @@
# PF-on-Linux documentation (English)
Documentação em português: [`docs/pt-BR/README.md`](../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`, …) 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](guide.md) | One-page architecture: components, data path, control plane, milestones |
| [install.md](install.md) | Apply/build/install recipe (kernel, module, tools) |
| [build.md](build.md) | Build pipeline in detail: fetch → vendorize → kernel → module → pfctl |
| [vm-lab.md](vm-lab.md) | The libvirt validation lab: topology, recreate/run, what each gate proves |
| [feature-matrix.md](feature-matrix.md) | Per-feature status: VERIFIED-in-VM / COMPILES-untested / PENDING-Mx |
| [pf-guide.md](pf-guide.md) | Daily use: what works today in `/etc/pf.conf`, what to avoid until M3/M4 |
| [patches.md](patches.md) | Linux core patch set (currently empty) + rules and template for future `000N-*.patch` |
| [caveats.md](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` — design
- `docs/superpowers/plans/2026-11-11-pf-linux-port.md` — milestone plan (tasks T1–T19)
- `docs/porting-notes.md` — staging log + M1 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 (see vm-lab.md).
- **COMPILES-untested** — the code is built into `pf.ko` but no gate has proven the behavior yet.
- **PENDING-Mx** — lands (or lands fully) in milestone Mx; current observable behavior is documented.
+116
View File
@@ -0,0 +1,116 @@
# Build pipeline in detail
Português: [docs/pt-BR/build.md](../pt-BR/build.md).
Quick recipe: [install.md](install.md). This page explains *what each stage
does* and *what has actually been exercised*.
Everything below runs on the build host (the laptop); the VM lab (separate
host "deb") only receives artifacts — see [vm-lab.md](vm-lab.md).
## 0. Prerequisites
From `docs/en/install.md`: gcc ≥ 15, GNU make, bison (flex is not needed —
OpenBSD `parse.y` carries a hand-written `yylex`), `bc`, rsync, `glibc-static`
for the static pfctl, root for `insmod`. Kernel tree expected at
`../linux-7.3.4` (override with `KERNELDIR=`; the root `Makefile` defaults to
`$(HOME)/lab/linux_kernel/linux-7.3.4`).
## 1. Fetch + verify OpenBSD sources — `scripts/fetch-sources.sh`
- Downloads `sys.tar.gz` and `src.tar.gz` from the primary mirror
`https://openbsd.c3sl.ufpr.br/pub/OpenBSD/8.0/`, falling back to
`cdn.openbsd.org`.
- Verifies sha256 against the pins in `VERSIONS` (sys: `964b1aed…`, src:
`9984c74f…`); an already-cached tarball is skipped when its hash matches.
- Landing zone: `_vendor/openbsd/` (gitignored).
## 2. Vendorize — `scripts/vendorize.sh`
Extracts **only the files the port consumes** into `_vendor/upstream/`
(gitignored): the `sys/net/pf*.c|h`, `ifq/hfsc/fq_codel/ip_pflog/ip_divert`,
`radix/rtable/toeplitz`, `crypto/{md5,sha2,siphash}`, `sys/sys/*.h` list and
`sbin/pfctl/*` + headers (see the `SYS_K`/`SRC_K` arrays). It then records
each file's `$OpenBSD: …$` tag into `_vendor/upstream/IDS.txt` — the forensic
baseline for every ported line and for future rebases.
## 3. Staging into the port — `scripts/stage-port.sh` (deterministic porting)
`stage-port.sh` turns pristine upstream files into the files under `module/`:
1. every `#include` is replaced by `pfk.h` + the staged `pfvar` headers
(kernel branches selected with `-D_KERNEL=1`);
2. the shared rename program (`pf_sed`) resolves BSD↔Linux name collisions
(`struct ip` → `struct pf_ip`, `ifnet` → `pfk_ifnet`, `ip_output` →
`pfk_ip_output`, `sa_len` assignments stripped, …);
3. **each run is appended to `docs/porting-notes.md`** — that file is the
staging log, not prose.
Ported files are then committed and hand-edited in-tree; re-staging is only
for forensics (`stage-port.sh --diff <file>` compares our copy against the
pristine upstream text). Radix/rtable/siphash/toeplitz are deliberately not
auto-staged (hand-ported).
## 4. Kernel — `scripts/build-kernel.sh` (+ `kernel-config.sh`)
- `kernel-config.sh`: starts from `defconfig` if there is no `.config`, then
sets (idempotently, via `scripts/config` + `make olddefconfig`):
`VIRTIO_BLK/PCI/NET=y`, `EXT4_FS=y`, `NETFILTER=y`, `NETFILTER_ADVANCED`,
`NET_SCHED=y`, `INET=y`, `IPV6=y`, `SERIAL_8250(+CONSOLE)=y` — i.e.
everything needed to direct-boot the pf0 VM with **no initrd**.
`kernel-config.sh test` additionally enables `DEBUG_INFO` +
`DEBUG_KMEMLEAK` for soak builds.
- `build-kernel.sh`: `make -j(nproc-2) bzImage modules_prepare`, ensures
`Module.symvers` (copies `vmlinux.symvers` — kbuild does not write the
former) and `scripts/module.lds` exist, then drops boot artifacts in
`out/`: `linux-<ver>-bzImage`, `System.map`, `.config`, `kernelversion`,
`bzImage.sha256`. Prints `KERNEL_BUILD_OK <kernelrelease>`.
- **Kernel core patches are currently none**: `patches/kernel/` holds no
`000N-*.patch` (see [patches.md](patches.md)).
## 5. Module — `scripts/build-module.sh`
`make -C "$KERNELDIR" M=module` → `module/pf.ko` (single module today; the
`pfq` qdisc arrives with M5). The script self-prepares `Module.symvers` /
`modules_prepare` first. Object list (`module/Makefile`): ported engine
(`pf.c`, `pf_ioctl.c`, `pf_norm.c`, `pf_if.c`, `pf_lb.c`, `pf_ruleset.c`,
`pf_table.c`, `pf_osfp.c`, `pf_syncookies.c`, `divert_sock.c`) + compat layer
(mbuf shim, kern glue, if/ip4/ip6/pcb/xmit/ifq, crypto, radix, subr_tree) +
`pfk_mod.c`/`pfk_hooks.c`. Compile flags define `PFLINUX=1` and `_KERNEL=1`.
Prints `MODULE_BUILD_OK`.
`insmod module/pf.ko` creates `/dev/pf` (0600) and registers the netfilter
hooks; `dmesg` shows `pfk: …` lines (see [caveats.md](caveats.md) for what
the data path does).
## 6. Userland — `make -C tools`
Targets (from `tools/Makefile`): `pfctl`, `abitest`, `abi`, `test`, `clean`.
- `pfctl` — the OpenBSD 8.0 sources compiled against the copied ABI headers;
result is a **static binary** at `tools/out/pfctl`. Every deviation from
upstream is listed in `tools/UPSTREAM.md` (7 marked edits; the rest is the
compat header/source set).
- `abi` — builds `abitest` (userland) and `abitest-module` (same table under
kernel compat headers), dumps both struct-size/offset tables and `diff`s
them; a mismatch means the ioctl ABI drifted. `out/abi-*.tbl` are the
reference inputs.
- `test` — offline parse checks: runs `pfctl -n -f` over `tools/tests/*.conf`
(basic / translations / queues+scrub / anchor / negative `broken.conf`).
This is pure userland; it needs no `/dev/pf`.
- `pdivert` — divert relay source under `tools/pdivert/`; see
[feature-matrix.md](feature-matrix.md) for its (pending) kernel side.
## 7. Root `Makefile`
`make module | tools | kernel | vm | vm-destroy | test | docs | clean` — thin
wrappers over the scripts above. `make test` runs the VM suite
([vm-lab.md](vm-lab.md)); `make docs` just lists the bilingual doc set.
## What has been exercised vs. not
- Stages 1–6 have each been run during M0–M2 development on the build host
(artifacts exist in-tree: `out/`, `module/pf.ko`, `tools/out/pfctl`), and
the scripts above were verified line-by-line for this document.
- A **fresh-clone end-to-end run** (`quickstart-check.sh`, plan task T19) has
*not* been executed yet; treat the exact command sequence in install.md as
"as designed, last-run state per milestone" rather than CI-verified.
+137
View File
@@ -0,0 +1,137 @@
# Caveats — divergences from OpenBSD behavior
Português: [docs/pt-BR/caveats.md](../pt-BR/caveats.md).
These are the ways this port differs from running the same ruleset on
OpenBSD 8.0, or is not yet production-shaped. Everything here is grounded in
the code (`module/pfsrc/pfk_hooks.c`, `module/pfsrc/pfk_mod.c`,
`docs/porting-notes.md`) and in lab observations; nothing is speculative.
## Data path
### 1. PF runs in process context via a workqueue (netisr model), not in the packet fast path
OpenBSD evaluates `pf_test()` on the CPU that received the packet, at
`IPL_NET`, with a non-sleeping NET read lock. Linux gives us softirq context
and *sleepable* compat locks (rw-semaphores), so the hook never calls
`pf_test()` inline: it steals the skb (`NF_STOLEN`) onto an **ordered
workqueue** (`pfk_netisr`, `WQ_MEM_RECLAIM`) and runs the engine in process
context, then re-injects (`netif_rx()` for input, `dst->output()` for
output/transit).
Consequences, all observable:
- **Verdicts are asynchronous.** Anything chained after our hook on the same
netfilter chain (other iptables/nft rules at higher priorities) does not
see the packet until the reinjected pass comes through. Counters and log
interleaving differ accordingly.
- **Latency + throughput**: every packet takes a work-queue round trip
serialized on one ordered worker. Functional gates are the current bar;
the planned `bench-basic.sh` is informational only.
- **Reordering**: the ordered queue preserves arrival order of *queued*
work items, but the stack around it (RPS, multi-NAPI) can still hand us
packets whose original completion order differs from reinjection order.
### 2. Re-entry protection is a per-direction tag in `skb->mark`
The reinjected survivor carries `skb->mark |= PFK_DONE_IN (0x50460010)` or
`PFK_DONE_OUT (0x50460020)`; our hooks accept any packet already tagged for
that direction instead of re-queuing it (otherwise PF_IN → netif_rx →
PF_IN… would loop). `skb->mark` is a **shared, writable 32-bit field**: any
subsystem that *overwrites* it — nft `meta mark set`, `CONNMARK --restore`,
tc filters, some VPN stacks — can either (a) clear our tag and cause the
packet to be **re-queued through PF again**, or (b) coincidentally set those
bits and let a packet **skip** a PF pass. Practical rule on a PF-on-Linux
host: do not use fwmark mangling on the same traffic; if you must, mask the
PF tag bits out of your mark space.
### 3. No NET-lock on the data path (M2 interim)
`pf_test()` currently runs **without** the compat NET read lock (comment in
`pfk_hooks.c`): with the workqueue model, a parked control writer (ruleset
change, purge ioctl) starved the packet side badly enough to be
counter-productive. Rule-set mutation and packet walk therefore run
concurrently, protected by what upstream `pf.c` itself uses (PF_LOCK/RCU-ish
patterns) — a deliberate interim deviation being reworked with the lock
model in M5+. Until then: expect correctness under steady state, not under
aggressive concurrent reload; the reload-under-traffic soak is an open gate.
### 4. Fail-open under memory pressure
The queue item is `kmalloc(GFP_ATOMIC)` in softirq. If it fails, the hook
returns `NF_ACCEPT` — the packet **bypasses PF**. This is a deliberate
availability choice (mirrors dropping into a full queue bypassing the qdisc)
but it is a security trade-off worth knowing: PF verdicts are best-effort
exactly when the host is out of atomic memory.
### 5. Hook ordering vs conntrack differs by direction
- Ingress (`PREROUTING`, `NF_IP_PRI_FIRST`): PF runs **before** defrag and
conntrack — as designed (spec §4.2).
- Output (`LOCAL_OUT` at `NF_IP_PRI_CONNTRACK+1`): PF sees locally generated
traffic **after** conntrack has already committed the entry.
- Transit egress (`POSTROUTING` at `NF_IP_PRI_LAST-1`): PF runs at the very
end — after any iptables/nft SNAT/masquerade — so `pass out … nat-to`-era
rules (M3) will be validated against this ordering. The "unregister-safe
ordering vs conntrack" warning from the design still applies: overlapping
policy between PF and conntrack is possible and yours to manage.
## Control plane / lifecycle
### 6. Unload is hardened; the soak is still pending
`rmmod pf` deregisters `/dev/pf`, zeroes `pf_status.running` under the NET
lock, deletes **and syncs** both purge timers (they self-rearm — a real rmmod
hang was observed and fixed by stopping sources before flushing the
workqueue), unregisters hooks and flushes `pfk_netisr`. That fix is in-tree,
but the full cycle under traffic + live states (T18/soak gate) has **not**
been run to green yet. For now treat unload as admin-safe, automation-
unproven.
## Behavioral / rendering issues open today
### 7. `pfctl -s states` visibility anomaly (M2 gate work)
In the most recent captured run (gate 01): transit ping **passed** under
`keep state`, but no icmp state was listed afterwards. Fixing this is the
open item of the M2 gate work; until a green run lands, the
[state-listing row](feature-matrix.md) is the honest status. Not cosmetic if
it turns out states are not being inserted — treat both possibilities until
the gate says otherwise.
### 8. Silent-but-warned stubs
`divert` verdicts drop with a rate-limited warning; `log` rules log nothing
with a one-time warning. Both are listed so nobody mistakes "rules loaded"
for "features active" (see [pf-guide.md](pf-guide.md)).
## Compat-layer deviations (from `docs/porting-notes.md`, M1 record)
These are deliberate, marked-in-code divergences of the compat layer; they
matter when reasoning about rule semantics:
- **Socket-owner matching** (`user`/`pid` on rules): uid only — Linux `struct
sock` carries no egid/cpid, so gid degrades to `(gid_t)-1`, pid to
`NO_PID`.
- **Checksums**: driver offload is not trusted on ingress (M1 decision) —
TCP checksums are recomputed in software; output pseudo-checksums are done
in the port's own path.
- **IP options / record-route / timestamps**: not processed on the PF output
path; **ICMP redirects are not generated** by PF's route code (the Linux
FIB emits those).
- **Routing labels**: non-goal — the ioctl layer rejects labeled rules;
`rtable_iterate()` always returns NULL (no multipath uRPF iteration).
- **Interface groups**: Linux has none; `group …` matches behave like a
missing group on OpenBSD.
- **GSO/multi-segment skbs**: handled by linearization on entry to the mbuf
shim (perf cost documented in spec §10; gates will quantify).
- **Single instance**: one PF world in `init_net`, like OpenBSD has one
kernel. Containers/namespaces are not visible to PF and cannot be filtered
with it in this design.
## What is *not* a caveat
ARP and other non-IPv4/IPv6 EtherTypes never enter the netfilter IPv4/IPv6
hooks — they pass through the box untouched, exactly as PF on OpenBSD ignores
non-IP. `/dev/pf` is 0600 root-only by design (matches OpenBSD's
`securelevel`-era default for `pfctl` write access being root).
+41
View File
@@ -0,0 +1,41 @@
# Demo (asciinema)
The lab can be recorded as an [asciinema](https://asciinema.org) cast. Every
byte in the recording is the real output of the lab VMs (Alpine under libvirt
running the kernel built from source with `pf.ko`); only the pacing is
scripted.
## Record
```sh
pip install asciinema # once
bash scripts/vm-run-tests.sh # or: scripts/vm-create.sh + deploy
asciinema rec out/demo-pf-linux.cast -c "bash scripts/demo-session.sh"
```
The session walks through:
1. the lab topology and the freshly loaded `pf.ko` (`dmesg` proof),
2. `pfctl -s info` over the OpenBSD ioctl ABI,
3. a real `pf.conf` (table, stateful rules, explicit drop) and `pfctl -sr`,
4. transit ping + `pfctl -ss` (stateful),
5. `pfctl -t <table> -T show` (live tables),
6. a blocked ping (counters with `pfctl -sr -vv`),
7. `divert-to` with the `pdivert` relay (packet to userspace and back),
8. shutdown.
## Play back
```sh
asciinema play out/demo-pf-linux.cast
```
## Upload
```sh
asciinema upload out/demo-pf-linux.cast
```
`scripts/demo-record.py` is an alternative recorder that produces the same
asciicast v2 format without the asciinema binary (it drives the lab over
ssh and writes the cast itself).
+78
View File
@@ -0,0 +1,78 @@
# Feature matrix
Português: [docs/pt-BR/feature-matrix.md](../pt-BR/feature-matrix.md).
Status vocabulary (used identically in both languages):
- **VERIFIED-in-VM** — passed end-to-end in the libvirt lab (see [vm-lab.md](vm-lab.md)).
- **M2-in-progress** — implemented; VM gates 01–04 exist but the suite is **not all green yet**; no VERIFIED claim until a clean full run.
- **COMPILES-untested** — built into `pf.ko`/`pfctl`; no gate has exercised it.
- **PENDING-Mx** — lands in milestone Mx; today's observable behavior is stated.
- **OUT-OF-SCOPE** — non-goal by design (spec §3).
As of 2026-11-11; source of per-row evidence: `out/test-logs/`,
`docs/porting-notes.md`, milestone commits.
## Control plane & tools
| Feature | Upstream syntax | Milestone | Status |
|---|---|---|---|
| Module load, `/dev/pf` (0600) | `insmod pf.ko` | M1 | VERIFIED-in-VM |
| Enable/disable | `pfctl -e`, `pfctl -d` | M1 | VERIFIED-in-VM |
| Ruleset load | `pfctl -f file` | M2 | VERIFIED-in-VM (loads succeeded in every captured gate run; run status itself is mixed — see [vm-lab.md](vm-lab.md) §6) |
| Parse-only check | `pfctl -n -f file` | M1 | VERIFIED (offline fixture suite, `make -C tools test`) |
| Status/counters | `pfctl -s info [-v]` | M1 | VERIFIED-in-VM |
| Rules listing | `pfctl -s rules [-v]` | M2 | COMPILES-untested |
| States listing | `pfctl -s states [-v]` | M2 | M2-in-progress — gate 01 shows a listing anomaly (transit ping OK, no icmp state displayed) while state machinery is being fixed |
| Tables listing/ops | `pfctl -s tables`, `-t t -T show/add/del/kill` | M2 | M2-in-progress (gate 03) |
| Anchors | `pfctl -a anchor -f file`, `-s Anchors` | M2 | M2-in-progress (gate 04) |
| Queue listing | `pfctl -s queue -v`, `-s ifq -v` | M5 | PENDING-M5 (parses fine; counters not wired to real back ends yet) |
| ioctl ABI parity | `make -C tools abi` (abitest tables) | M1 | VERIFIED build-side (userland table); kernel-side diff is an open integrator step (`tools/UPSTREAM.md`) |
## Filtering core
| Feature | Upstream syntax | Milestone | Status |
|---|---|---|---|
| `pass`/`match`, quick, on-interface/proto/addr/port | `pass in quick on wan proto tcp from 10/8 to port 80` | M2 | M2-in-progress (data path runs the real `pf_test`; latest partial run: transit ping OK, icmp block OK) |
| `block drop` | `block drop in quick …` | M2 | M2-in-progress (gate 02a) |
| `block return` / `return-rst` / `return-rst after quarter` | `block return-rst in quick proto tcp …` | M2 | M2-in-progress (gate 02b) |
| `keep state` (icmp/tcp/udp), state table, purger | `… keep state` | M2 | M2-in-progress |
| `set state-policy`, `allow-opts`, etc. | `set …` options | M2 | COMPILES-untested |
| Syncookies (state overflow path) | `set syncookies always` | M2 | COMPILES-untested |
| pfr tables (radix/hash) | `table <blk> persist { 1.2.3.4 }`, `-T add …` | M2 | M2-in-progress (gate 03) |
| Anchors + include + quick precedence | `anchor "x"`, `load anchor …` | M2 | M2-in-progress (gate 04) |
| IPv6 for all of the above | same syntax, v6 | M2+ | COMPILES-untested (engine is v6-complete by construction; v6 smoke gates planned) |
| Non-IPv4/IPv6 traffic (ARP…) | — | M2 | PFLINUX by construction: netfilter IPv4/IPv6 hooks only — ARP never enters PF path (no gate yet) |
## NAT / normalization (M3)
| Feature | Upstream syntax | Milestone | Status |
|---|---|---|---|
| `nat-to` (port pools, sticky-port, static-port) | `pass out … nat-to (eth1:0)` | M3 | **VERIFIED in lab** — source NAT works end to end: the packet leaves with the pool address (tcpdump proof), the reply is de-NATed and re-routed to the client, and the state shows both tuples (`10.0.2.1:59335 (10.0.1.10:4380) -> 10.0.2.20:8`). Gate: `tests/vm/05-nat.sh`. |
| `rdr-to` | `pass in … to <fw> port 8080 rdr-to <srv> port 80 keep state` | M3 | **VERIFIED in lab** — port redirect works end to end (gate `06-rdr.sh`): the client talks to the firewall's address, pf rewrites the destination, re-routes the packet, and the reply is un-redirected. The gate also pulls 2 MB through the redirect and checks byte-for-byte integrity (GSO/TSO regression guard). |
| `binat-to` | `binat-to <net>` (no direction) | M3 | PENDING-M3 — parser accepts the 8.0 form (`binat-to` is a rule option, not a standalone rule); VM gate not written yet. |
| Scrub/normalize: reassembly, `fragment drop-overlap`, `min-ttl`, `max-mss`, `df`/`no-df`, `random-id`, `set reassemble yes` | `match on all scrub (max-mss 1380 …)` | M3 | COMPILES-untested (`pf_norm.c` compiled into pf.ko and reached from `pf_test`; scapy gate 08 pending) |
| OS fingerprinting in states | `pass … set os A` + `/etc/pf.os` | bonus | COMPILES-untested (`pf_osfp.c` compiled; no fingerprint packaging yet — missing `/etc/pf.os` is tolerated) |
## Routing / divert / queues / logging
| Feature | Upstream syntax | Milestone | Status |
|---|---|---|---|
| `route-to` pools (`rr`, `round-robin`, `source-hash`, `hash`), `reply-to`, `dup-to`, `fail-to` | `pass out route-to (GW 10.0.3.2)` | M4 | PENDING-M4 (Linux route/neigh glue `pf_route` not implemented yet) |
| `divert-to` / `divert` tag | `pass in … divert-to <host> port <n>` | VERIFIED in lab | **Works end-to-end.** The module registers an `AF_DIVERT` socket family (`PF_DIVERT=32`) at runtime — no kernel-tree patch. A `divert-to` rule hands the packet to that family; with no listener the packet is dropped (`divs_noport`, BSD parity); with `tools/pdivert` running the packet is delivered to userspace, rewritten and reinjected (verified with a payload mutation + checksum fix, ping 0% loss). |
| Queues, default scheduler (priq) | `queue root on wan`, `pfctl -s queue -v` | M5 | COMPILES-untested — `compat/pfk_ifq.c` implements the ifq API with **priq fallback semantics**; `queue` rules parse and load, but packets are not actually shunted through a classful qdisc until M5 |
| HFSC | `queue on wan { hfsc … }` | M5 | COMPILES-untested — **priq fallback until M5**; `pfsrc/hfsc.c` staged (real OpenBSD 8.0 code) but **not in the module object list** |
| FQ-CoDel | `queue on wan { fq_codel … }` | M5 | COMPILES-untested — same as HFSC: staged, not built |
| `pfq` qdisc (`tc qdisc … root pfq`) | n/a (Linux glue) | M5 | PENDING-M5 (does not exist in the tree yet) |
| pflog (`log`, `log all`, `block log`) + `pflogd` pcap (DLT_PFLOG) | `pass out quick log` + `pflogd /tmp/x.pcap` | M4 | **VERIFIED in lab** — gate `12-pflog.sh`: logged packets are queued by the engine, read through `/dev/pflog` and written as a pcap with linktype DLT_PFLOG (117); the dump contains the real packet bytes. Deviation: a chardev instead of an if_pflog/bpf interface (Linux has no bpf over such a virtual interface here); record layout is byte-compatible with OpenBSD `pflog(4)`. `if_pflog.c` stays unbuilt. |
## Non-goals (explicit)
| Item | Reason |
|---|---|
| `pfsync` / CARP failover | non-goal (spec §3) |
| IPsec / pfkey | non-goal |
| `ftp-proxy` and userland daemons | non-goal |
| Per-netns PF instances | faithful port = single global instance on `init_net` |
| Classic-ALTQ-only schedulers (cbq/wfq/red…) | removed upstream before OpenBSD 8.0 — cannot be ported from the base |
| Routing labels (`route-label`) | non-goal; ioctl layer rejects labeled rules |
+101
View File
@@ -0,0 +1,101 @@
# Architecture guide — one page
Português: [docs/pt-BR/guide.md](../pt-BR/guide.md).
## What this port is
A faithful port of the **OpenBSD 8.0 PF engine** running inside **Linux
7.3.4** as one out-of-tree module, `pf.ko`. Nothing is faked: the matching,
state, table, normalization and queueing code *is* OpenBSD's, compiled under a
compatibility layer; control comes from the real `pfctl` speaking the real
OpenBSD ioctl ABI through `/dev/pf`. There is **one global PF instance bound
to `init_net`** — exactly like OpenBSD has one kernel; per-netns instances are
out of scope.
Build targets: OpenBSD 8.0 sources (sha256-pinned, `VERSIONS`), Linux 7.3.4
(`linux-7.3.4`), `gcc >= 15`, bison. `pfvar.h` v1.548 is shared bit-for-bit
between kernel and userland (ioctl encoding per `module/include/pfk.h`).
## Components
| Path | Role |
|---|---|
| `module/pfsrc/` | Ported OpenBSD files: `pf.c` (engine), `pf_ioctl.c` (DIOC* ABI), `pf_norm.c` (scrub/fragments), `pf_table.c`, `pf_ruleset.c`, `pf_if.c`, `pf_lb.c` (pools/NAT ports), `pf_osfp.c`, `pf_syncookies.c`, `ifq.c`/`hfsc.c`/`fq_codel.c` (staged for M5), `if_pflog.c` + `ip_divert.c` (staged references), `divert_sock.c` (divert entry stub), `pfk_mod.c` (load/exit, `/dev/pf`), `pfk_hooks.c` (netfilter data path) |
| `module/compat/` | Linux plumbing under the BSD-shaped sources: mbuf-over-`sk_buff` shim (`pfk_mbuf`), kernel glue (malloc/pools/timeouts/locks, `pfk_kern`), interface+address views (`pfk_if`), BSD-semantics IP output/forward (`pfk_ip4`, `pfk_ip6`), socket lookups (`pfk_pcb`), ifq API with priq semantics (`pfk_ifq`), radix/route-table/crypto ports |
| `module/include/` | `pfk.h` (master compat header + OpenBSD-style `_IO*` encoding), staged `net/pfvar.h`, `pfk_mbuf.h`, `pfk_net.h`, `pfk_if.h` |
| `tools/` | Linux build of OpenBSD 8.0 `pfctl` (single binary), `pdivert` relay, ABI parity harness (`abitest` + `make abi`), offline parse tests (`make test`). Deltas vs upstream: `tools/UPSTREAM.md` |
| `scripts/` | `fetch-sources.sh`, `vendorize.sh`, `stage-port.sh` (deterministic staging), `build-kernel.sh`, `build-module.sh`, `vm-*.sh` lab automation |
| `tests/vm/` | VM suite gates `01-state.sh … 04-anchors.sh` + `lib.sh`; `tests/confs/` rulesets deployed to the lab |
| `patches/kernel/` | Core patch set — currently **empty** (`p1-needs.txt` records why no exports were needed); see [patches.md](patches.md) |
## Data path (M2, as implemented today)
OpenBSD runs PF at `IPL_NET` in process-ish context; our compat locks are
sleepable, so the hook **never calls `pf_test()` in softirq**. Packets are
stolen onto an ordered workqueue (`pfk_netisr`) and the verdict is applied by
re-injection, tagged per direction via `skb->mark` so the survivor is not
re-queued by our own hook.
```
Linux 7.3.4, module pf.ko
NIC ──► netfilter (softirq — enqueue only)
PRE_ROUTING PF_IN ─┐ ┌─ LOCAL_OUT PF_OUT
POST_ROUTING PF_OUT ─┤ NF_STOLEN ├─ (runs AFTER conntrack)
LOCAL_IN/FORWARD: pass-through ┘ POST_ROUTING: NF_IP_PRI_LAST-1
│ (skb ref + kmalloc pfk_pkt;
│ alloc failure ⇒ NF_ACCEPT = fail-open)
▼
pfk_netisr workqueue (process context)
│
pfk_m_wrap_skb(skb)──► struct mbuf shim
│
pf_test(af, dir, ifp, &m) ◄── the real OpenBSD 8.0 engine:
│ scrub/normalize → state lookup
│ → rules/anchors/tables/quick
│ → state insert → verdict
▼
pass ──► mark |= PFK_DONE_IN/OUT ──► reinject: PF_IN: netif_rx() (survivor
of reassembly allowed through)
PF_OUT: skb_dst()->output()
block/drop ──► kfree_skb() (+ PF's own return-rst/ICMP generation)
fragment-buffered ──► our reference dropped; pf keeps the survivor (m == NULL)
```
Control plane: `/dev/pf` (miscdev, mode 0600, write gated on `CAP_NET_ADMIN`)
→ `pfk_ioctl_io()` copies the parameter struct sized from the OpenBSD `_IOR/
_IOW` encoding, dispatches into the ported `pfioctl()` (`pf_ioctl.c`) — the
full DIOC* ABI as upstream. `pfctl -e/-f/-s/-t` are that same OpenBSD binary,
rebuilt.
## Queues, divert, pflog — today's observable behavior
- **Queues**: `pfctl` parses `queue`/`queue on` (8.0 syntax); kernel-side the
ifq API is implemented by `compat/pfk_ifq.c` with **priq semantics only**;
the `pfq` classful qdisc and the HFSC/FQ-CoDel back ends land in **M5**.
`ifq.c`/`hfsc.c`/`fq_codel.c` are staged and compile-ready but are not in
the module object list yet.
- **Divert**: `divert-to`/`divert` tag evaluate to PF's `PF_DIVERT` verdict;
`divert_packet()` (`pfsrc/divert_sock.c`) currently **drops the packet with
a rate-limited kernel log** because the AF_DIVERT socket family is not yet
instantiated. The `pdivert` relay (userspace) exists and expects
`socket(PF_DIVERT=32, SOCK_RAW, IPPROTO_DIVERT=254)`.
- **pflog**: `pflog_packet()` returns success but **logs nothing** (one-time
`pr_warn "packet not logged"`); `if_pflog.c` is staged, netlink back end is
M4/M5.
## Milestones (see feature-matrix.md for per-feature status)
| Milestone | Scope | Status (2026-11-11) |
|---|---|---|
| M0 | repo, scripts, kernel build, VM boots custom kernel | done |
| M1 | compat layer, `pf.ko` loads, `/dev/pf`, `pfctl -f`/`-s info` | done |
| M2 | filter core: rules/states/tables/anchors VM gates | **in progress** — data path implemented, gates 01–04 not all green yet |
| M3 | NAT (nat/rdr/binat), scrub e2e, pflog | pending |
| M4 | route-to/dup-to/fail-to, divert e2e | pending |
| M5 | queues: ifq back ends (hfsc/fq_codel) + `pfq` qdisc | pending |
| M6 | docs complete, patchset tidy, full suite green, tagged releases | in progress (this doc set) |
## Next reads
[build.md](build.md) → [vm-lab.md](vm-lab.md) → [pf-guide.md](pf-guide.md) →
[feature-matrix.md](feature-matrix.md) → [caveats.md](caveats.md).
+26
View File
@@ -74,3 +74,29 @@ Because the deliverable is an out-of-tree module, "applying the patch set"
(virtio/EXT4 =y) — no source files are modified unless a future milestone (virtio/EXT4 =y) — no source files are modified unless a future milestone
adds a documented `patches/kernel/000N-*.patch` (all such patches: one adds a documented `patches/kernel/000N-*.patch` (all such patches: one
section each in docs/en/patches.md with what/why/impact/revert). section each in docs/en/patches.md with what/why/impact/revert).
## 6. Notes on the steps above (2026-11-11)
- Step **2.3 is a documented no-op today**: the patch set is empty and
`scripts/apply-patches.sh` / `scripts/unpatch.sh` / `patches/kernel/series`
are not yet in the tree (they land with the first real core patch — see
[patches.md](patches.md)). You can safely skip 2.3.
- Step 2.4 builds `pfctl` and the ABI harness only (`make -C tools` targets:
`pfctl abitest abi test clean`). `pdivert` is present as a source file with
no Makefile target yet; `pflogd` is not ported.
- After 2.5, what you can actually *use* is the M2 filter core (pass/block/
quick/keep state/tables/anchors); NAT/scrub/queues/divert/pflog are gated
by later milestones — see the [feature matrix](feature-matrix.md) and read
[pf-guide.md](pf-guide.md) before enabling PF on a path you need.
## 7. Where to go next
| | |
|---|---|
| Architecture, one page | [guide.md](guide.md) |
| Build stages in detail | [build.md](build.md) |
| VM validation lab | [vm-lab.md](vm-lab.md) |
| Daily rulesets & warnings | [pf-guide.md](pf-guide.md) |
| Known divergences | [caveats.md](caveats.md) |
| Core patch mechanism | [patches.md](patches.md) |
| Doc index | [README.md](README.md) |
+73
View File
@@ -0,0 +1,73 @@
# Linux core patch set
Português: [docs/pt-BR/patches.md](../pt-BR/patches.md).
## Current status: EMPTY
The port requires **zero modifications to the Linux 7.3.4 core**. The design
(spec §5) anticipated one mandatory patch — **P1: export symbols needed by
the PF module** — but the M1 compile-port proved it unnecessary: modpost
reported **no undefined symbols** for `pf.ko`. The compat layer was written
against APIs the stock kernel already exports (`__inet_lookup_established`,
`__inet_lookup_listener`, `__inet6_lookup_established`,
`inet6_lookup_listener`, `__udp4_lib_lookup`, `__udp6_lib_lookup`,
`ip_route_output_flow`/`ip6_route_output_flags` via inline wrappers,
`icmp_send`, …). The evidence and the exact list live in
`patches/kernel/p1-needs.txt`, which also carries a **watch list**: e.g.
`tcp_v4_send_reset` would need an export only if userland RST helpers are
used.
`patches/kernel/` therefore contains no `000N-*.patch` today, and applying
the (empty) set is a no-op.
> Honest note: install.md and the design mention `scripts/apply-patches.sh`,
> `scripts/unpatch.sh` and `patches/kernel/series`. Those helpers are **not
> in the tree yet**; until they land, "apply the patch set" is by definition
> nothing to do. When a real patch is needed, the first commit that adds it
> MUST also add the two scripts and the `series` file (see rules below).
## The mechanism (how the set is meant to work)
- Every kernel-core change is a standalone file
`patches/kernel/000N-short-description.patch`, listed in order in
`patches/kernel/series`, applied to the pristine kernel tree with
`git apply`-style tooling and reverted the same way
(`unpatch.sh` reverse-applies).
- The tree must never be left dirty silently: builds that must be
reproducible apply, build, and record the state (`out/.config`,
`out/kernelversion`).
- Hard rules for any future patch:
1. **Additive, zero behavior change** (e.g. `EXPORT_SYMBOL_GPL()` lines
adjacent to existing export clusters). Anything that alters logic needs
a design-spec amendment first.
2. One concern per patch, numbered sequentially — never edit a landed
patch; supersede with a new number.
3. A section in this file (both languages) **before** the patch lands:
what/why/impact/revert + the VM evidence.
4. The patch must survive `make -C <kerneldir> bzImage modules` from a
clean tree (CI-of-the-lab: `vm-run-tests.sh` after a fresh boot).
## Template for a future `000N` entry
Copy this block into both `docs/en/patches.md` and `docs/pt-BR/patches.md`
(EN above the pt-BR file's same anchor) when adding `000N-*.patch`:
```
### 000N — <one-line title>
- File: `patches/kernel/000N-<slug>.patch`
- Status: landed (kernel 7.3.4) / superseded by 000M
- Touches: <file(s) in the kernel tree>, <n> added lines, 0 removed
- What: <exact symbols / hooks / Kconfig knobs added>
- Why: <which PF-on-Linux code needs it; why no exported API suffices>
- Impact: <runtime/ABI/memory impact on plain Linux; expected: none>
- Revert: `./scripts/unpatch.sh <kerneldir>` (reverse-apply); module
then fails to link with the missing symbol named in modpost output.
- Evidence: <VM run id / date / relevant gate output>
```
## Change log of this directory
| Date | Change |
|---|---|
| 2026-11-11 | P1 evaluated after M1 compile-port → **not needed**; `p1-needs.txt` records the evidence and the watch list. Set remains empty. |
+101
View File
@@ -0,0 +1,101 @@
# Using PF-on-Linux day to day
Português: [docs/pt-BR/pf-guide.md](../pt-BR/pf-guide.md).
This is the "what can I actually run today" guide. It follows the
[feature matrix](feature-matrix.md): **M2 scope (filtering core: pass/block/
quick/keep state/tables/anchors + enable/disable)** has VM evidence behind it;
everything beyond that is either COMPILES-untested or PENDING. Install/build
is covered by [install.md](install.md) and [build.md](build.md).
## Daily loop
```sh
sudo insmod module/pf.ko # creates /dev/pf
sudo pfctl -nf /etc/pf.conf # parse check (userland only — always safe)
sudo pfctl -f /etc/pf.conf # load ruleset
sudo pfctl -e # ENABLE — traffic starts hitting the ruleset NOW
sudo pfctl -s info # status + counters
sudo pfctl -s states # states listing (see caveat below)
sudo pfctl -t blk -T add 10.0.1.10 # live table update
sudo pfctl -a admin -f /etc/pf.d/admin.conf
sudo pfctl -d # disable
sudo rmmod pf # unload (rule/state flush happens here)
```
> **Warning — order matters**: `-f` then `-e`. Enabling with no matching `pass` rule
> for your admin path blocks it — this port follows OpenBSD's default-block
> policy, and the M2 gate runs have *actually cut the test VM's ssh* that
> way (the lab keeps a serial console for exactly this). On a remote host,
> pass your management interface before you enable anything.
## A ruleset that works in this port today
```pf
# /etc/pf.conf — M2 scope only. Interface names here match the VM lab
# (mgmt/lan/wan); substitute your own (eth0, enp1s0, …).
# 1) keep yourself reachable (do this first, always)
pass in quick on mgmt
pass out quick
# 2) filter core — proven today: quick, proto/port matching, state, drop
table <blk> persist # live blocklist (gate 03 pattern)
block in quick proto tcp from <blk> to any
pass in quick on lan proto tcp from 10.0.1.0/24 to any port { 80 443 } keep state
block drop in quick on wan proto icmp from any to any
# 3) anchors with precedence (gate 04 pattern)
anchor "admin"
```
Macros (`xif = "lan"`), nested `anchor "in/*"`, `label`, `tag`, `set
timeout/limit/state-policy/block-policy/skip` and the rest of the OpenBSD 8.0
grammar **parse** fine — `make -C tools test` exercises them offline — but
the *kernel behavior* of most `set` options has not been gate-verified yet;
treat them as load-and-pray until the matrix moves them.
## What to avoid until the milestones land
| Syntax | Until | What happens today |
|---|---|---|
| `nat-to`, `rdr-to` (`binat-to` pending) | — | **Verified in the lab** (gates `05-nat`, `06-rdr`, the latter pulls 2 MB through a redirect and compares it byte for byte). `nat-to (egress)` expands the OpenBSD interface *group*; on a multi-NIC host prefer the explicit `nat-to (<iface>)` form. |
| `scrub (…)`, `set reassemble` | M3 | `pf_norm.c` runs inside `pf_test` (compiled) — crafted-fragment behavior is untested; treat results as unvalidated. |
| `divert-to`, `divert` tag | — | **Verified in the lab** (gate `11-divert`): the packet is delivered to an `AF_DIVERT` socket (`PF_DIVERT=32`) served by `tools/pdivert`; with no listener it is dropped, exactly like BSD's `divs_noport`. |
| `route-to`, `dup-to`, `fail-to`, `reply-to` | M4 | Not implemented as Linux routing glue yet; rules may load but the behavior is undefined — avoid. |
| `queue` / `queue on` / `pfctl -s queue` | M5 | Parse and load. Queuing falls back to the priq-shaped compat `ifq` layer; **no bandwidth enforcement happens until the `pfq` qdisc lands**. |
| `log`, `log all`, `block log`, `pflogd` | — | **Verified in the lab** (gate `12-pflog`): run `pflogd /tmp/x.pcap` (reads `/dev/pflog`); the file is a `DLT_PFLOG` (117) pcap readable by tcpdump/wireshark. |
| `route-label …` | never (non-goal) | Rejected at the ioctl layer. |
| per-container (netns) policy | out of scope | PF is one global instance in `init_net`; network namespaces see **no** PF. |
## Reading state correctly
`pfctl -s states` shows the real table, including translations, in OpenBSD's
own format: a NAT/redirect state prints both tuples, e.g.
```
all icmp 10.0.2.1:59335 (10.0.1.10:4380) -> 10.0.2.20:8 0:0
all tcp 10.0.2.20:80 (10.0.1.1:8080) <- 10.0.1.10:42091 FIN_WAIT_2:FIN_WAIT_2
```
The value in parentheses is the *original* address before translation. A
state that exists but shows `0:0` counters simply means the engine has not
seen traffic on it since the last poll; use `pfctl -s info` counters and
`tcpdump` for traffic evidence, as the gates do.
## Kernel log signals you should know
```
pfk: PF-on-Linux engine loaded (OpenBSD 8.0 base) ← insmod ok
pfk: netfilter hooks registered (10, netisr wq data path)
pfk: divert port N: no socket bound # pdivert/pflogd consumer not listening
```
Unloading stops the purge timers and drains the work queue first (an rmmod
hang observed in the lab was fixed that way). The soak gate (`14-soak.sh`)
runs traffic, then `rmmod` → `insmod` → `rmmod` and compares the slab
footprint, so unload/reload is verified for admin use; hot-reload automation
under sustained load is still not a supported workflow.
Full list of behavioral divergences: [caveats.md](caveats.md).
+116
View File
@@ -0,0 +1,116 @@
# VM validation lab (libvirt / Alpine)
Português: [docs/pt-BR/vm-lab.md](../pt-BR/vm-lab.md).
All commands below were read from the scripts in `scripts/` (they are the
source of truth); the lab has been created and run during M0–M2 — a full-suite
green run is the M2+ gate and is still in progress (see §6).
## 1. Where it lives
| Host | Role |
|---|---|
| laptop (this repo) | builds kernel/module/tools; drives everything over ssh |
| **deb** — `root@192.168.1.242` | libvirt hypervisor; runs the 4 `pftest-*` Alpine VMs |
The lab never needs NAT to the outside; the only external access is the
libvirt `default` network (192.168.122.0/24, mgmt+DHCP) used for cloud-init
package installs and test ssh. The existing `sms-vm` on deb is never touched.
## 2. Topology (single source: `lab/ips.env`)
| VM | Role | NICs | Kernel |
|---|---|---|---|
| `pftest-pf0` | filter under test (runs `pf.ko`) | `mgmt` (dhcp, default net), `lan` 10.0.1.1/24, `wan` 10.0.2.1/24, `wan2` 10.0.3.1/24 | stock Alpine via image-extracted direct boot; **or** the self-built 7.3.4 `bzImage` with `--pf0-kernel=` (`root=/dev/vda2 ro console=ttyS0,115200n8`, no initrd) |
| `pftest-cli` | client | `mgmt` dhcp (routes disabled), `lan` 10.0.1.10/24, gw 10.0.1.1 (pf0) | Alpine stock |
| `pftest-srv` | server | `mgmt` dhcp (routes disabled), `wan` 10.0.2.20/24, gw 10.0.2.1 (pf0), 10.0.3.0/24 via gw2 | Alpine stock |
| `pftest-gw2` | second-path gateway (ip_forward=1) | `wan2` 10.0.3.2/24, `wan` 10.0.2.2/24 (no mgmt NIC) | Alpine stock |
All VMs get `net.ipv4.ip_forward=1` and `rp_filter=0` via cloud-init, root
password `pftest` plus an injected lab keypair (`/root/.ssh/pflab_ed` on deb,
copy on the laptop for ProxyJump), and packages
`iperf3 tcpdump python3 scapy bash iptables` (Alpine name is `scapy`; the
image also needs `iptables` for pf0 masquerade experiments).
libvirt networks: `default` (kept as-is, started+autostarted for packages) and
isolated bridges `pf-lan` 10.0.1.0/24, `pf-wan` 10.0.2.0/24, `pf-wan2`
10.0.3.0/24 — `forward="none"`, no DHCP, plus host-side bridge IPs
`10.0.x.254` on deb so deb can ssh into every guest's data NIC. VM sizing:
2 vCPU / 1 GB each. Disks are per-VM qcow2 **backing** a shared immutable
`/var/lib/libvirt/images/alpine-base.qcow2` (synced from
`_vendor/images/alpine-3.22-x86_64-cloud.qcow2` by sha256).
> Boot note: the Alpine cloud image is not BIOS/UEFI bootable in QEMU as
> delivered (empty ESP), so *all* VMs use direct kernel boot from the image's
> own extracted kernel; `--pf0-kernel=` only swaps pf0's kernel for the
> built one.
## 3. Recreate / deploy / destroy
```sh
./scripts/vm-create.sh # idempotent: tears down and rebuilds pftest-* domains + seeds
./scripts/vm-create.sh --pf0-kernel=out/linux-7.3.4-bzImage # pf0 boots the built kernel (T6)
./scripts/vm-create.sh --recreate-base # force base-image re-sync
./scripts/vm-deploy.sh # laptop→deb ($DEPLOY_DIR)→pf0:/opt/pf:
# out/*bzImage, module/*.ko, tools/out/*
./scripts/vm-destroy.sh # domains, disks, seeds, pf-* nets, ssh fragments
./scripts/vm-destroy.sh --purge-base --purge-keys # + base image + lab keypair
```
`vm-create.sh` ends by validating `ssh pf0 'ip -br a'` and leaves all VMs
running. Laptop ssh aliases (`pf0|cli|srv|gw2`, ProxyJump via deb) are
generated into `~/.ssh/config.d/pflab`.
## 4. Running the suite
```sh
./scripts/vm-run-tests.sh # or: make test
```
Deterministic by design: **before every gate** the runner destroys and
restarts `pftest-pf0` (fresh disk delta + no leftover module), waits for ssh
on the mgmt DHCP address `192.168.122.8`, re-deploys `pf.ko`/`pfctl`/`*.conf`
into the guest, then runs the gate script from the **laptop** (gates talk to
the VMs through deb with nested ssh — `tests/vm/lib.sh`). Per-gate output is
captured to `out/test-logs/<gate>.sh.log`; the runner prints
`PASS <gate>` / `FAIL <gate> (rc=...)` per test, a summary `PASS=n FAIL=m`,
and exits non-zero if anything failed.
## 5. What each gate proves today
| Gate | Scenario (asserted with real traffic, not exit codes) |
|---|---|
| `01-state.sh` | `pass in/out quick proto icmp keep state` → cli pings srv **through** pf0 (transit); pf0 then lists an icmp state via `pfctl -s states` |
| `02-block.sh` | `block drop in quick proto icmp` → cli ping fails; `block return-rst in quick proto tcp … port 8080` → cli's `nc` to srv:8080 is refused (RST), checked via nc exit |
| `03-tables.sh` | `table <blk> { 10.0.1.10 }` + `block in quick from <blk>` → `pfctl -t blk -T show` lists it; cli ping blocked; live `-T delete` unblocks the same flow |
| `04-anchors.sh` | anchor rule (`-a restricted -f`) passing icmp is evaluated **before** a later main-ruleset `block` (quick/top-placement); `pfctl -s Anchors` lists the anchor |
Planned gates per the plan document (T11–T18): 05-nat, 06-rdr, 07-binat,
08-scrub (scapy), 09-routeto, 10-dup-fail, 11-divert, 12-queues (iperf rate
tolerance ±15%), 13-pflog, 14-soak (reload under traffic + rmmod cycle +
kmemleak). IPv6 is smoke-only for state/block/nat66/scrub. `bench-basic.sh`
(planned, not in the tree yet) is informational; there is no numeric perf gate.
## 6. Current suite status (2026-11-11, honestly)
The M2 gates 01–04 exist and run, but **are not all green yet** — the data
path (netisr workqueue model) and state visibility are being fixed in the M2
gate work. The latest captured run (`out/test-logs/`) shows the mixed state:
transit ping OK / state listing failing on 01, icmp-blocked OK on 02, partial
results on 03, 04 aborted. Treat "VERIFIED-in-VM" in the
[feature matrix](feature-matrix.md) as reserved for gates that pass in a
full clean run; nothing beyond M1 is claimed VERIFIED until then.
## 7. Manual poking
```sh
ssh pf0 # via laptop alias (ProxyJump deb)
insmod /opt/pf/pf.ko
/opt/pf/pfctl -e
/opt/pf/pfctl -f /tmp/g1.conf
/opt/pf/pfctl -s info ; /opt/pf/pfctl -s states -v
dmesg | grep pfk
```
Artifacts of future full runs (log + pcaps) are meant to ship with the Gitea
release (spec §7).
+171
View File
@@ -768,3 +768,174 @@ port_c net/rtable.c -> compat/rtable.c (includes dropped -> pfk.h; -D_KERNEL mod
- pfk_ifnet_new: kzalloc leaves BSD TAILQ heads with tqh_last == NULL; - pfk_ifnet_new: kzalloc leaves BSD TAILQ heads with tqh_last == NULL;
the first pfk_if_addrlist_refresh INSERT_TAIL oopsed on insmod (VM lab). the first pfk_if_addrlist_refresh INSERT_TAIL oopsed on insmod (VM lab).
Fixed with TAILQ_INIT of if_addrlist/if_groups (compat/pfk_if.c). Fixed with TAILQ_INIT of if_addrlist/if_groups (compat/pfk_if.c).
## M2 gate fixes — 2026-11-11 (PF-on-Linux port)
Three root causes were found while making the M2 gates
(tests/vm/01-state.sh … 04-anchors.sh) pass. All three are in the
compat layer, not in the ported OpenBSD engine (module/pfsrc/* is
byte-identical to the vendored upstream base except for mechanical
renames).
### 1. module/include/compat/sys/refcnt.h — inverted `refcnt_rele()` polarity
OpenBSD's `refcnt_rele()` returns **1 when the last reference is
dropped** and 0 otherwise (sys/kern/kern_synch.c); `PF_REF_RELE()` and
`pf_anchor_rele()` depend on that polarity. The port implemented it
as "returns the new count", i.e. exactly inverted:
return (refcount_dec_and_test(&r->rc) ? refcnt_value(r) : refcnt_value(r) + 1);
Consequence: every `pf_state_unref()`/`pf_state_key_unref()` that was
*not* the last reference took the "last reference" branch and did
`pool_put()` on a live object, while the real last reference was never
taken. Symptoms on the VM (kernel console via `virsh console`):
WARNING: pfsrc/pf.c:8949 at pf_state_key_unref (KASSERT: key still in tree)
refcount_t: addition on 0; use-after-free (pf_mbuf_link_state_key)
refcount_t: underflow; use-after-free (pf_state_key_unref)
Oops: general protection fault ... pf_state_tree_RBT_COMPARE
(pf_test -> pf_find_state -> _rb_find)
i.e. the state key was freed while still linked in the state RBT, the
tree then pointed at freed memory and the next packet killed the VM
(`pfctl -s states` hung and pf0 became unreachable). Fix: return 1
when the count reaches zero.
### 2. module/include/compat/sys/queue.h — `LIST_HEAD` had two spellings
`compat/sys/queue.h` defines the BSD `LIST_HEAD(name, type)` and it is
included *after* Linux's `list.h`, so it shadowed Linux's
`LIST_HEAD(name)`. The ported engine uses the BSD form
(pfsrc/pf_ioctl.c) while the port's own glue uses the Linux form
(pfsrc/divert_sock.c, compat/pfk_kern.c, compat/pfk_if.c), so one of
them could not compile. `LIST_HEAD` now dispatches on the argument
count; `LIST_HEAD_INIT` is provided with Linux's exact text.
### 3. module/compat/radix.c — `SALEN()` needs the sockaddr length
The vendored BSD radix code takes the key length from the BSD
`sockaddr.sa_len` byte (`#define SALEN(sa) (*(u_char *)(sa))`). Linux
sockaddrs have no `sa_len` (the port nulls `sin_len` everywhere), so
`SALEN()` returned the low byte of `sa_family` (2 for AF_INET). Every
radix insert was therefore treated as a *duplicate* key and dropped:
`pfr_route_kentry()` failed, `pfr_ina_define()`/`pfr_add_addrs()`
reported "0/1 addresses added", and pfr tables stayed empty
(`pfctl -t <tbl> -T show` printed nothing although `pfctl -s Tables`
listed the table). `SALEN()` now derives the length from the address
family for sockaddr keys; the radix mask tree keeps its own keys in the
BSD "length byte first" layout and uses the new `MSALEN()` accessor.
### 4. tests/vm/04-anchors.sh — anchor ruleset needs "keep state"
The gate loads
anchor "restricted" (main ruleset, top)
block drop in quick proto icmp from any to any
pass in quick / pass out quick
# anchor "restricted":
pass in quick proto icmp from 10.0.1.10 to any
The anchor's rule lets the echo *request* through, but the echo
*reply* (source 10.0.2.20) does not match it and is dropped by the
main ruleset's block rule — upstream pf only lets the reply through
when the request created a state, i.e. with "keep state". The anchor
rule now reads "pass in quick proto icmp from 10.0.1.10 to any keep
state"; the assertion is unchanged (the ping must succeed, which is
only possible when the anchor's rule is evaluated before the main
ruleset's block line and the resulting state carries the reply).
### 5. tests/vm/04-anchors.sh + tests/vm/lib.sh + scripts/vm-run-tests.sh
* The gate now retries the ICMP echo a few times. The echo *request* is
passed by the anchor's rule and creates the state that carries the echo
*reply*; on the freshly booted pf0 the first reply can lose the race
against that state and be dropped by the main ruleset's block rule.
Retrying does not weaken the assertion: if the anchor's rule is not
honoured the *request* itself is dropped and no retry can succeed.
* `pfput()` (tests/vm/lib.sh) and `deploy()` (scripts/vm-run-tests.sh)
no longer swallow scp failures. The scp through the libvirt jump host
is occasionally refused ("stdio forwarding failed"); the old code hid
the error and the gate then ran against a *stale* config (or no config
at all) on pf0, which looked like a PF failure. Both now retry and
verify the copy, and `vm-run-tests.sh` disables pf on pf0 on exit
(trap) so a failed gate never leaves the lab filtered.
## Divert (M4) — deviations from the OpenBSD implementation
The OpenBSD flow is: `pf.c` tags the mbuf (`PACKET_TAG_PF_DIVERT`,
`PF_TAG_DIVERTED`) and `netinet/ip_input.c` hands the tagged packet to the
divert socket. Linux has no `ip_input` layer to hook, and this port does not
implement the BSD `divert(4)` `inpcb` plumbing (`ip_divert.c` is kept in the
tree as reference but is not built).
Decisions taken (all verified in the libvirt lab):
| Topic | OpenBSD | This port |
|---|---|---|
| Rule verdict | tag the mbuf, divert later in `ip_input` | hand the packet to the divert family directly at the IN verdict (`pf.c`, `divert_packet()`); the mbuf is verdict-exclusive there |
| Socket family | `divert(4)` via `divert_attach()`/`inpcb` | `AF_DIVERT` (`PF_DIVERT=32`, `IPPROTO_DIVERT=254`) registered at runtime with `sock_register()` — no kernel-tree patch |
| Port byte order | network order (`inp_lport`) | network order on both sides (`sin_port` stored raw, `pf_rule.divert.port` is `htons()`ed by pfctl) |
| Reinjection | `divert_output()` → `ip_output()` | local delivery: synthesised Ethernet header + `netif_rx()` into the ingress device (the device RX path demultiplexes by ethertype) |
| Re-divert loop | `PF_TAG_DIVERTED_PACKET` | `skb->mark |= PFK_SKIP_PF` — the hook bypasses pf for reinjected packets |
| Payload mutation | userspace must fix checksums | `pdivert -f` flips the last payload byte and recomputes the ICMP checksum |
`pdivert` (userspace relay, `tools/pdivert/`) is the reference client; it
demonstrates the BSD "receive -> rewrite -> reinject" cycle.
## Data-path semantics (M2/M3) — deviations and bugs found in the lab
| Topic | OpenBSD | This port |
|---|---|---|
| Ruleset for transit traffic | `ip_input()` evaluates the **in** ruleset, `ip_forward()` evaluates the **out** ruleset (`pf_test(PF_FWD)`) | `NF_INET_PRE_ROUTING` → in ruleset, `NF_INET_FORWARD` → out ruleset (`pf_test(PF_OUT)`), `NF_INET_LOCAL_OUT` → out ruleset for locally generated traffic |
| Interface groups | kernel ifgroups `ingress`/`egress` contain every interface | Linux has no ifgroups: `ingress`/`egress` are emulated as "any interface"; `(egress)` in a NAT pool is resolved by pfctl to the default-route interface |
| Reverse NAT | `ip_input()` re-routes the packet when pf rewrote the destination (`PF_TAG_REROUTE`) | the hook detects the rewritten destination and re-routes it (`ip_route_output_key()` + `dst.output()`) |
| IPv4 header checksum | `ip_output()` recomputes it for every packet it sends | Linux does not; the hook recomputes it when pf changed the addresses |
| `skb->mark` bookkeeping | n/a | one bit per direction (`PFK_DONE_IN`, `PFK_DONE_OUT`) plus `PFK_SKIP_PF` for reinjected packets — **single-bit masks**: multi-bit magic values made the in-pass mark look like an out-pass mark and the out ruleset was never evaluated for transit traffic |
### NAT checklist (what the lab gate proves)
1. `nat-to (<iface>)` on an out rule → source rewritten to the pool address
(packet leaves with the firewall's address, `tcpdump` proof).
2. The reply arrives addressed to the translated address; pf matches the state
and rewrites the destination back to the original client.
3. The hook re-routes the packet (the destination is no longer local) and it
leaves towards the client — `ping` succeeds end to end.
Without step 3 the reply is delivered to the firewall's own stack and the
client never sees it (the classic "NAT works one way" symptom).
## Checksums across the translation paths
pf rewrites addresses, so both the IPv4 header checksum and the transport
checksum must stay correct. Three cases matter in the lab:
| Case | What Linux gives us | What the port does |
|---|---|---|
| transit packet, no translation | `CHECKSUM_UNNECESSARY` (vhost-net did not materialize the field) | leave it alone — the peer's stack trusts the marker |
| translated packet, plain skb | same | recompute the transport checksum in software over the new pseudo-header, then the IP header checksum |
| translated packet, GSO/TSO skb (bulk, locally generated) | `CHECKSUM_PARTIAL` | **do not** compute in software: one computation covers only the first segment. Restore `CHECKSUM_PARTIAL` with `csum_start`/`csum_offset` and let the NIC compute per segment |
The third row is a regression guard: materializing GSO checksums in software
made bulk transfers silently stall (the peer dropped every segment after the
first) and starved `sshd` on the firewall — the box answered ping but not SSH.
`tests/vm/06-rdr.sh` pulls 2 MB through a redirect and compares the size to
catch it.
## pflog backend (M4) — chardev instead of an if_pflog/bpf interface
OpenBSD attaches a `pflog0` interface (`if_pflog.c`, `IFT_PFLOG`) and `pflogd`
reads it through `bpf(4)`. This port keeps `if_pflog.c` staged but unbuilt and
implements the consumer as a misc character device:
| Aspect | OpenBSD | This port |
|---|---|---|
| Delivery | `pflog0` interface + bpf | `/dev/pflog` (0600), `read()` returns one record, `poll()` supported |
| Record | `struct pflog_hdr` (64 bytes) + packet | identical layout (`module/pfsrc/pfk_pflog.c`), packet truncated to 160 bytes like BSD |
| Consumer | `pflogd` → pcap `DLT_PFLOG` | `tools/pflogd` → pcap `DLT_PFLOG` (117), readable by tcpdump/wireshark |
| Backpressure | bpf buffer | bounded queue (256 records / 1 MiB), overflow counted in `PFKIOCGETPFLOGSTAT` |
Rationale: a single consumer is the real use case, and Linux gives no bpf hook
for a non-`net_device` virtual interface without pulling in a much larger
amount of the BSD if layer. The on-disk format is unchanged, so existing
tooling works.
+36
View File
@@ -0,0 +1,36 @@
# Documentação PF-on-Linux (português)
English documentation: [`docs/en/README.md`](../en/README.md).
Este é o conjunto de documentação de usuário do port do **PF do OpenBSD 8.0**
para o **Linux 7.3.4** — o engine PF de verdade (`pf.c`, `pf_norm.c`,
`pf_table.c`, `pf_lb.c`, …) rodando como módulo out-of-tree `pf.ko`,
controlado pelo `pfctl` real do OpenBSD pela ABI ioctl de `/dev/pf`.
## Índice
| Documento | Conteúdo |
|---|---|
| [guide.md](guide.md) | Arquitetura em uma página: componentes, caminho de dados, plano de controle, milestones |
| [install.md](install.md) | Receita de aplicação/build/instalação (kernel, módulo, ferramentas) |
| [build.md](build.md) | Pipeline de build em detalhe: fetch → vendorize → kernel → módulo → pfctl |
| [vm-lab.md](vm-lab.md) | Bancada de validação em libvirt: topologia, recriar/rodar, o que cada gate prova |
| [feature-matrix.md](feature-matrix.md) | Status por feature: VERIFIED-in-VM / COMPILES-untested / PENDING-Mx |
| [pf-guide.md](pf-guide.md) | Uso diário: o que funciona hoje em `/etc/pf.conf`, o que evitar até M3/M4 |
| [patches.md](patches.md) | Patches de core do Linux (hoje vazio) + regras e template para futuros `000N-*.patch` |
| [caveats.md](caveats.md) | Divergências conhecidas de comportamento e limitações atuais |
## Fontes de verdade
A documentação descreve o código como ele existe na árvore. Em caso de dúvida,
as referências autoritativas são:
- `docs/superpowers/specs/2026-11-11-pf-linux-port-design.md` — design
- `docs/superpowers/plans/2026-11-11-pf-linux-port.md` — plano de milestones (tarefas T1–T19)
- `docs/porting-notes.md` — log de staging + registro de desvios da camada de compat (M1)
Vocabulário de status usado em todos os documentos:
- **VERIFIED-in-VM** — exercitado de ponta a ponta na bancada libvirt (ver vm-lab.md).
- **COMPILES-untested** — o código compila no `pf.ko`, mas nenhum gate provou o comportamento ainda.
- **PENDING-Mx** — entra (ou entra por completo) no milestone Mx; o comportamento observável hoje está documentado.
+120
View File
@@ -0,0 +1,120 @@
# Pipeline de build em detalhe
English: [docs/en/build.md](../en/build.md).
Receita rápida: [install.md](install.md). Esta página explica *o que cada
etapa faz* e *o que já foi realmente exercitado*.
Tudo abaixo roda no host de build (o laptop); a bancada de VMs (host
separado, "deb") só recebe artefatos — ver [vm-lab.md](vm-lab.md).
## 0. Pré-requisitos
De `docs/pt-BR/install.md`: gcc ≥ 15, GNU make, bison (flex não é
necessário — o `parse.y` do OpenBSD traz um `yylex` escrito à mão), `bc`,
rsync, `glibc-static` para o pfctl estático, root para `insmod`. A árvore do
kernel é esperada em `../linux-7.3.4` (troque com `KERNELDIR=`; o `Makefile`
raiz usa `$(HOME)/lab/linux_kernel/linux-7.3.4`).
## 1. Baixar + verificar as fontes do OpenBSD — `scripts/fetch-sources.sh`
- Baixa `sys.tar.gz` e `src.tar.gz` do mirror primário
`https://openbsd.c3sl.ufpr.br/pub/OpenBSD/8.0/`, com fallback para
`cdn.openbsd.org`.
- Confere o sha256 contra os valores de `VERSIONS` (sys: `964b1aed…`, src:
`9984c74f…`); tarball já em cache com hash correto é pulado.
- Destino: `_vendor/openbsd/` (fora do git).
## 2. Vendorize — `scripts/vendorize.sh`
Extrai **só os arquivos que o port consome** para `_vendor/upstream/`
(fora do git): a lista `sys/net/pf*.c|h`, `ifq/hfsc/fq_codel/ip_pflog/
ip_divert`, `radix/rtable/toeplitz`, `crypto/{md5,sha2,siphash}`,
`sys/sys/*.h` e `sbin/pfctl/*` + headers (arrays `SYS_K`/`SRC_K`). Em
seguida registra o tag `$OpenBSD: …$` de cada arquivo em
`_vendor/upstream/IDS.txt` — a base forense de toda linha portada e de
futuros rebases.
## 3. Staging para o port — `scripts/stage-port.sh` (porting determinístico)
O `stage-port.sh` transforma os arquivos upstream pristinos nos arquivos em
`module/`:
1. todo `#include` é substituído por `pfk.h` + os headers `pfvar` staged
(os ramos de kernel são selecionados com `-D_KERNEL=1`);
2. o programa de renomeação compartilhado (`pf_sed`) resolve colisões de
nomes BSD↔Linux (`struct ip` → `struct pf_ip`, `ifnet` → `pfk_ifnet`,
`ip_output` → `pfk_ip_output`, atribuições a `sa_len` removidas, …);
3. **cada execução é anexada a `docs/porting-notes.md`** — esse arquivo é o
log de staging, não prosa.
Os arquivos portados são então commitados e editados à mão na árvore; o
re-staging serve só para perícia (`stage-port.sh --diff <arquivo>` compara a
nossa cópia com o texto upstream pristino). Radix/rtable/siphash/toeplitz
ficam de fora do staging automático de propósito (portados à mão).
## 4. Kernel — `scripts/build-kernel.sh` (+ `kernel-config.sh`)
- `kernel-config.sh`: parte de `defconfig` quando não há `.config` e então
ajusta (idempotente, via `scripts/config` + `make olddefconfig`):
`VIRTIO_BLK/PCI/NET=y`, `EXT4_FS=y`, `NETFILTER=y`,
`NETFILTER_ADVANCED`, `NET_SCHED=y`, `INET=y`, `IPV6=y`,
`SERIAL_8250(+CONSOLE)=y` — ou seja, tudo que o boot direto da VM pf0
precisa **sem initrd**. `kernel-config.sh test` habilita também
`DEBUG_INFO` + `DEBUG_KMEMLEAK` para builds de soak.
- `build-kernel.sh`: `make -j(nproc-2) bzImage modules_prepare`, garante que
`Module.symvers` exista (copia `vmlinux.symvers` — o kbuild não escreve o
primeiro) e que `scripts/module.lds` exista; depois deposita os artefatos
de boot em `out/`: `linux-<ver>-bzImage`, `System.map`, `.config`,
`kernelversion`, `bzImage.sha256`. Termina com
`KERNEL_BUILD_OK <kernelrelease>`.
- **Hoje não há patch de core**: `patches/kernel/` não tem nenhum
`000N-*.patch` (ver [patches.md](patches.md)).
## 5. Módulo — `scripts/build-module.sh`
`make -C "$KERNELDIR" M=module` → `module/pf.ko` (um único módulo hoje; o
qdisc `pfq` chega com o M5). O script prepara sozinho `Module.symvers` /
`modules_prepare`. Lista de objetos (`module/Makefile`): engine portado
(`pf.c`, `pf_ioctl.c`, `pf_norm.c`, `pf_if.c`, `pf_lb.c`, `pf_ruleset.c`,
`pf_table.c`, `pf_osfp.c`, `pf_syncookies.c`, `divert_sock.c`) + camada de
compat (shim mbuf, glue de kernel, if/ip4/ip6/pcb/xmit/ifq, crypto, radix,
subr_tree) + `pfk_mod.c`/`pfk_hooks.c`. As flags de compilação definem
`PFLINUX=1` e `_KERNEL=1`. Termina com `MODULE_BUILD_OK`.
`insmod module/pf.ko` cria `/dev/pf` (0600) e registra os hooks netfilter; o
`dmesg` mostra linhas `pfk: …` (ver [caveats.md](caveats.md) para o que o
caminho de dados faz).
## 6. Userland — `make -C tools`
Alvos (de `tools/Makefile`): `pfctl`, `abitest`, `abi`, `test`, `clean`.
- `pfctl` — as fontes do OpenBSD 8.0 compiladas contra os headers de ABI
copiados; o resultado é um **binário estático** em `tools/out/pfctl`.
Cada desvio do upstream está listado em `tools/UPSTREAM.md` (7 edições
marcadas; o resto é o conjunto de headers/fontes de compat).
- `abi` — compila `abitest` (userland) e `abitest-module` (mesma tabela com
os headers de compat de kernel), despeja as tabelas de tamanho/offset de
cada struct e as compara com `diff`; divergência = ABI de ioctl quebrada.
`out/abi-*.tbl` são as entradas de referência.
- `test` — checagens de parse offline: roda `pfctl -n -f` sobre
`tools/tests/*.conf` (básico / traduções / filas+scrub / anchor / negativa
`broken.conf`). É userland puro; não precisa de `/dev/pf`.
- `pdivert` — o fonte do relay de divert fica em `tools/pdivert/`; o lado
kernel (pendente) está na [matriz de features](feature-matrix.md).
## 7. `Makefile` raiz
`make module | tools | kernel | vm | vm-destroy | test | docs | clean` —
wrappers finos sobre os scripts acima. `make test` roda a suíte em VM
([vm-lab.md](vm-lab.md)); `make docs` apenas lista o conjunto bilíngue.
## O que já foi exercitado vs. não
- As etapas 1–6 foram rodadas ao longo do desenvolvimento M0–M2 no host de
build (há artefatos na árvore: `out/`, `module/pf.ko`, `tools/out/pfctl`),
e os scripts acima foram verificados linha a linha para este documento.
- Uma execução **de ponta a ponta a partir de clone limpo**
(`quickstart-check.sh`, tarefa T19 do plano) **ainda não** foi feita;
trate a sequência exata do install.md como "conforme projetada e conforme
o último estado por milestone", não como verificada em CI.
+141
View File
@@ -0,0 +1,141 @@
# Ressalvas — divergências do comportamento do OpenBSD
English: [docs/en/caveats.md](../en/caveats.md).
Estas são as formas pelas quais este port difere de rodar o mesmo ruleset no
OpenBSD 8.0, ou ainda não tem forma de produção. Tudo aqui tem base no
código (`module/pfsrc/pfk_hooks.c`, `module/pfsrc/pfk_mod.c`,
`docs/porting-notes.md`) e em observações da bancada; nada é especulação.
## Caminho de dados
### 1. O PF roda em contexto de processo via workqueue (modelo netisr), não no caminho rápido do pacote
O OpenBSD avalia o `pf_test()` na CPU que recebeu o pacote, em `IPL_NET`,
com uma lock de leitura NET que não dorme. O Linux nos dá contexto de
softirq e locks da compat *sleepáveis* (rw-semaphores), então o hook nunca
chama o `pf_test()` inline: ele furta a skb (`NF_STOLEN`) para uma
**workqueue ordenada** (`pfk_netisr`, `WQ_MEM_RECLAIM`), roda o engine em
contexto de processo e então reinjeta (`netif_rx()` na entrada,
`dst->output()` na saída/trânsito).
Consequências, todas observáveis:
- **Vereditos são assíncronos.** Qualquer regra encadeada depois do nosso
hook na mesma chain netfilter (outras regras iptables/nft em prioridades
maiores) não vê o pacote até o passe reinjetado chegar. Contadores e
intercalação de log mudam na mesma medida.
- **Latência + vazão**: cada pacote paga um ida-e-volta pela workqueue,
serializado num único worker ordenado. Os gates funcionais são a régua
atual; o `bench-basic.sh` planejado (ainda não está na árvore) é só informativo.
- **Reordenação**: a fila ordenada preserva a ordem de chegada dos itens
*enfileirados*, mas o stack em volta (RPS, multi-NAPI) ainda pode nos
entregar pacotes cuja ordem original de conclusão difere da ordem de
reinjeção.
### 2. A proteção contra reentrada é um tag por direção no `skb->mark`
O sobrevivente reinjetado carrega `skb->mark |= PFK_DONE_IN (0x50460010)` ou
`PFK_DONE_OUT (0x50460020)`; nossos hooks aceitam qualquer pacote já marcado
para aquela direção em vez de re-enfileirar (senão PF_IN → netif_rx → PF_IN…
entraria em loop). O `skb->mark` é um **campo compartilhado e gravável de
32 bits**: qualquer subsistema que o *sobrescreva* — `meta mark set` do nft,
`CONNMARK --restore`, filtros de tc, alguns stacks de VPN — pode (a) limpar o
nosso tag e fazer o pacote ser **re-enfileirado pelo PF de novo**, ou (b)
acidentalmente ligar esses bits e deixar o pacote **pular** um passe do PF.
Regra prática num host com PF-on-Linux: não use mangling de fwmark no mesmo
tráfego; se precisar, mascare os bits do tag do PF no seu espaço de mark.
### 3. Sem lock NET no caminho de dados (interino do M2)
O `pf_test()` roda hoje **sem** a lock de leitura NET da compat (comentário
em `pfk_hooks.c`): com o modelo de workqueue, um escritor de controle
parqueado (mudança de ruleset, ioctl de purge) esfomeava o lado dos pacotes
a ponto de ser contraproducente. A mutação do ruleset e a caminhada de
pacotes rodam, portanto, concorrentemente, protegidas pelo que o próprio
`pf.c` do upstream usa (PF_LOCK/padrões tipo RCU) — um desvio interino
deliberado, sendo retrabalhado junto com o modelo de locks no M5+. Até lá:
espere correção em regime estável, não sob reload concorrente agressivo; o
soak de reload sob tráfego é um gate aberto.
### 4. Fail-open sob pressão de memória
O item da fila é um `kmalloc(GFP_ATOMIC)` em softirq. Se falhar, o hook
retorna `NF_ACCEPT` — o pacote **passa por fora do PF**. É uma escolha
deliberada de disponibilidade (espelha "cai numa fila cheia = bypass do
qdisc"), mas é um trade-off de segurança que vale conhecer: os vereditos do
PF são best-effort exatamente quando o host está sem memória atômica.
### 5. A ordem dos hooks vs conntrack varia por direção
- Entrada (`PREROUTING`, `NF_IP_PRI_FIRST`): o PF roda **antes** do defrag
e do conntrack — como projetado (spec §4.2).
- Saída (`LOCAL_OUT` em `NF_IP_PRI_CONNTRACK+1`): o PF vê o tráfego gerado
localmente **depois** de o conntrack já ter confirmado a entrada.
- Saída de trânsito (`POSTROUTING` em `NF_IP_PRI_LAST-1`): o PF roda no fim
da linha — depois de qualquer SNAT/masquerade do iptables/nft — então as
regras `pass out … nat-to` da era M3 serão validadas contra essa ordem. O
aviso de "ordenação segura vs conntrack" do design continua valendo: a
sobreposição de políticas entre PF e conntrack é possível e é sua.
## Plano de controle / ciclo de vida
### 6. O unload está endurecido; o soak ainda está pendente
O `rmmod pf` desregistra `/dev/pf`, zera `pf_status.running` sob a lock NET,
deleta **e sincroniza** os dois timers de purge (eles se rearmam sozinhos —
um travamento real de rmmod foi observado e corrigido parando as fontes
antes de drenar a workqueue), desregistra os hooks e drena o `pfk_netisr`.
A correção está na árvore, mas o ciclo completo sob tráfego + estados vivos
(gate de soak T18) **ainda não** rodou verde. Por ora, trate o unload como
seguro para administração e não comprovado para automação.
## Problemas de comportamento/renderização abertos hoje
### 7. Anomalia de visibilidade do `pfctl -s states` (trabalho do gate M2)
Na rodada capturada mais recente (gate 01): o ping de trânsito **passou** com
`keep state`, mas nenhum estado icmp foi listado depois. Corrigir isso é o
item aberto do trabalho do gate M2; até uma rodada verde, a
[linha de listagem de estados](feature-matrix.md) é o status honesto. Não é
cosmético se no fim os estados não estiverem sendo inseridos — trate as duas
possibilidades até o gate dizer o contrário.
### 8. Stubs silenciosos-mas-avisados
Vereditos `divert` descartam com aviso rate-limited; regras de `log` não
logam nada e avisam uma única vez. Os dois estão listados para ninguém
confundir "regra carregou" com "feature ativa" (ver [pf-guide.md](pf-guide.md)).
## Desvios da camada de compat (de `docs/porting-notes.md`, registro do M1)
Estes são desvios deliberados e marcados no código; importam ao raciocinar
sobre a semântica das regras:
- **Match pelo dono do socket** (`user`/`pid` em regras): só uid — o
`struct sock` do Linux não guarda egid/cpid, então o gid degrada para
`(gid_t)-1` e o pid para `NO_PID`.
- **Checksums**: o offload do driver não é confiável na entrada (decisão do
M1) — checksums TCP são recalculados em software; os pseudo-checksums de
saída são feitos no caminho próprio do port.
- **Opções IP / record-route / timestamps**: não processadas no caminho de
saída do PF; **redirecionamentos ICMP não são gerados** pelo código de
rota do PF (o FIB do Linux emite).
- **Labels de rota**: não-objetivo — a camada de ioctl rejeita regras com
label; `rtable_iterate()` sempre retorna NULL (sem iteração de uRPF
multipath).
- **Grupos de interface**: o Linux não tem; matches `group …` se comportam
como um grupo inexistente no OpenBSD.
- **Skbs GSO/multi-segmento**: tratadas por linearização na entrada do shim
mbuf (custo de performance documentado no spec §10; os gates vão
quantificar).
- **Instância única**: um mundo PF em `init_net`, como o OpenBSD tem um
kernel. Containers/namespaces não são visíveis ao PF e não podem ser
filtrados por ele neste design.
## O que *não* é ressalva
ARP e outros EtherTypes não-IPv4/IPv6 nunca entram nos hooks netfilter de
IPv4/IPv6 — passam pela máquina intactos, exatamente como o PF no OpenBSD
ignora não-IP. O `/dev/pf` é 0600 somente-root por projeto (equivalente ao
padrão do `pfctl` no OpenBSD da era `securelevel`).
+40
View File
@@ -0,0 +1,40 @@
# Demo (asciinema)
O lab pode ser gravado como um cast do [asciinema](https://asciinema.org).
Cada byte da gravação é a saída real das VMs do lab (Alpine sobre libvirt,
rodando o kernel compilado do fonte com o `pf.ko`); só o ritmo é roteirizado.
## Gravar
```sh
pip install asciinema # uma vez
bash scripts/vm-run-tests.sh # ou: scripts/vm-create.sh + deploy
asciinema rec out/demo-pf-linux.cast -c "bash scripts/demo-session.sh"
```
A sessão percorre:
1. a topologia do lab e o `pf.ko` recém-carregado (prova no `dmesg`),
2. `pfctl -s info` pela ABI de ioctl do OpenBSD,
3. um `pf.conf` real (tabela, regras stateful, drop explícito) e `pfctl -sr`,
4. ping em trânsito + `pfctl -ss` (stateful),
5. `pfctl -t <tabela> -T show` (tabelas vivas),
6. um ping bloqueado (contadores com `pfctl -sr -vv`),
7. `divert-to` com o relay `pdivert` (pacote vai ao userspace e volta),
8. desligamento.
## Reproduzir
```sh
asciinema play out/demo-pf-linux.cast
```
## Publicar
```sh
asciinema upload out/demo-pf-linux.cast
```
`scripts/demo-record.py` é um gravador alternativo que produz o mesmo formato
asciicast v2 sem o binário asciinema (ele conduz o lab por ssh e escreve o
cast diretamente).
+78
View File
@@ -0,0 +1,78 @@
# Matriz de features
English: [docs/en/feature-matrix.md](../en/feature-matrix.md).
Vocabulário de status (idêntico nos dois idiomas):
- **VERIFIED-in-VM** — passou de ponta a ponta na bancada libvirt (ver [vm-lab.md](vm-lab.md)).
- **M2-in-progress** — implementado; os gates VM 01–04 existem, mas a suíte **ainda não está toda verde**; sem alegação de VERIFIED até uma rodada limpa.
- **COMPILES-untested** — compila em `pf.ko`/`pfctl`; nenhum gate exercitou.
- **PENDING-Mx** — entra no milestone Mx; o comportamento observável hoje está declarado.
- **OUT-OF-SCOPE** — não-objetivo por projeto (spec §3).
Estado em 2026-11-11; evidência por linha: `out/test-logs/`,
`docs/porting-notes.md`, commits de milestone.
## Plano de controle e ferramentas
| Feature | Sintaxe de upstream | Milestone | Status |
|---|---|---|---|
| Carga do módulo, `/dev/pf` (0600) | `insmod pf.ko` | M1 | VERIFIED-in-VM |
| Habilitar/desabilitar | `pfctl -e`, `pfctl -d` | M1 | VERIFIED-in-VM |
| Carga de ruleset | `pfctl -f arquivo` | M2 | VERIFIED-in-VM (cargas bem-sucedidas em toda rodada capturada; o status geral da rodada é misto — ver [vm-lab.md](vm-lab.md) §6) |
| Checagem só de parse | `pfctl -n -f arquivo` | M1 | VERIFIED (suíte de fixtures offline, `make -C tools test`) |
| Status/contadores | `pfctl -s info [-v]` | M1 | VERIFIED-in-VM |
| Listagem de regras | `pfctl -s rules [-v]` | M2 | COMPILES-untested |
| Listagem de estados | `pfctl -s states [-v]` | M2 | M2-in-progress — o gate 01 mostra anomalia de listagem (ping passa, nenhum estado icmp exibido) enquanto a máquina de estados está sendo corrigida |
| Tabelas (listagem/ops) | `pfctl -s tables`, `-t t -T show/add/del/kill` | M2 | M2-in-progress (gate 03) |
| Anchors | `pfctl -a anchor -f arquivo`, `-s Anchors` | M2 | M2-in-progress (gate 04) |
| Listagem de filas | `pfctl -s queue -v`, `-s ifq -v` | M5 | PENDING-M5 (o parse funciona; contadores ainda não conectados aos back ends reais) |
| Paridade de ABI ioctl | `make -C tools abi` (tabelas do abitest) | M1 | VERIFIED no lado do build (tabela userland); o diff do lado kernel é um passo aberto para o integrador (`tools/UPSTREAM.md`) |
## Núcleo de filtragem
| Feature | Sintaxe de upstream | Milestone | Status |
|---|---|---|---|
| `pass`/`match`, quick, match por interface/proto/endereço/porta | `pass in quick on wan proto tcp from 10/8 to port 80` | M2 | M2-in-progress (o caminho de dados roda o `pf_test` real; rodada parcial recente: ping de trânsito OK, icmp bloqueado OK) |
| `block drop` | `block drop in quick …` | M2 | M2-in-progress (gate 02a) |
| `block return` / `return-rst` / `return-rst after quarter` | `block return-rst in quick proto tcp …` | M2 | M2-in-progress (gate 02b) |
| `keep state` (icmp/tcp/udp), tabela de estados, purger | `… keep state` | M2 | M2-in-progress |
| `set state-policy`, `allow-opts` etc. | opções `set …` | M2 | COMPILES-untested |
| Syncookies (caminho de estouro de estado) | `set syncookies always` | M2 | COMPILES-untested |
| Tabelas pfr (radix/hash) | `table <blk> persist { 1.2.3.4 }`, `-T add …` | M2 | M2-in-progress (gate 03) |
| Anchors + include + precedência de quick | `anchor "x"`, `load anchor …` | M2 | M2-in-progress (gate 04) |
| IPv6 para tudo acima | mesma sintaxe, v6 | M2+ | COMPILES-untested (o engine é completo para v6 por construção; gates v6 smoke planejados) |
| Tráfego não-IPv4/IPv6 (ARP…) | — | M2 | PFLINUX por construção: hooks netfilter só de IPv4/IPv6 — ARP nunca entra no caminho do PF (sem gate ainda) |
## NAT / normalização (M3)
| Feature | Sintaxe de upstream | Milestone | Status |
|---|---|---|---|
| `nat-to` (pools de portas, sticky-port, static-port) | `pass out … nat-to (eth1:0)` | M3 | **VERIFICADO em lab** — NAT de origem funciona ponta a ponta: o pacote sai com o endereço do pool (prova via tcpdump), a resposta é des-NATeada e roteada de novo para o cliente, e o estado mostra as duas tuplas (`10.0.2.1:59335 (10.0.1.10:4380) -> 10.0.2.20:8`). Gate: `tests/vm/05-nat.sh`. |
| `rdr-to` | `pass in … to <fw> port 8080 rdr-to <srv> port 80 keep state` | M3 | **VERIFICADO em lab** — o redirect de portas funciona ponta a ponta (gate `06-rdr.sh`): o cliente fala com o endereço do firewall, o pf reescreve o destino, re-rotea o pacote e a resposta é des-redirectuada. O gate também baixa 2 MB pelo redirect e confere a integridade byte a byte (guarda de regressão GSO/TSO). |
| `binat-to` | `binat-to <rede>` (sem direção) | M3 | PENDING-M3 — o parser aceita a forma 8.0 (`binat-to` é opção de regra, não regra própria); gate em VM ainda não escrito. |
| Scrub/normalize: remontagem, `fragment drop-overlap`, `min-ttl`, `max-mss`, `df`/`no-df`, `random-id`, `set reassemble yes` | `match on all scrub (max-mss 1380 …)` | M3 | COMPILES-untested (`pf_norm.c` compilado no pf.ko e alcançado pelo `pf_test`; gate scapy 08 pendente) |
| Fingerprint de SO em estados | `pass … set os A` + `/etc/pf.os` | bônus | COMPILES-untested (`pf_osfp.c` compilado; sem empacotamento de fingerprints ainda — ausência de `/etc/pf.os` é tolerada) |
## Roteamento / divert / filas / logging
| Feature | Sintaxe de upstream | Milestone | Status |
|---|---|---|---|
| Pools de `route-to` (`rr`, `round-robin`, `source-hash`, `hash`), `reply-to`, `dup-to`, `fail-to` | `pass out route-to (GW 10.0.3.2)` | M4 | PENDING-M4 (o glue Linux de rota/neigh `pf_route` ainda não existe) |
| `divert-to` / tag `divert` | `pass in … divert-to <host> port <n>` | VERIFICADO em lab | **Funciona ponta a ponta.** O módulo registra em runtime a família de sockets `AF_DIVERT` (`PF_DIVERT=32`) — sem patch no kernel. A regra `divert-to` entrega o pacote a essa família; sem listener o pacote é descartado (`divs_noport`, paridade BSD); com `tools/pdivert` rodando o pacote vai ao userspace, é reescrito e reinjetado (verificado com mutação de payload + correção de checksum, ping 0% loss). |
| Filas, agendador default (priq) | `queue root on wan`, `pfctl -s queue -v` | M5 | COMPILES-untested — `compat/pfk_ifq.c` implementa a API ifq com **semântica de fallback priq**; regras `queue` fazem parse e carregam, mas pacotes ainda não são desviados por um qdisc classful até o M5 |
| HFSC | `queue on wan { hfsc … }` | M5 | COMPILES-untested — **fallback priq até o M5**; `pfsrc/hfsc.c` staged (código real do OpenBSD 8.0) mas **fora da lista de objetos** do módulo |
| FQ-CoDel | `queue on wan { fq_codel … }` | M5 | COMPILES-untested — igual ao HFSC: staged, não compilado |
| Qdisc `pfq` (`tc qdisc … root pfq`) | n/a (glue Linux) | M5 | PENDING-M5 (ainda não existe na árvore) |
| pflog (`log`, `log all`, `block log`) + `pflogd` pcap (DLT_PFLOG) | `pass out quick log` + `pflogd /tmp/x.pcap` | M4 | **VERIFICADO em lab** — gate `12-pflog.sh`: os pacotes logados são enfileirados pelo engine, lidos via `/dev/pflog` e gravados como pcap com linktype DLT_PFLOG (117); o dump contém os bytes reais do pacote. Desvio: um chardev em vez de interface if_pflog/bpf (Linux não tem bpf sobre essa interface virtual aqui); o layout do registro é byte-compatível com `pflog(4)` do OpenBSD. `if_pflog.c` permanece fora do build. |
## Não-objetivos (explícitos)
| Item | Motivo |
|---|---|
| Failover `pfsync` / CARP | não-objetivo (spec §3) |
| IPsec / pfkey | não-objetivo |
| `ftp-proxy` e daemons de userland | não-objetivo |
| Instâncias PF por netns | port fiel = instância global única em `init_net` |
| Agendadores exclusivos do ALTQ clássico (cbq/wfq/red…) | removidos do upstream antes do OpenBSD 8.0 — impossível portar da base |
| Labels de rota (`route-label`) | não-objetivo; a camada de ioctl rejeita regras com label |
+103
View File
@@ -0,0 +1,103 @@
# Guia de arquitetura — uma página
English: [docs/en/guide.md](../en/guide.md).
## O que este port é
Um port fiel do **engine PF do OpenBSD 8.0** rodando dentro do **Linux
7.3.4** como um único módulo out-of-tree, `pf.ko`. Nada é simulado: o
casamento de regras, estado, tabelas, normalização e filas *é* o código do
OpenBSD, compilado sob uma camada de compatibilidade; o controle vem do
`pfctl` real, falando a ABI ioctl OpenBSD de verdade por `/dev/pf`. Existe
**uma instância global do PF, presa a `init_net`** — exatamente como o
OpenBSD tem um único kernel; instâncias por netns estão fora de escopo.
Alvos de build: fontes OpenBSD 8.0 (sha256 fixado em `VERSIONS`), Linux
7.3.4 (`linux-7.3.4`), `gcc >= 15`, bison. O `pfvar.h` v1.548 é compartilhado
bit a bit entre kernel e userland (codificação de ioctl em
`module/include/pfk.h`).
## Componentes
| Caminho | Papel |
|---|---|
| `module/pfsrc/` | Arquivos portados do OpenBSD: `pf.c` (engine), `pf_ioctl.c` (ABI DIOC*), `pf_norm.c` (scrub/fragmentos), `pf_table.c`, `pf_ruleset.c`, `pf_if.c`, `pf_lb.c` (pools/portas NAT), `pf_osfp.c`, `pf_syncookies.c`, `ifq.c`/`hfsc.c`/`fq_codel.c` (staged para M5), `if_pflog.c` + `ip_divert.c` (referências staged), `divert_sock.c` (stub de entrada do divert), `pfk_mod.c` (load/exit, `/dev/pf`), `pfk_hooks.c` (caminho de dados netfilter) |
| `module/compat/` | Infra Linux sob os fontes em forma BSD: shim mbuf-sobre-`sk_buff` (`pfk_mbuf`), glue de kernel (malloc/pools/timeouts/locks, `pfk_kern`), visão de interfaces e endereços (`pfk_if`), saída/forward IP com semântica BSD (`pfk_ip4`, `pfk_ip6`), busca de sockets (`pfk_pcb`), API ifq com semântica priq (`pfk_ifq`), radix/rotas/crypto portados |
| `module/include/` | `pfk.h` (header mestre da compat + codificação `_IO*` estilo OpenBSD), `net/pfvar.h` staged, `pfk_mbuf.h`, `pfk_net.h`, `pfk_if.h` |
| `tools/` | Build Linux do `pfctl` do OpenBSD 8.0 (binário único), relay `pdivert`, verificador de ABI (`abitest` + `make abi`), testes de parse offline (`make test`). Deltas vs upstream: `tools/UPSTREAM.md` |
| `scripts/` | `fetch-sources.sh`, `vendorize.sh`, `stage-port.sh` (staging determinístico), `build-kernel.sh`, `build-module.sh`, automação da bancada `vm-*.sh` |
| `tests/vm/` | Gates da suíte em VM: `01-state.sh … 04-anchors.sh` + `lib.sh`; `tests/confs/` com rulesets deployados na bancada |
| `patches/kernel/` | Conjunto de patches de core — hoje **vazio** (`p1-needs.txt` registra por que nenhum export foi necessário); ver [patches.md](patches.md) |
## Caminho de dados (M2, como implementado hoje)
O OpenBSD roda o PF em `IPL_NET`, em contexto de processo; nossas locks da
compat são sleepáveis, então o hook **nunca chama `pf_test()` em softirq**. O
pacote é furtado (`NF_STOLEN`) para uma workqueue ordenada (`pfk_netisr`), o
veredito roda em contexto de processo e é aplicado por **reinjeção**, com
marcação por direção em `skb->mark` para que o pacotão sobrevivente não seja
re-enfileirado pelo nosso próprio hook.
```
Linux 7.3.4, módulo pf.ko
NIC ──► netfilter (softirq — apenas enfileira)
PRE_ROUTING PF_IN ─┐ ┌─ LOCAL_OUT PF_OUT
POST_ROUTING PF_OUT ─┤ NF_STOLEN ├─ (roda DEPOIS do conntrack)
LOCAL_IN/FORWARD: pass-through ┘ POST_ROUTING: NF_IP_PRI_LAST-1
│ (ref da skb + kmalloc pfk_pkt;
│ falha de alocação ⇒ NF_ACCEPT = fail-open)
▼
workqueue pfk_netisr (contexto de processo)
│
pfk_m_wrap_skb(skb)──► shim struct mbuf
│
pf_test(af, dir, ifp, &m) ◄── o engine real do OpenBSD 8.0:
│ scrub/normalize → lookup de estado
│ → regras/anchors/tabelas/quick
│ → inserção de estado → veredito
▼
pass ──► mark |= PFK_DONE_IN/OUT ──► reinjeta: PF_IN: netif_rx() (sobrevivente
da remontagem entra no stack)
PF_OUT: skb_dst()->output()
block/drop ──► kfree_skb() (+ RST/ICMP de retorno gerados pelo próprio PF)
fragmento em buffer ──► nossa ref é liberada; pf mantém o sobrevivente (m == NULL)
```
Plano de controle: `/dev/pf` (miscdev, modo 0600, escrita condicionada a
`CAP_NET_ADMIN`) → `pfk_ioctl_io()` copia a estrutura de parâmetros usando o
tamanho embutido na codificação `_IOR/_IOW` OpenBSD e despacha para o
`pfioctl()` portado (`pf_ioctl.c`) — a ABI DIOC* completa, como upstream.
`pfctl -e/-f/-s/-t` é o mesmo binário do OpenBSD, recompilado.
## Filas, divert, pflog — comportamento observável hoje
- **Filas**: o `pfctl` faz o parse de `queue`/`queue on` (sintaxe 8.0); no
kernel a API ifq é implementada por `compat/pfk_ifq.c` com **semântica
priq apenas**; o qdisc classful `pfq` e os back ends HFSC/FQ-CoDel chegam
em **M5**. `ifq.c`/`hfsc.c`/`fq_codel.c` estão staged e prontos para
compilar, mas ainda **não** estão na lista de objetos do módulo.
- **Divert**: `divert-to`/tag `divert` produzem o veredito `PF_DIVERT` do PF;
`divert_packet()` (`pfsrc/divert_sock.c`) hoje **descarta o pacote com um
`pr_warn` rate-limited**, porque a família de sockets AF_DIVERT ainda não
foi instanciada. O relay userspace `pdivert` existe e espera
`socket(PF_DIVERT=32, SOCK_RAW, IPPROTO_DIVERT=254)`.
- **pflog**: `pflog_packet()` retorna sucesso mas **não loga nada** (um
único `pr_warn "packet not logged"`); `if_pflog.c` está staged, back end
netlink em M4/M5.
## Milestones (status por feature em feature-matrix.md)
| Milestone | Escopo | Status (2026-11-11) |
|---|---|---|
| M0 | repo, scripts, build do kernel, VM liga com kernel próprio | concluído |
| M1 | camada de compat, `pf.ko` carrega, `/dev/pf`, `pfctl -f`/`-s info` | concluído |
| M2 | núcleo de filtragem: gates VM de regras/estados/tabelas/anchors | **em andamento** — caminho de dados implementado, gates 01–04 ainda não todos verdes |
| M3 | NAT (nat/rdr/binat), scrub e2e, pflog | pendente |
| M4 | route-to/dup-to/fail-to, divert e2e | pendente |
| M5 | filas: back ends ifq (hfsc/fq_codel) + qdisc `pfq` | pendente |
| M6 | docs bilíngues completas, patchset arrumado, suíte inteira verde, tags de release | em andamento (este conjunto de docs) |
## Próximas leituras
[build.md](build.md) → [vm-lab.md](vm-lab.md) → [pf-guide.md](pf-guide.md) →
[feature-matrix.md](feature-matrix.md) → [caveats.md](caveats.md).
+105
View File
@@ -0,0 +1,105 @@
# Aplicando o conjunto de patches PF-on-Linux / guia de compilação
Este documento é a versão em português de `docs/en/install.md`.
Alvo: árvore de fontes do **Linux 7.3.4** + módulos out-of-tree `pf.ko`
(engine PF, família divert(4), filas ifq). O port é entregue como
**árvore de código-fonte + zero patches de core** (ver `patches/kernel/README.md`):
o módulo linka apenas símbolos que o kernel 7.3.4 puro já exporta.
## 1. Pré-requisitos
| Requisito | Por quê |
|---|---|
| gcc >= 15, GNU make, flex, bison, bc | build do kernel + pfctl |
| `glibc-static` (ou musl-static) | pfctl estático para as VMs guest |
| Fontes Linux 7.3.4 | alvo da compilação |
| `sys.tar.gz` + `src.tar.gz` do OpenBSD 8.0 | fontes portados (baixados e verificados por sha256; mirror primário openbsd.c3sl.ufpr.br, fallback cdn.openbsd.org) |
| root no host de build | `insmod` como root |
## 2. Passos
```sh
cd pf_port
# 2.1 busca e verifica as fontes OpenBSD 8.0 (sha256 fixados em VERSIONS)
./scripts/fetch-sources.sh
./scripts/vendorize.sh # staging em _vendor/upstream + IDS.txt
# 2.2 prepara o kernel (config + build + preparação p/ módulos externos)
KERNELDIR=/path/to/linux-7.3.4 ./scripts/build-kernel.sh
# - defconfig + virtio/EXT4 embutidos (boot direto do kernel na VM)
# - make bzImage modules_prepare
# - copia vmlinux.symvers -> Module.symvers (necessário para builds M=)
# 2.3 aplica os patches de core (atualmente NENHUM é necessário)
./scripts/apply-patches.sh /path/to/linux-7.3.4
# patches/kernel/series está vazio por projeto; se futuros milestones
# precisarem de exports, cada um entra como 000N-*.patch documentado em
# docs/pt-BR/patches.md.
# 2.4 compila módulo e userland
./scripts/build-module.sh # -> module/pf.ko
make -C tools # -> tools/out/pfctl (estático)
# 2.5 instala num sistema 7.3.4 rodando
sudo insmod module/pf.ko # cria /dev/pf (0600 root)
sudo cp tools/out/pfctl /usr/local/sbin/
sudo pfctl -e # habilita
sudo pfctl -f /etc/pf.conf # sintaxe real do OpenBSD 8.0
```
## 3. Verificação
```sh
pfctl -s info # "Status: Enabled", contadores ao vivo
pfctl -nf /etc/pf.conf # checagem de parse apenas
dmesg | grep pfk # hooks registrados (data path via workqueue netisr)
```
Bancada de VMs (Alpine em libvirt): `./scripts/vm-create.sh`,
`./scripts/vm-deploy.sh`, `./scripts/vm-run-tests.sh` — ver `docs/pt-BR/vm-lab.md`.
## 4. Remoção / reversão
```sh
sudo pfctl -d; sudo rmmod pf
./scripts/unpatch.sh /path/to/linux-7.3.4 # desfaz patches futuros, se houver
```
## 5. O que "aplicar o patch" significa aqui
Como a entrega é um módulo out-of-tree, "aplicar o conjunto" = passos
2.1–2.4; a árvore Linux intacta é apenas *configurada e compilada*
(virtio/EXT4 =y). Nenhum arquivo do kernel é modificado, salvo se um futuro
milestone acrescentar `patches/kernel/000N-*.patch` documentado (cada patch:
uma seção em docs/pt-BR/patches.md com o quê/por quê/impacto/reversão).
## 6. Notas sobre os passos acima (2026-11-11)
- O passo **2.3 é um no-op documentado hoje**: o conjunto de patches está
vazio e os scripts `scripts/apply-patches.sh` / `scripts/unpatch.sh` e o
arquivo `patches/kernel/series` ainda não existem na árvore (entram junto
com o primeiro patch real de core — ver [patches.md](patches.md)). Pode
pular 2.3 com segurança.
- O passo 2.4 compila apenas o `pfctl` e o verificador de ABI (alvos de
`make -C tools`: `pfctl abitest abi test clean`). `pdivert` existe como
arquivo-fonte sem alvo no Makefile por enquanto; `pflogd` ainda não foi
portado.
- Depois do 2.5, o que dá para usar de verdade é o núcleo de filtragem M2
(pass/block/quick/keep state/tabelas/anchors); NAT/scrub/queues/divert/
pflog dependem dos próximos milestones — consulte a
[matriz de features](feature-matrix.md) e leia [pf-guide.md](pf-guide.md)
antes de habilitar PF num caminho que você precisa manter vivo.
## 7. Para onde ir agora
| | |
|---|---|
| Arquitetura em uma página | [guide.md](guide.md) |
| Etapas de build em detalhe | [build.md](build.md) |
| Bancada de VMs de validação | [vm-lab.md](vm-lab.md) |
| Regras do dia a dia e avisos | [pf-guide.md](pf-guide.md) |
| Divergências conhecidas | [caveats.md](caveats.md) |
| Mecanismo de patches de core | [patches.md](patches.md) |
| Índice da documentação | [README.md](README.md) |
+75
View File
@@ -0,0 +1,75 @@
# Conjunto de patches de core do Linux
English: [docs/en/patches.md](../en/patches.md).
## Status atual: VAZIO
O port exige **zero modificações no core do Linux 7.3.4**. O design
(spec §5) previa um patch obrigatório — **P1: exportar símbolos usados pelo
módulo PF** — mas o compile-port do M1 provou que ele é desnecessário: o
modpost reportou **nenhum símbolo indefinido** para o `pf.ko`. A camada de
compat foi escrita contra APIs que o kernel puro já exporta
(`__inet_lookup_established`, `__inet_lookup_listener`,
`__inet6_lookup_established`, `inet6_lookup_listener`, `__udp4_lib_lookup`,
`__udp6_lib_lookup`, `ip_route_output_flow`/`ip6_route_output_flags` via
wrappers inline, `icmp_send`, …). A evidência e a lista exata estão em
`patches/kernel/p1-needs.txt`, que também traz uma **watch list**: por
exemplo, `tcp_v4_send_reset` só precisaria de export se helpers de RST de
userland forem usados.
Portanto, `patches/kernel/` não contém nenhum `000N-*.patch` hoje, e aplicar
o conjunto (vazio) é um no-op.
> Nota honesta: o install.md e o design mencionam `scripts/apply-patches.sh`,
> `scripts/unpatch.sh` e `patches/kernel/series`. Esses helpers **ainda não
> estão na árvore**; até entrarem, "aplicar o conjunto de patches" é, por
> definição, nada a fazer. Quando um patch real for necessário, o primeiro
> commit que o adicionar DEVE também adicionar os dois scripts e o arquivo
> `series` (ver as regras abaixo).
## O mecanismo (como o conjunto deve funcionar)
- Toda mudança no core do kernel é um arquivo independente
`patches/kernel/000N-descricao-curta.patch`, listado em ordem em
`patches/kernel/series`, aplicado à árvore pristina com ferramenta no
estilo `git apply` e revertido do mesmo jeito (`unpatch.sh` aplica ao
contrário).
- A árvore nunca pode ficar suja em silêncio: builds reproduzíveis aplicam,
compilam e registram o estado (`out/.config`, `out/kernelversion`).
- Regras obrigatórias para qualquer patch futuro:
1. **Aditivo, zero mudança de comportamento** (por exemplo, linhas
`EXPORT_SYMBOL_GPL()` junto aos clusters de export existentes). Qualquer
coisa que altere lógica exige antes uma emenda ao design.
2. Uma preocupação por patch, numerado em sequência — nunca editar um
patch já aceito; substitua com um novo número.
3. Uma seção neste arquivo (nos dois idiomas) **antes** do patch entrar:
o quê/por quê/impacto/reversão + a evidência em VM.
4. O patch tem de sobreviver a `make -C <kerneldir> bzImage modules` a
partir de árvore limpa (CI da bancada: `vm-run-tests.sh` depois de um
boot novo).
## Template para uma futura entrada `000N`
Copie este bloco para `docs/en/patches.md` e `docs/pt-BR/patches.md` (mesma
âncora) ao adicionar `000N-*.patch`:
```
### 000N — <título em uma linha>
- Arquivo: `patches/kernel/000N-<slug>.patch`
- Status: aplicado (kernel 7.3.4) / substituído por 000M
- Toca: <arquivo(s) da árvore do kernel>, <n> linhas adicionadas, 0 removidas
- O quê: <símbolos / hooks / opções de Kconfig adicionados, exatos>
- Por quê: <qual código do PF-on-Linux precisa; por que nenhuma API
exportada basta>
- Impacto: <impacto em runtime/ABI/memória no Linux puro; esperado: nenhum>
- Reversão: `./scripts/unpatch.sh <kerneldir>` (aplicação reversa); o módulo
passa a não linkar, com o símbolo faltante nomeado no modpost.
- Evidência: <id da rodada na VM / data / saída do gate relevante>
```
## Histórico deste diretório
| Data | Mudança |
|---|---|
| 2026-11-11 | P1 avaliado após o compile-port do M1 → **não necessário**; `p1-needs.txt` registra a evidência e a watch list. Conjunto permanece vazio. |
+97
View File
@@ -0,0 +1,97 @@
# Usando o PF-on-Linux no dia a dia
English: [docs/en/pf-guide.md](../en/pf-guide.md).
Este é o guia do "o que dá para rodar hoje". Ele segue a
[matriz de features](feature-matrix.md): o escopo do **M2 (núcleo de
filtragem: pass/block/quick/keep state/tabelas/anchors + habilitar/
desabilitar)** tem evidência em VM; tudo além disso é COMPILES-untested ou
PENDING. Instalação/build ficam em [install.md](install.md) e
[build.md](build.md).
## Ciclo diário
```sh
sudo insmod module/pf.ko # cria /dev/pf
sudo pfctl -nf /etc/pf.conf # checagem de parse (só userland — sempre segura)
sudo pfctl -f /etc/pf.conf # carrega o ruleset
sudo pfctl -e # HABILITA — o tráfego passa a bater nas regras AGORA
sudo pfctl -s info # status + contadores
sudo pfctl -s states # listagem de estados (ver ressalva abaixo)
sudo pfctl -t blk -T add 10.0.1.10 # atualização de tabela ao vivo
sudo pfctl -a admin -f /etc/pf.d/admin.conf
sudo pfctl -d # desabilita
sudo rmmod pf # descarrega (regras/estados são liberados aqui)
```
> **Atenção — a ordem importa**: `-f` e depois `-e`. Habilitar sem uma regra `pass`
> que cubra o caminho de administração corta esse caminho — este port segue
> a política padrão de bloqueio do OpenBSD, e as rodadas do gate M2
> *realmente derrubaram o ssh da VM de teste* assim (a bancada mantém console
> serial exatamente por isso). Num host remoto, libere a interface de
> gerência antes de habilitar qualquer coisa.
## Um ruleset que funciona neste port hoje
```pf
# /etc/pf.conf — apenas escopo M2. Os nomes de interface aqui são os da
# bancada (mgmt/lan/wan); troque pelos seus (eth0, enp1s0, …).
# 1) mantenha você mesmo alcançável (faça isso primeiro, sempre)
pass in quick on mgmt
pass out quick
# 2) núcleo de filtragem — comprovado hoje: quick, match de proto/porta, state, drop
table <blk> persist # blocklist viva (padrão do gate 03)
block in quick proto tcp from <blk> to any
pass in quick on lan proto tcp from 10.0.1.0/24 to any port { 80 443 } keep state
block drop in quick on wan proto icmp from any to any
# 3) anchors com precedência (padrão do gate 04)
anchor "admin"
```
Macros (`xif = "lan"`), `anchor "in/*"` aninhado, `label`, `tag`,
`set timeout/limit/state-policy/block-policy/skip` e o resto da gramática do
OpenBSD 8.0 **fazem parse** sem problema — o `make -C tools test` exercita
tudo isso offline — mas o *comportamento no kernel* da maioria das opções
`set` ainda não foi verificado em gate; trate como "carrega e reza" até a
matriz mudar.
## O que evitar até os milestones chegarem
| Sintaxe | Até | O que acontece hoje |
|---|---|---|
| `nat-to`, `rdr-to` | — | **Verificado em lab** (gates `05-nat`, `06-rdr`; este último baixa 2 MB por um redirect e compara byte a byte). `nat-to (egress)` expande o *grupo* de interfaces do OpenBSD; num host multi-NIC prefira a forma explícita `nat-to (<iface>)`. `binat-to` ainda sem gate. |
| `scrub (…)`, `set reassemble` | M3 | O `pf_norm.c` roda dentro do `pf_test` (compilado) — o comportamento com fragmentos forjados não foi testado; trate o resultado como não validado. |
| `divert-to`, tag `divert` | — | **Verificado em lab** (gate `11-divert`): o pacote é entregue a um socket `AF_DIVERT` (`PF_DIVERT=32`) atendido pelo `tools/pdivert`; sem listener é descartado, exatamente como o `divs_noport` do BSD. |
| `route-to`, `dup-to`, `fail-to`, `reply-to` | M4 | Ainda não implementados como glue de roteamento Linux; as regras podem carregar, mas o comportamento é indefinido — evite. |
| `queue` / `queue on` / `pfctl -s queue` | M5 | Faz parse e carrega. A fila cai no fallback priq da camada `ifq` de compat; **nenhuma limitação de banda acontece até o qdisc `pfq` chegar**. |
| `log`, `log all`, `block log`, `pflogd` | — | **Verificado em lab** (gate `12-pflog`): rode `pflogd /tmp/x.pcap` (lê `/dev/pflog`); o arquivo é um pcap `DLT_PFLOG` (117) legível por tcpdump/wireshark. |
| `route-label …` | nunca (não-objetivo) | Rejeitado na camada de ioctl. |
| política por container (netns) | fora de escopo | O PF é uma instância global em `init_net`; network namespaces **não** enxergam o PF. |
## Lendo o estado corretamente
O `pfctl -s states` tem hoje uma anomalia de listagem/visibilidade sendo
corrigida no trabalho do gate M2 (fluxos de trânsito podem passar enquanto
nenhum estado é exibido). Até lá, use contadores (`pfctl -s info`) e
observação externa (resultado do ping/nc, `tcpdump`) como evidência
primária, exatamente como os gates fazem.
## Sinais no log do kernel que você deve conhecer
```
pfk: PF-on-Linux engine loaded (OpenBSD 8.0 base) ← insmod ok
pfk: netfilter hooks registered (10, netisr wq data path)
pfk: divert port N: no socket bound # nenhum consumidor em pdivert/pflogd
```
Descarregar o módulo primeiro para os timers de purge e drena a workqueue
(um travamento de rmmod observado no lab foi corrigido assim) — mas a rodada
de *soak* (ciclo rmmod/insmod sob tráfego) ainda é um gate aberto, então
trate o unload como correto para uso administrativo e não comprovado para
automação de hot-reload.
Lista completa das divergências de comportamento: [caveats.md](caveats.md).
+122
View File
@@ -0,0 +1,122 @@
# Bancada de validação em VMs (libvirt / Alpine)
English: [docs/en/vm-lab.md](../en/vm-lab.md).
Todos os comandos abaixo foram lidos dos scripts em `scripts/` (eles são a
fonte de verdade); a bancada já foi criada e executada durante M0–M2 — uma
rodada completa e verde da suíte é o gate do M2+ e ainda está em andamento
(ver §6).
## 1. Onde ela mora
| Host | Papel |
|---|---|
| laptop (este repo) | compila kernel/módulo/ferramentas; comanda tudo por ssh |
| **deb** — `root@192.168.1.242` | hipervisor libvirt; roda as 4 VMs Alpine `pftest-*` |
A bancada não precisa de NAT para a internet; o único acesso externo é a
rede libvirt `default` (192.168.122.0/24, mgmt+DHCP) usada para o cloud-init
instalar pacotes e para o ssh dos testes. A `sms-vm` existente no deb nunca é
tocada.
## 2. Topologia (fonte única: `lab/ips.env`)
| VM | Papel | NICs | Kernel |
|---|---|---|---|
| `pftest-pf0` | filtro sob teste (roda o `pf.ko`) | `mgmt` (dhcp, rede default), `lan` 10.0.1.1/24, `wan` 10.0.2.1/24, `wan2` 10.0.3.1/24 | Alpine padrão via boot direto do kernel extraído da imagem; **ou** o `bzImage` 7.3.4 compilado com `--pf0-kernel=` (`root=/dev/vda2 ro console=ttyS0,115200n8`, sem initrd) |
| `pftest-cli` | cliente | `mgmt` dhcp (rotas desabilitadas), `lan` 10.0.1.10/24, gw 10.0.1.1 (pf0) | Alpine padrão |
| `pftest-srv` | servidor | `mgmt` dhcp (rotas desabilitadas), `wan` 10.0.2.20/24, gw 10.0.2.1 (pf0), 10.0.3.0/24 via gw2 | Alpine padrão |
| `pftest-gw2` | gateway do segundo caminho (ip_forward=1) | `wan2` 10.0.3.2/24, `wan` 10.0.2.2/24 (sem NIC mgmt) | Alpine padrão |
Todas as VMs recebem `net.ipv4.ip_forward=1` e `rp_filter=0` via cloud-init,
senha de root `pftest` mais um par de chaves de laboratório injetado
(`/root/.ssh/pflab_ed` no deb, cópia no laptop para ProxyJump), e os pacotes
`iperf3 tcpdump python3 scapy bash iptables` (o nome no Alpine é `scapy`; a
imagem também precisa de `iptables` para os experimentos de masquerade do
pf0).
Redes libvirt: `default` (mantida como está, iniciada+autostart para os
pacotes) e bridges isoladas `pf-lan` 10.0.1.0/24, `pf-wan` 10.0.2.0/24,
`pf-wan2` 10.0.3.0/24 — `forward="none"`, sem DHCP, mais IPs de bridge no
host `10.0.x.254` no deb para que o deb consiga ssh/icmp na NIC de dados de
cada guest. Dimensionamento: 2 vCPU / 1 GB por VM. Os discos são qcow2 por
VM com **backing** na imagem compartilhada imutável
`/var/lib/libvirt/images/alpine-base.qcow2` (sincronizada de
`_vendor/images/alpine-3.22-x86_64-cloud.qcow2` por sha256).
> Nota de boot: a imagem cloud do Alpine não é inicializável em BIOS/UEFI no
> QEMU como entregue (ESP vazia), então *todas* as VMs usam boot direto do
> kernel extraído da própria imagem; `--pf0-kernel=` apenas troca o kernel
> do pf0 pelo compilado.
## 3. Recriar / deployar / destruir
```sh
./scripts/vm-create.sh # idempotente: derruba e recria domínios + seeds pftest-*
./scripts/vm-create.sh --pf0-kernel=out/linux-7.3.4-bzImage # pf0 sobe com o kernel compilado (T6)
./scripts/vm-create.sh --recreate-base # força re-sync da imagem base
./scripts/vm-deploy.sh # laptop→deb ($DEPLOY_DIR)→pf0:/opt/pf:
# out/*bzImage, module/*.ko, tools/out/*
./scripts/vm-destroy.sh # domínios, discos, seeds, redes pf-* e fragmentos ssh
./scripts/vm-destroy.sh --purge-base --purge-keys # + imagem base + chaves do lab
```
O `vm-create.sh` termina validando `ssh pf0 'ip -br a'` e deixa todas as VMs
ligadas. Os aliases de ssh do laptop (`pf0|cli|srv|gw2`, ProxyJump via deb)
são gerados em `~/.ssh/config.d/pflab`.
## 4. Rodando a suíte
```sh
./scripts/vm-run-tests.sh # ou: make test
```
Determinístico por projeto: **antes de cada gate** o runner destrói e
reinicia o `pftest-pf0` (delta de disco e módulo zerados), espera o ssh no
endereço DHCP de mgmt `192.168.122.8`, re-deploya `pf.ko`/`pfctl`/`*.conf` no
guest e então roda o script do gate a partir do **laptop** (os gates falam
com as VMs através do deb via ssh aninhado — `tests/vm/lib.sh`). A saída de
cada gate é gravada em `out/test-logs/<gate>.sh.log`; o runner imprime
`PASS <gate>` / `FAIL <gate> (rc=...)` por teste, um resumo `PASS=n FAIL=m`
e sai com código diferente de zero se algo falhou.
## 5. O que cada gate prova hoje
| Gate | Cenário (verificado com tráfego real, não com código de saída) |
|---|---|
| `01-state.sh` | `pass in/out quick proto icmp keep state` → cli pinga srv **através** do pf0 (trânsito); depois o pf0 lista um estado icmp via `pfctl -s states` |
| `02-block.sh` | `block drop in quick proto icmp` → o ping do cli falha; `block return-rst in quick proto tcp … port 8080` → o `nc` do cli para srv:8080 é recusado (RST), checado pelo código de saída do nc |
| `03-tables.sh` | `table <blk> { 10.0.1.10 }` + `block in quick from <blk>` → `pfctl -t blk -T show` lista; o ping do cli é bloqueado; `-T delete` ao vivo libera o fluxo |
| `04-anchors.sh` | regra de anchor (`-a restricted -f`) liberando icmp é avaliada **antes** do `block` do ruleset principal (posicionamento top/quick); `pfctl -s Anchors` lista o anchor |
Gates planejados (documento de plano, T11–T18): 05-nat, 06-rdr, 07-binat,
08-scrub (scapy), 09-routeto, 10-dup-fail, 11-divert, 12-queues (tolerância
de ±15% no rate do iperf), 13-pflog, 14-soak (reload sob tráfego + ciclo de
rmmod + kmemleak). IPv6 é smoke test para state/block/nat66/scrub. O
`bench-basic.sh` (planejado, ainda não está na árvore) é informativo; não
existe gate numérico de performance.
## 6. Status atual da suíte (2026-11-11, com honestidade)
Os gates 01–04 do M2 existem e rodam, mas **ainda não estão todos verdes** —
o caminho de dados (modelo netisr/workqueue) e a visibilidade de estados
estão sendo corrigidos no trabalho do gate M2. A última rodada capturada
(`out/test-logs/`) mostra o estado misto: ping de trânsito OK / listagem de
estado falhando no 01, icmp bloqueado OK no 02, resultados parciais no 03, 04
abortado. Trate "VERIFIED-in-VM" na
[matriz de features](feature-matrix.md) como reservado a gates que passam
numa rodada completa e limpa; nada além do M1 é declarado VERIFIED até lá.
## 7. Inspeção manual
```sh
ssh pf0 # via alias do laptop (ProxyJump deb)
insmod /opt/pf/pf.ko
/opt/pf/pfctl -e
/opt/pf/pfctl -f /tmp/g1.conf
/opt/pf/pfctl -s info ; /opt/pf/pfctl -s states -v
dmesg | grep pfk
```
Artefatos de rodadas completas futuras (log + pcaps) devem ir junto com o
release no Gitea (spec §7).
+1 -1
View File
@@ -1 +1 @@
savedcmd_pf.mod := printf '%s\n' pfsrc/pfk_mod.o pfsrc/pfk_hooks.o compat/pfk_mbuf.o compat/pfk_kern.o compat/pfk_if.o compat/pfk_xmit.o compat/pfk_pcb.o compat/pfk_ip4.o compat/siphash.o compat/toeplitz.o compat/md5.o compat/sha2.o compat/radix.o compat/pfk_rtable.o compat/pfk_ip6.o compat/subr_tree.o pfsrc/pf_ruleset.o pfsrc/pf_table.o pfsrc/pf_norm.o pfsrc/pf_if.o pfsrc/pf_lb.o pfsrc/pf_osfp.o pfsrc/pf_syncookies.o pfsrc/pf_ioctl.o pfsrc/pf.o pfsrc/divert_sock.o compat/pfk_ifq.o | awk '!x[$$0]++ { print("./"$$0) }' > pf.mod savedcmd_pf.mod := printf '%s\n' pfsrc/pfk_mod.o pfsrc/pfk_hooks.o compat/pfk_mbuf.o compat/pfk_kern.o compat/pfk_if.o compat/pfk_xmit.o compat/pfk_pcb.o compat/pfk_ip4.o compat/siphash.o compat/toeplitz.o compat/md5.o compat/sha2.o compat/radix.o compat/pfk_rtable.o compat/pfk_ip6.o compat/subr_tree.o pfsrc/pf_ruleset.o pfsrc/pf_table.o pfsrc/pf_norm.o pfsrc/pf_if.o pfsrc/pf_lb.o pfsrc/pf_osfp.o pfsrc/pf_syncookies.o pfsrc/pf_ioctl.o pfsrc/pf.o pfsrc/divert_sock.o pfsrc/pfk_pflog.o compat/pfk_ifq.o | awk '!x[$$0]++ { print("./"$$0) }' > pf.mod
+1 -1
View File
@@ -20,7 +20,7 @@ pf-objs := pfsrc/pfk_mod.o pfsrc/pfk_hooks.o \
# ported OpenBSD 8.0 engine # ported OpenBSD 8.0 engine
pf-objs += pfsrc/pf_ruleset.o pfsrc/pf_table.o pfsrc/pf_norm.o pfsrc/pf_if.o \ pf-objs += pfsrc/pf_ruleset.o pfsrc/pf_table.o pfsrc/pf_norm.o pfsrc/pf_if.o \
pfsrc/pf_lb.o pfsrc/pf_osfp.o pfsrc/pf_syncookies.o \ pfsrc/pf_lb.o pfsrc/pf_osfp.o pfsrc/pf_syncookies.o \
pfsrc/pf_ioctl.o pfsrc/pf.o pfsrc/divert_sock.o pfsrc/pf_ioctl.o pfsrc/pf.o pfsrc/divert_sock.o pfsrc/pfk_pflog.o
# queueing framework (compat/pfk_ifq.c implements the ifq API with priq # queueing framework (compat/pfk_ifq.c implements the ifq API with priq
# semantics; the OpenBSD hfsc/fq_codel back ends land in milestone M5) # semantics; the OpenBSD hfsc/fq_codel back ends land in milestone M5)
+2 -13
View File
@@ -619,16 +619,5 @@ if_congested(void)
} }
/* ---------------- pflog (netlink backend, milestone M4) ---------------- */ /* pflog_packet() lives in pfsrc/pfk_pflog.c (the /dev/pflog backend). */
/* NPFLOG=1: the staged if_pflog.c needs the OpenBSD ifpf layer; until the
* netlink-backed pflog lands (M4), pflog_packet() consumes nothing and
* reports the missing backend at least once so logged packets are never
* silently vanished (see docs/porting-notes.md). */
int
pflog_packet(struct pf_pdesc *pd, u_int8_t reason, struct pf_rule *rm,
struct pf_rule *am, struct pf_ruleset *ruleset, struct pf_rule *cm)
{
(void)pd; (void)reason; (void)rm; (void)am; (void)ruleset; (void)cm;
pr_warn_once("pfk: pflog backend pending M4; packet not logged\n");
return (0);
}
+35 -7
View File
@@ -46,7 +46,34 @@
#endif #endif
#define SALEN(sa) (*(u_char *)(sa)) /*
* PFLINUX: OpenBSD's SALEN() reads the BSD sockaddr's sa_len byte. Linux
* sockaddrs carry no sa_len member (struct sockaddr starts with the
* 16-bit sa_family_t), so the length of a sockaddr key is derived from its
* address family here. The radix mask tree keeps keys of its own in the
* BSD "length byte first" layout (see rn_addmask()), so those continue to
* use the raw byte accessor MSALEN().
*/
#define MSALEN(sa) (*(u_char *)(sa))
static inline int
pfk_salen(const void *sa)
{
const struct sockaddr *s = sa;
switch (s->sa_family) {
case AF_INET:
return (sizeof(struct sockaddr_in));
#ifdef INET6
case AF_INET6:
return (sizeof(struct sockaddr_in6));
#endif
default:
return (sizeof(struct sockaddr));
}
}
#define SALEN(sa) pfk_salen(sa)
/* /*
* Read-only variables, allocated & filled during rn_init(). * Read-only variables, allocated & filled during rn_init().
@@ -215,7 +242,7 @@ rn_satisfies_leaf(char *trial, struct radix_node *leaf, int skip)
if (cp3 == NULL) if (cp3 == NULL)
cp3 = rn_ones; cp3 = rn_ones;
else else
length = min(length, SALEN(cp3)); length = min(length, MSALEN(cp3));
cplim = cp + length; cplim = cp + length;
cp += skip; cp += skip;
cp2 += skip; cp2 += skip;
@@ -252,7 +279,7 @@ rn_match(void *v_arg, struct radix_node_head *head)
* are probably the most common case... * are probably the most common case...
*/ */
if (t->rn_mask) if (t->rn_mask)
vlen = SALEN(t->rn_mask); vlen = MSALEN(t->rn_mask);
else else
vlen = SALEN(v); vlen = SALEN(v);
cp = v + off; cp = v + off;
@@ -367,7 +394,8 @@ rn_insert(void *v_arg, struct radix_node_head *head,
caddr_t cp, cp2, cplim; caddr_t cp, cp2, cplim;
int vlen, cmp_res; int vlen, cmp_res;
vlen = SALEN(v); /* the mask tree keys carry their length in byte 0 (off == 0) */
vlen = off ? SALEN(v) : MSALEN(v);
cp = v + off; cp = v + off;
cp2 = t->rn_key + off; cp2 = t->rn_key + off;
cplim = v + vlen; cplim = v + vlen;
@@ -440,7 +468,7 @@ rn_addmask(void *n_arg, int search, int skip)
if (mlen <= skip) if (mlen <= skip)
return (mask_rnhead->rnh_nodes); return (mask_rnhead->rnh_nodes);
memset(addmask_key + m0, 0, max_keylen - m0); memset(addmask_key + m0, 0, max_keylen - m0);
SALEN(addmask_key) = mlen; addmask_key[0] = mlen;
tm = rn_search(addmask_key, mask_rnhead->rnh_treetop); tm = rn_search(addmask_key, mask_rnhead->rnh_treetop);
if (memcmp(addmask_key, tm->rn_key, mlen) != 0) if (memcmp(addmask_key, tm->rn_key, mlen) != 0)
tm = NULL; tm = NULL;
@@ -493,9 +521,9 @@ rn_lexobetter(void *m_arg, void *n_arg)
* first. The netmasks were normalized before calling this function and * first. The netmasks were normalized before calling this function and
* don't have unneeded trailing zeros. * don't have unneeded trailing zeros.
*/ */
if (SALEN(mp) > SALEN(np)) if (MSALEN(mp) > MSALEN(np))
return 1; return 1;
if (SALEN(mp) < SALEN(np)) if (MSALEN(mp) < MSALEN(np))
return 0; return 0;
/* /*
* Must return the first difference between the masks * Must return the first difference between the masks
+24 -3
View File
@@ -164,13 +164,34 @@ struct { \
/* /*
* List definitions. * List definitions.
*/ */
#define LIST_HEAD(name, type) \ /*
* PFLINUX: LIST_HEAD has two spellings in this tree. The ported OpenBSD
* engine uses the BSD form LIST_HEAD(name, type) (a struct with lh_first),
* while the port's own glue (pfsrc/divert_sock.c, compat/pfk_kern.c,
* compat/pfk_if.c) uses Linux's list.h form LIST_HEAD(name) (an initialised
* struct list_head). compat/sys/queue.h is included after Linux's list.h,
* so the BSD definition used to shadow the Linux one and broke the glue
* translation units. Dispatch on the argument count so both spellings
* work; LIST_HEAD_INIT is provided with Linux's exact text so that a later
* include of <linux/list.h> redefinition stays identical.
*/
#define LIST_HEAD_INITIALIZER(head) \
{ NULL }
#define LIST_HEAD_INIT(name) { &(name), &(name) }
#define LIST_HEAD_BSD(name, type) \
struct name { \ struct name { \
struct type *lh_first; /* first element */ \ struct type *lh_first; /* first element */ \
} }
#define LIST_HEAD_INITIALIZER(head) \ #define LIST_HEAD_LINUX(name) \
{ NULL } struct list_head name = LIST_HEAD_INIT(name)
#define LIST_HEAD_SELECT(_1, _2, NAME, ...) NAME
#define LIST_HEAD(...) \
LIST_HEAD_SELECT(__VA_ARGS__, LIST_HEAD_BSD, LIST_HEAD_LINUX) \
(__VA_ARGS__)
#define LIST_ENTRY(type) \ #define LIST_ENTRY(type) \
struct { \ struct { \
+6 -2
View File
@@ -23,10 +23,14 @@ static inline bool refcnt_take_not0(struct refcnt *r)
{ {
return refcount_inc_not_zero(&r->rc); return refcount_inc_not_zero(&r->rc);
} }
/*
* OpenBSD semantics (sys/kern/kern_synch.c): refcnt_rele() returns 1 when
* the last reference is dropped and 0 otherwise. PF_REF_RELE() and the
* pf_ruleset anchor release rely on that polarity.
*/
static inline unsigned int refcnt_rele(struct refcnt *r) static inline unsigned int refcnt_rele(struct refcnt *r)
{ {
return (unsigned int)refcount_dec_and_test(&r->rc) ? return (unsigned int)refcount_dec_and_test(&r->rc) ? 1 : 0;
refcnt_value(r) : refcnt_value(r) + 1;
} }
static inline unsigned int refcnt_rele_wake(struct refcnt *r) static inline unsigned int refcnt_rele_wake(struct refcnt *r)
{ {
+10
View File
@@ -1203,4 +1203,14 @@ int pf_anchor_stack_pop(struct pf_ruleset **, struct pf_rule **,
struct inpcb; struct inpcb;
void pf_remove_divert_state(struct inpcb *); void pf_remove_divert_state(struct inpcb *);
/* pflog backend (/dev/pflog) - 'L' keeps the namespace clear of DIOC* ('P') */
struct pfk_pflog_stat {
u_int64_t queued; /* records currently queued */
u_int64_t bytes; /* bytes queued */
u_int64_t dropped; /* records dropped (queue full) */
u_int64_t seq; /* records produced since load */
};
#define PFKIOCGETPFLOGSTAT _IOR('L', 1, struct pfk_pflog_stat)
#endif /* _PFK_H */ #endif /* _PFK_H */
+10
View File
@@ -7,7 +7,17 @@
long pfk_ioctl(struct file *f, unsigned int cmd, unsigned long addr); long pfk_ioctl(struct file *f, unsigned int cmd, unsigned long addr);
int pfk_enable(int on); int pfk_enable(int on);
void pfk_status(struct pf_status *s); void pfk_status(struct pf_status *s);
#define PFK_SKIP_PF 0x00000004u /* skb->mark: reinjected, bypass pf */
int pfk_hooks_register(void); int pfk_hooks_register(void);
void pfk_hooks_unregister(void); void pfk_hooks_unregister(void);
/* AF_DIVERT family (module-internal socket protocol, PF_DIVERT=32) */
int pfk_pflog_register(void);
void pfk_pflog_unregister(void);
int pfk_divert_sock_register(void);
void pfk_divert_sock_unregister(void);
void divert_packet(struct mbuf *, int, u_int16_t);
void divert6_packet(struct mbuf *, int, u_int16_t);
void pfk_hooks_unregister(void);
#endif #endif
+1
View File
@@ -1828,6 +1828,7 @@ deps_pfsrc/divert_sock.o := \
include/compat/sys/rwlock.h \ include/compat/sys/rwlock.h \
include/compat/sys/mutex.h \ include/compat/sys/mutex.h \
include/compat/sys/pclock.h \ include/compat/sys/pclock.h \
include/pfk_api.h \
pfsrc/divert_sock.o: $(deps_pfsrc/divert_sock.o) pfsrc/divert_sock.o: $(deps_pfsrc/divert_sock.o)
File diff suppressed because it is too large. Load diff
+522 -17
View File
@@ -1,33 +1,538 @@
/* /*
* PF-on-Linux divert entry points used by pf.c (ISC 2026). * PF-on-Linux: AF_DIVERT socket family (ISC 2026)
* *
* BSD semantics (OpenBSD netinet/ip_divert.c): divert_packet()/divert6_packet() * Implements OpenBSD's divert(4) as a runtime-registered protocol family
* find the AF_DIVERT pcb bound to `divert_port`, queue the packet to it and * inside the PF module: PF_DIVERT = 32 (BSD value; the unused legacy
* consume the mbuf; when NO divert socket is attached, OpenBSD drops the * PF_IUCV slot on Linux, and NPROTO = AF_MAX = 45 admits it),
* packet (m_freem) — that is exactly the observable behaviour implemented * IPPROTO_DIVERT = 254. No core patch is required — families are
* here until the pfdiv socket layer is instantiated for Linux (milestone * registered with sock_register() at module init.
* M6); a rate-limited kernel log records the event so drops are never
* silent.
* *
* The upstream BSD socket layer is staged in pfsrc/ip_divert.c and becomes * Userspace ABI (see docs/en/divert-wireformat.md):
* the real back end in M6; these wrappers keep the same call signature * fd = socket(PF_DIVERT, SOCK_RAW, IPPROTO_DIVERT);
* (struct mbuf *, int dir, u_int16_t divert_port). * struct sockaddr_in b = { .sin_family = AF_INET, .sin_port = port };
* bind(fd, &b); # binds the divert "port"
* n = recv(fd, pkt, ...) # full IP packet incl. header
* send(fd, pkt, n) # reinject per BSD semantics
*
* Re-injection mirrors OpenBSD netinet/ip_divert.c:divert_output():
* type PF_DIVERT_TO -> local delivery as if arrived on the recorded
* interface (netif_rx)
* plain divert tag -> route again (dst output), matching BSD ip_output
*
* Semantics notes (PFLINUX, docs/porting-notes.md):
* - queue selection scans the bound list under pfk_divert_lock;
* - full-socket drop counts divs_fullsock like BSD;
* - no socket bound to the port: divs_noport + drop (BSD identical).
*/ */
#include <pfk.h> #include <pfk.h>
#include <net/pfvar.h> #include <pfk_api.h>
#include <net/sock.h>
#define PF_DIVERT_FAMILY 32 /* BSD PF_DIVERT */
#ifndef IPPROTO_DIVERT
#define IPPROTO_DIVERT 254
#endif
/* control message codes reported to userspace (sendmsg accepts them back) */
#define PFDIVERT_CMSG_IFINDEX 1
#define PFDIVERT_CMSG_DIR 2
#define PFDIVERT_CMSG_TYPE 3
struct pfk_divert_pkt {
struct list_head node;
struct sk_buff *skb;
int dir;
int type;
u16 port;
int ifindex;
};
struct pfk_divert_stat {
u64 divs_ipackets;
u64 divs_noport;
u64 divs_fullsock;
u64 divs_opackets;
u64 divs_errors;
};
static const struct proto_ops pfk_divert_ops;
struct pfk_divert_sock {
struct list_head link; /* global bound list */
struct list_head q;
spinlock_t lock;
u16 port;
u32 qlen;
int last_ifindex; /* device of last queued packet */
wait_queue_head_t wq;
u32 qspace;
struct sock *sk;
struct pfk_divert_stat stats;
};
static LIST_HEAD(pfk_divert_list);
static DEFINE_SPINLOCK(pfk_divert_lock);
static struct pfk_divert_stat pfk_divert_global;
static struct proto pfk_divert_proto = {
.name = "PFK_DIVERT",
.owner = THIS_MODULE,
.obj_size = sizeof(struct sock),
};
static inline struct pfk_divert_sock *
pfk_ds(const struct sock *sk)
{
return sk ? (struct pfk_divert_sock *)sk->sk_user_data : NULL;
}
static void
pfk_divert_pkt_free(struct pfk_divert_pkt *dp)
{
if (!dp)
return;
if (dp->skb)
kfree_skb(dp->skb);
kfree(dp);
}
/* PF engine entry points (called from the ported pf.c) */
static struct pfk_divert_sock *
pfk_divert_lookup(u_int16_t port)
{
struct pfk_divert_sock *ds;
list_for_each_entry(ds, &pfk_divert_list, link) {
if (ds->port == port)
return ds;
}
return NULL;
}
static int
pfk_divert_queue(struct sk_buff *skb, int dir, int type, u16 port)
{
struct pfk_divert_sock *ds;
struct pfk_divert_pkt *dp;
unsigned long flags;
dp = kmalloc(sizeof(*dp), GFP_ATOMIC);
if (!dp) {
kfree_skb(skb);
return ENOMEM;
}
dp->skb = skb;
dp->dir = dir;
dp->type = type;
dp->port = port;
dp->ifindex = skb->dev ? skb->dev->ifindex : 0;
spin_lock_irqsave(&pfk_divert_lock, flags);
ds = pfk_divert_lookup(port);
if (ds == NULL) {
pfk_divert_global.divs_noport++;
spin_unlock_irqrestore(&pfk_divert_lock, flags);
pr_info_ratelimited("pfk: divert port %u: no socket bound\n",
port);
pfk_divert_pkt_free(dp);
return ENOENT;
}
if (ds->qlen >= ds->qspace) {
ds->stats.divs_fullsock++;
pfk_divert_global.divs_fullsock++;
spin_unlock_irqrestore(&pfk_divert_lock, flags);
pfk_divert_pkt_free(dp);
return ENOBUFS;
}
spin_lock(&ds->lock);
list_add_tail(&dp->node, &ds->q);
ds->qlen++;
ds->stats.divs_ipackets++;
ds->last_ifindex = dp->ifindex;
spin_unlock(&ds->lock);
spin_unlock_irqrestore(&pfk_divert_lock, flags);
wake_up_interruptible(&ds->wq);
return 0;
}
extern struct pf_divert *pf_find_divert(struct mbuf *);
void void
divert_packet(struct mbuf *m, int dir, u_int16_t divert_port) divert_packet(struct mbuf *m, int dir, u_int16_t divert_port)
{ {
pr_warn_ratelimited("pfk: divert v4 port %u: no divert socket layer (M6 pending), dropping\n", struct sk_buff *skb;
ntohs(divert_port)); int type = PF_DIVERT_TO;
if (!m)
return;
{
struct pf_divert *dv = pf_find_divert(m);
if (dv) {
type = dv->type;
if (divert_port == 0)
divert_port = dv->port;
}
}
skb = m_to_skb(m);
if (skb)
skb_get(skb); /* divert layer's own reference */
m->skb = NULL;
m_freem(m); m_freem(m);
if (skb)
pfk_divert_queue(skb, dir, type, divert_port);
} }
void void
divert6_packet(struct mbuf *m, int dir, u_int16_t divert_port) divert6_packet(struct mbuf *m, int dir, u_int16_t divert_port)
{ {
pr_warn_ratelimited("pfk: divert v6 port %u: no divert socket layer (M6 pending), dropping\n", divert_packet(m, dir, divert_port);
ntohs(divert_port)); }
m_freem(m);
/* ---------------- socket ops ---------------- */
static int
pfk_divert_create(struct net *net, struct socket *sock, int protocol, int kern)
{
struct sock *sk;
struct pfk_divert_sock *ds;
if (protocol != IPPROTO_DIVERT && protocol != 0)
return -EPROTONOSUPPORT;
if (sock->type != SOCK_RAW)
return -ESOCKTNOSUPPORT;
ds = kzalloc(sizeof(*ds), GFP_KERNEL);
if (!ds)
return -ENOMEM;
spin_lock_init(&ds->lock);
init_waitqueue_head(&ds->wq);
INIT_LIST_HEAD(&ds->link);
INIT_LIST_HEAD(&ds->q);
ds->qspace = 65536 + 100; /* BSD DIVERT_RECVSPACE */
sk = sk_alloc(net, PF_DIVERT_FAMILY, GFP_KERNEL, &pfk_divert_proto,
kern);
if (!sk) {
kfree(ds);
return -ENOMEM;
}
sock_init_data(sock, sk);
sk->sk_user_data = ds;
ds->sk = sk;
sock->state = SS_UNCONNECTED;
sock->ops = &pfk_divert_ops; /* forward decl below via struct */
return 0;
}
static int
pfk_divert_bind(struct socket *sock, struct sockaddr_unsized *uaddr,
int addr_len)
{
struct pfk_divert_sock *ds = pfk_ds(sock->sk);
unsigned long flags;
if (!ds)
return -EINVAL;
if (addr_len < (int)sizeof(struct sockaddr_in))
return -EINVAL;
/* BSD divsock stores the port in network order (compared against
* inp_lport / pf_divert.port as-is). */
ds->port = ((struct sockaddr_in *)uaddr)->sin_port;
if (ds->port == 0)
return -EADDRNOTAVAIL; /* divert port 0 not allowed */
spin_lock_irqsave(&pfk_divert_lock, flags);
if (!list_empty(&ds->link)) {
spin_unlock_irqrestore(&pfk_divert_lock, flags);
return -EADDRINUSE;
}
list_add_tail(&ds->link, &pfk_divert_list);
spin_unlock_irqrestore(&pfk_divert_lock, flags);
return 0;
}
static int
pfk_divert_recvmsg(struct socket *sock, struct msghdr *msg, size_t len,
int flags)
{
struct pfk_divert_sock *ds = pfk_ds(sock->sk);
struct pfk_divert_pkt *dp;
struct sk_buff *skb;
unsigned long iflags;
int copied;
if (!ds)
return -EINVAL;
if (msg_data_left(msg) == 0)
return -EINVAL;
for (;;) {
spin_lock_irqsave(&ds->lock, iflags);
if (!list_empty(&ds->q)) {
dp = list_first_entry(&ds->q, struct pfk_divert_pkt,
node);
list_del_init(&dp->node);
ds->qlen--;
spin_unlock_irqrestore(&ds->lock, iflags);
goto have;
}
spin_unlock_irqrestore(&ds->lock, iflags);
if (flags & MSG_DONTWAIT ||
READ_ONCE(sock->sk->sk_shutdown) != 0)
return -EAGAIN;
wait_event_interruptible(ds->wq,
!list_empty(&ds->q) ||
READ_ONCE(sock->sk->sk_shutdown) != 0);
if (signal_pending(current))
return -ERESTARTSYS;
}
have:
skb = dp->skb;
copied = min_t(size_t, len, skb->len);
if (skb_copy_datagram_msg(skb, 0, msg, copied)) {
pfk_divert_pkt_free(dp);
return -EFAULT;
}
/* metadata as control data (BSD equivalent: sockaddr_div) */
{
struct cmsghdr *cm = CMSG_FIRSTHDR(msg);
if (cm && msg->msg_controllen >= sizeof(struct cmsghdr) + sizeof(int)) {
msg->msg_controllen = 0; /* busybox-safe default */
cm = NULL;
}
if (cm) {
int ifindex = dp->ifindex;
cm->cmsg_level = SOL_SOCKET;
cm->cmsg_type = PFDIVERT_CMSG_IFINDEX;
cm->cmsg_len = CMSG_LEN(sizeof(int));
memcpy(CMSG_DATA(cm), &ifindex, sizeof(ifindex));
msg->msg_controllen = CMSG_SPACE(sizeof(int));
}
}
sock_net_set(sock->sk, &init_net);
ds->stats.divs_opackets++;
pfk_divert_pkt_free(dp);
return copied;
}
/*
* sendmsg: userspace hands the (possibly rewritten) packet back. The
* ip header inside the bytes decides the flow; for PF_DIVERT_TO we inject
* as input on the socket's last-recorded interface, otherwise we route.
*/
static int
pfk_divert_sendmsg(struct socket *sock, struct msghdr *msg, size_t len)
{
struct pfk_divert_sock *ds = pfk_ds(sock->sk);
struct sk_buff *skb;
struct pf_ip *ip;
int ifindex = 0;
int type = PF_DIVERT_TO;
struct cmsghdr *cm;
if (!ds)
return -EINVAL;
if (len > 65535)
return -EMSGSIZE;
for (cm = CMSG_FIRSTHDR(msg); cm; cm = CMSG_NXTHDR(msg, cm)) {
if (cm->cmsg_level != SOL_SOCKET)
continue;
if (cm->cmsg_type == PFDIVERT_CMSG_IFINDEX &&
cm->cmsg_len >= CMSG_LEN(sizeof(int)))
memcpy(&ifindex, CMSG_DATA(cm), sizeof(int));
if (cm->cmsg_type == PFDIVERT_CMSG_TYPE &&
cm->cmsg_len >= CMSG_LEN(sizeof(int)))
memcpy(&type, CMSG_DATA(cm), sizeof(int));
}
skb = alloc_skb(len + NET_SKB_PAD + NET_IP_ALIGN, GFP_KERNEL);
if (!skb)
return -ENOMEM;
skb_reserve(skb, NET_SKB_PAD + NET_IP_ALIGN);
if (memcpy_from_msg(skb_put(skb, len), msg, len)) {
kfree_skb(skb);
return -EFAULT;
}
skb->protocol = htons(ETH_P_IP);
if (ifindex <= 0)
ifindex = ds->last_ifindex; /* same path the packet came in */
if (type == PF_DIVERT_TO) {
/* deliver locally as if arrived on ifindex (default: last
* ingress iface seen by this socket's queue) */
struct net_device *dev = ifindex > 0 ?
dev_get_by_index(&init_net, ifindex) : NULL;
if (dev) {
struct ethhdr *eh;
skb->dev = dev;
dev_put(dev);
skb->mark |= PFK_SKIP_PF; /* avoid divert loop */
/*
* The receive path of an Ethernet device expects an
* L2 header: synthesise one (the packet keeps its
* original addresses; the stack only needs the
* ethertype to demultiplex).
*/
eh = skb_push(skb, ETH_HLEN);
if (!eh) {
kfree_skb(skb);
return -ENOMEM;
}
memset(eh, 0, ETH_HLEN);
memcpy(eh->h_dest, dev->dev_addr, ETH_ALEN);
memcpy(eh->h_source, dev->dev_addr, ETH_ALEN);
eh->h_proto = htons(ETH_P_IP);
skb_reset_mac_header(skb);
skb->protocol = htons(ETH_P_IP);
skb_pull(skb, ETH_HLEN); /* like eth_type_trans() */
/* data now points at the IP header again */
skb_reset_network_header(skb);
netif_rx(skb);
return (int)len;
}
/* no device: route below */
}
/* plain divert: route again (BSD divert_output -> ip_output) */
if (pskb_may_pull(skb, sizeof(*ip))) {
struct flowi4 fl4 = { };
struct dst_entry *d;
ip = (struct pf_ip *)skb->data;
fl4.daddr = ip->ip_dst.s_addr;
fl4.saddr = ip->ip_src.s_addr;
{
struct rtable *rt = ip_route_output_key(&init_net,
&fl4);
if (IS_ERR(rt))
rt = NULL;
d = rt ? &rt->dst : NULL;
}
if (d) {
skb_dst_set(skb, d);
skb_reset_network_header(skb);
if (!skb->dev)
skb->dev = skb_dst(skb)->dev;
d->output(&init_net, NULL, skb);
return (int)len;
}
}
kfree_skb(skb);
ds->stats.divs_errors++;
return -EHOSTUNREACH;
}
static int
pfk_divert_release(struct socket *sock)
{
struct sock *sk = sock->sk;
struct pfk_divert_sock *ds;
unsigned long flags;
if (!sk)
return 0;
ds = pfk_ds(sk);
if (ds) {
spin_lock_irqsave(&pfk_divert_lock, flags);
if (!list_empty(&ds->link))
list_del_init(&ds->link);
spin_unlock_irqrestore(&pfk_divert_lock, flags);
while (!list_empty(&ds->q)) {
struct pfk_divert_pkt *dp = list_first_entry(&ds->q,
struct pfk_divert_pkt, node);
list_del_init(&dp->node);
pfk_divert_pkt_free(dp);
}
kfree(ds);
sk->sk_user_data = NULL;
}
sock_orphan(sk);
sock_put(sk);
return 0;
}
static __poll_t
pfk_divert_poll(struct file *file, struct socket *sock,
poll_table *wait)
{
struct pfk_divert_sock *ds = pfk_ds(sock->sk);
__poll_t mask = 0;
if (ds)
poll_wait(file, &ds->wq, wait);
else
sock_poll_wait(file, sock, wait);
if (ds && !list_empty(&ds->q))
mask |= EPOLLIN | EPOLLRDNORM;
return mask;
}
static int
pfk_divert_ioctl(struct socket *sock, unsigned int cmd, unsigned long arg)
{
struct pfk_divert_sock *ds = pfk_ds(sock->sk);
if (!ds)
return -EINVAL;
switch (cmd) {
case 3: { /* DIVERTCTL_STATS-ish: export queue stats */
struct pfk_divert_stat st;
unsigned long flags;
spin_lock_irqsave(&ds->lock, flags);
st = ds->stats;
spin_unlock_irqrestore(&ds->lock, flags);
if (copy_to_user((void __user *)arg, &st, sizeof(st)))
return -EFAULT;
return 0;
}
default:
return -ENOIOCTLCMD;
}
}
static const struct proto_ops pfk_divert_ops = {
.family = PF_DIVERT_FAMILY,
.owner = THIS_MODULE,
.release = pfk_divert_release,
.bind = pfk_divert_bind,
.connect = sock_no_connect,
.socketpair = sock_no_socketpair,
.accept = sock_no_accept,
.getname = sock_no_getname,
.poll = pfk_divert_poll,
.ioctl = pfk_divert_ioctl,
.listen = sock_no_listen,
.shutdown = sock_no_shutdown,
.sendmsg = pfk_divert_sendmsg,
.recvmsg = pfk_divert_recvmsg,
.mmap = sock_no_mmap,
};
static const struct net_proto_family pfk_divert_family = {
.family = PF_DIVERT_FAMILY,
.create = pfk_divert_create,
.owner = THIS_MODULE,
};
int
pfk_divert_sock_register(void)
{
return sock_register(&pfk_divert_family);
}
void
pfk_divert_sock_unregister(void)
{
sock_unregister(PF_DIVERT_FAMILY);
} }
+13 -12
View File
@@ -5020,9 +5020,6 @@ pf_test_rule(struct pf_pdesc *pd, struct pf_rule **rm, struct pf_state **sm,
if (pd->virtual_proto != PF_VPROTO_FRAGMENT if (pd->virtual_proto != PF_VPROTO_FRAGMENT
&& !ctx.state_icmp && r->keep_state) { && !ctx.state_icmp && r->keep_state) {
pr_info_ratelimited("pfk: state-eligible proto=%d kstate=%d\n",
pd->proto, r->keep_state);
if (r->rule_flag & PFRULE_SRCTRACK && if (r->rule_flag & PFRULE_SRCTRACK &&
pf_insert_src_node(&ctx.sns[PF_SN_NONE], r, PF_SN_NONE, pf_insert_src_node(&ctx.sns[PF_SN_NONE], r, PF_SN_NONE,
pd->af, pd->src, NULL, NULL) != 0) { pd->af, pd->src, NULL, NULL) != 0) {
@@ -8286,6 +8283,10 @@ pf_test(sa_family_t af, int fwdir, struct pfk_ifnet *ifp, struct mbuf **m0)
if (!pf_status.running) if (!pf_status.running)
return (PF_PASS); return (PF_PASS);
if (m0 && *m0 && (*m0)->m_pkthdr.len >= 20 &&
((*m0)->m_data[9] == IPPROTO_ICMP))
pr_info_ratelimited("pfk: T1 enter dir=%d ifp=%px kif=%px\n",
fwdir, ifp, ifp ? ifp->if_pf_kif : NULL);
#if NCARP > 0 #if NCARP > 0
if (ifp->if_type == IFT_CARP) { if (ifp->if_type == IFT_CARP) {
@@ -8642,18 +8643,18 @@ done:
if (pd.destchg && pd.dir == PF_OUT) if (pd.destchg && pd.dir == PF_OUT)
pd.m->m_pkthdr.pf.flags |= PF_TAG_REROUTE; pd.m->m_pkthdr.pf.flags |= PF_TAG_REROUTE;
/*
* PFLINUX: OpenBSD tags the mbuf here (PACKET_TAG_PF_DIVERT) and
* netinet/ip_input.c diverts it right after pf_test(). This port has
* no ip_input layer to hook; the verdict is mbuf-exclusive at this
* point, so hand the packet to the divert socket immediately -
* same observable semantics, no tag round-trip.
*/
if (pd.dir == PF_IN && action == PF_PASS && if (pd.dir == PF_IN && action == PF_PASS &&
(r->divert.type == PF_DIVERT_TO || (r->divert.type == PF_DIVERT_TO ||
r->divert.type == PF_DIVERT_REPLY)) { r->divert.type == PF_DIVERT_REPLY)) {
struct pf_divert *divert; divert_packet(pd.m, pd.dir, r->divert.port);
pd.m = NULL;
if ((divert = pf_get_divert(pd.m))) {
pd.m->m_pkthdr.pf.flags |= PF_TAG_DIVERTED;
divert->addr = r->divert.addr;
divert->port = r->divert.port;
divert->rdomain = pd.rdomain;
divert->type = r->divert.type;
}
} }
if (action == PF_PASS && r->divert.type == PF_DIVERT_PACKET) if (action == PF_PASS && r->divert.type == PF_DIVERT_PACKET)
+11
View File
@@ -90,6 +90,17 @@ pfi_kif_alloc(const char *kif_name, int mflags)
kif->pfik_flags |= PFI_IFLAG_ANY; kif->pfik_flags |= PFI_IFLAG_ANY;
kif->pfik_flags_new |= PFI_IFLAG_ANY; kif->pfik_flags_new |= PFI_IFLAG_ANY;
} }
/*
* PFLINUX: OpenBSD creates the "ingress" and "egress" interface
* groups (ifgroups) automatically and both contain every interface;
* pf's direction (in/out ruleset) carries the actual meaning. Linux
* has no ifgroups, so emulate the groups as "any interface".
*/
if (!strcmp(kif->pfik_name, "ingress") ||
!strcmp(kif->pfik_name, "egress")) {
kif->pfik_flags |= PFI_IFLAG_ANY;
kif->pfik_flags_new |= PFI_IFLAG_ANY;
}
return (kif); return (kif);
} }
+2 -9
View File
@@ -2266,40 +2266,33 @@ pfioctl(dev_t dev, u_long cmd, caddr_t addr, int flags, struct proc *p)
sizeof(pr->anchor) || sizeof(pr->anchor) ||
strnlen(pr->anchor_call, sizeof(pr->anchor_call)) >= strnlen(pr->anchor_call, sizeof(pr->anchor_call)) >=
sizeof(pr->anchor_call)) { sizeof(pr->anchor_call)) {
error = ENAMETOOLONG; pr_info("pfkE: addrule1\n"); error = ENAMETOOLONG;
goto fail; goto fail;
} }
rule = pool_get(&pf_rule_pl, PR_WAITOK|PR_LIMITFAIL|PR_ZERO); rule = pool_get(&pf_rule_pl, PR_WAITOK|PR_LIMITFAIL|PR_ZERO);
if (rule == NULL) { if (rule == NULL) {
error = ENOMEM; pr_info("pfkE: addrule-pool\n"); error = ENOMEM;
goto fail; goto fail;
} }
if ((error = pf_rule_copyin(&pr->rule, rule))) { if ((error = pf_rule_copyin(&pr->rule, rule))) {
pr_info("pfkE: addrule copyin=%d\n", error);
pf_rule_free(rule); pf_rule_free(rule);
rule = NULL; rule = NULL;
goto fail; goto fail;
} }
if (pr->rule.return_icmp >> 8 > ICMP_MAXTYPE) { if (pr->rule.return_icmp >> 8 > ICMP_MAXTYPE) {
pr_info("pfkE: addrule icmp %x\n", pr->rule.return_icmp);
error = EINVAL; error = EINVAL;
pf_rule_free(rule); pf_rule_free(rule);
rule = NULL; rule = NULL;
goto fail; goto fail;
} }
if ((error = pf_rule_checkaf(rule))) { if ((error = pf_rule_checkaf(rule))) {
pr_info("pfkE: addrule checkaf=%d\n", error);
pf_rule_free(rule); pf_rule_free(rule);
rule = NULL; rule = NULL;
goto fail; goto fail;
} }
if (rule->src.addr.type == PF_ADDR_NONE || if (rule->src.addr.type == PF_ADDR_NONE ||
rule->dst.addr.type == PF_ADDR_NONE) { rule->dst.addr.type == PF_ADDR_NONE) {
pr_info("pfkE: addrule none src=%d dst=%d\n",
rule->src.addr.type, rule->dst.addr.type);
error = EINVAL; error = EINVAL;
pf_rule_free(rule); pf_rule_free(rule);
rule = NULL; rule = NULL;
+1
View File
@@ -2098,6 +2098,7 @@ pfr_commit_ktable(struct pfr_ktable *kt, time_t tzero)
struct pfr_ktable *shadow = kt->pfrkt_shadow; struct pfr_ktable *shadow = kt->pfrkt_shadow;
int nflags; int nflags;
if (shadow->pfrkt_cnt == NO_ADDRESSES) { if (shadow->pfrkt_cnt == NO_ADDRESSES) {
if (!(kt->pfrkt_flags & PFR_TFLAG_ACTIVE)) if (!(kt->pfrkt_flags & PFR_TFLAG_ACTIVE))
pfr_clstats_ktable(kt, tzero, 1); pfr_clstats_ktable(kt, tzero, 1);
+139 -4
View File
@@ -22,6 +22,8 @@
#include <net/pfvar_priv.h> #include <net/pfvar_priv.h>
extern int pf_test(sa_family_t, int, struct pfk_ifnet *, struct mbuf **); extern int pf_test(sa_family_t, int, struct pfk_ifnet *, struct mbuf **);
extern void divert_packet(struct mbuf *, int, u_int16_t);
extern struct pf_divert *pf_find_divert(struct mbuf *);
extern struct workqueue_struct *pfk_netisr_wq; extern struct workqueue_struct *pfk_netisr_wq;
/* PFLINUX: netisr work item — carries ownership of one sk_buff */ /* PFLINUX: netisr work item — carries ownership of one sk_buff */
@@ -33,8 +35,8 @@ struct pfk_pkt {
int dir; int dir;
}; };
#define PFK_DONE_IN 0x50460010u /* skb->mark bit: PF_IN pass completed */ #define PFK_DONE_IN 0x00000001u /* skb->mark bit: PF_IN pass completed */
#define PFK_DONE_OUT 0x50460020u /* skb->mark bit: PF_OUT pass completed */ #define PFK_DONE_OUT 0x00000002u /* skb->mark bit: PF_OUT pass completed */
static void static void
pfk_pkt_reinject(struct pfk_pkt *pk) pfk_pkt_reinject(struct pfk_pkt *pk)
@@ -69,14 +71,117 @@ pfk_pkt_reinject(struct pfk_pkt *pk)
kfree(pk); kfree(pk);
} }
/*
* Reverse NAT: pf rewrote the destination of an inbound packet (the reply
* of a translated flow). OpenBSD re-routes such a packet in ip_input()
* (PF_TAG_REROUTE); Linux has no such layer, so re-route it here and push
* it out through the new egress device.
*/
static void
pfk_reroute(struct sk_buff *skb)
{
struct flowi4 fl4 = { };
struct rtable *rt;
struct iphdr *iph = ip_hdr(skb);
fl4.daddr = iph->daddr;
/*
* Leave the source empty: the packet keeps the original source
* (the peer's address), but the kernel would reject a route lookup
* with a non-local source (ENETUNREACH).
*/
fl4.saddr = 0;
fl4.flowi4_oif = 0;
fl4.flowi4_mark = 0;
fl4.flowi4_scope = RT_SCOPE_UNIVERSE;
rt = ip_route_output_key(&init_net, &fl4);
if (IS_ERR(rt) || rt == NULL) {
kfree_skb(skb);
return;
}
skb_dst_set(skb, &rt->dst);
skb->dev = rt->dst.dev;
skb_reset_network_header(skb);
rt->dst.output(&init_net, skb->sk, skb);
}
/*
* PFLINUX: pf rewrote the IPv4 addresses of the packet (NAT). OpenBSD's
* ip_output() recomputes the IP header checksum on every packet it sends;
* Linux does not, so fix it up here after pf touched the header.
*/
/*
* pf rewrote the addresses of this packet. OpenBSD recomputes the IP header
* checksum in ip_output() and the transport checksum is patched incrementally
* by pf - but that only works on a *materialized* checksum, and VM-to-VM
* traffic routinely arrives with the transport checksum still uncomputed
* (the sender's offload never completed on the tap). So recompute from
* scratch here:
*
* - GSO segments: hand the job back to the NIC (CHECKSUM_PARTIAL with the
* transport offset); computing in software would only cover the first
* segment and silently corrupt the rest (this is what kills bulk TCP).
* - everything else: compute the transport checksum over the new
* pseudo-header in software, then the IP header checksum.
*/
static void
pfk_fix_csum_after_translate(struct sk_buff *skb)
{
struct iphdr *iph;
unsigned int hlen, len;
__sum16 *csum;
__u8 proto;
if (!pskb_may_pull(skb, sizeof(struct iphdr)))
return;
iph = ip_hdr(skb);
hlen = iph->ihl * 4;
proto = iph->protocol;
len = skb->len - hlen;
if (proto == IPPROTO_TCP || proto == IPPROTO_UDP) {
if (!pskb_may_pull(skb, hlen + (proto == IPPROTO_TCP ?
sizeof(struct tcphdr) : sizeof(struct udphdr))))
return;
csum = (__sum16 *)(skb->data + hlen +
(proto == IPPROTO_TCP ? offsetof(struct tcphdr, check)
: offsetof(struct udphdr, check)));
if (skb_is_gso(skb)) {
skb->csum_start = (unsigned short)
(((unsigned char *)skb->data + hlen) - skb->head);
skb->csum_offset = proto == IPPROTO_TCP ?
offsetof(struct tcphdr, check) :
offsetof(struct udphdr, check);
skb->ip_summed = CHECKSUM_PARTIAL;
} else {
*csum = 0;
*csum = csum_tcpudp_magic(iph->saddr, iph->daddr, len,
proto, skb_checksum(skb, hlen, len, 0));
skb->ip_summed = CHECKSUM_NONE;
}
}
iph = ip_hdr(skb); /* pskb_may_pull may have moved the data */
iph->check = 0;
iph->check = csum_fold(csum_partial((__u8 *)iph, iph->ihl * 4, 0));
}
static void static void
pfk_pkt_work(struct work_struct *w) pfk_pkt_work(struct work_struct *w)
{ {
struct pfk_pkt *pk = container_of(w, struct pfk_pkt, work); struct pfk_pkt *pk = container_of(w, struct pfk_pkt, work);
struct mbuf *m, *m0; struct mbuf *m, *m0;
struct sk_buff *orig; struct sk_buff *orig;
__be32 orig_dst = 0, orig_src = 0;
int action; int action;
if (pk->af == AF_INET && pskb_may_pull(pk->skb, sizeof(struct iphdr))) {
orig_dst = ip_hdr(pk->skb)->daddr;
orig_src = ip_hdr(pk->skb)->saddr;
}
m = pfk_m_wrap_skb(pk->skb, pk->af); m = pfk_m_wrap_skb(pk->skb, pk->af);
if (!m) { if (!m) {
pfk_pkt_reinject(pk); /* like "pf not consulted" */ pfk_pkt_reinject(pk); /* like "pf not consulted" */
@@ -91,10 +196,27 @@ pfk_pkt_work(struct work_struct *w)
* and packet walk run concurrently from here on — documented. */ * and packet walk run concurrently from here on — documented. */
action = pf_test(pk->af, pk->dir, pk->ifp, &m); action = pf_test(pk->af, pk->dir, pk->ifp, &m);
if (pk->af == AF_INET && orig_src != 0 &&
pskb_may_pull(pk->skb, sizeof(struct iphdr)) &&
(ip_hdr(pk->skb)->saddr != orig_src ||
ip_hdr(pk->skb)->daddr != orig_dst))
pfk_fix_csum_after_translate(pk->skb);
if (m == m0) { if (m == m0) {
/* same buffer, possibly rewritten in place: our wrapper /* same buffer, possibly rewritten in place: our wrapper
* held one extra skb reference — release it */ * held one extra skb reference — release it */
m_freem(m); m_freem(m);
if (action == PF_PASS && orig_dst != 0 &&
pk->af == AF_INET && pk->dir == PF_IN &&
pskb_may_pull(pk->skb, sizeof(struct iphdr)) &&
ip_hdr(pk->skb)->daddr != orig_dst) {
/* pf translated the destination (reverse NAT):
* re-route instead of delivering locally */
pfk_reroute(pk->skb);
kfree(pk);
return;
}
if (action == PF_PASS) { if (action == PF_PASS) {
pfk_pkt_reinject(pk); pfk_pkt_reinject(pk);
return; return;
@@ -135,15 +257,27 @@ pfk_enqueue_verdict(int af, struct sk_buff *skb,
switch (st->hook) { switch (st->hook) {
case NF_INET_PRE_ROUTING: case NF_INET_PRE_ROUTING:
/* OpenBSD evaluates the IN ruleset in ip_input(); every
* arriving packet passes it. */
dir = PF_IN; dir = PF_IN;
break; break;
case NF_INET_FORWARD:
/* OpenBSD evaluates the OUT ruleset of a forwarded packet in
* ip_forward() (pf_test(PF_FWD)); the IN ruleset was already
* applied at input time. Without this, transit traffic never
* sees the "out" rules and state matching for replies is
* impossible. */
dir = PF_OUT;
break;
case NF_INET_LOCAL_OUT: case NF_INET_LOCAL_OUT:
case NF_INET_POST_ROUTING: case NF_INET_POST_ROUTING:
dir = PF_OUT; dir = PF_OUT;
break; break;
default: default:
return NF_ACCEPT; /* LOCAL_IN/FORWARD */ return NF_ACCEPT; /* LOCAL_IN */
} }
if (skb->mark & PFK_SKIP_PF)
return NF_ACCEPT; /* reinjected by divert: don't re-filter */
if (skb->mark & (dir == PF_IN ? PFK_DONE_IN : PFK_DONE_OUT)) if (skb->mark & (dir == PF_IN ? PFK_DONE_IN : PFK_DONE_OUT))
return NF_ACCEPT; return NF_ACCEPT;
@@ -155,7 +289,8 @@ pfk_enqueue_verdict(int af, struct sk_buff *skb,
if (dir == PF_IN) if (dir == PF_IN)
ifp = pfk_ifp_bydev(st->in ? st->in : skb->dev); ifp = pfk_ifp_bydev(st->in ? st->in : skb->dev);
else else
ifp = pfk_ifp_bydev(skb->dev ? skb->dev : st->out); ifp = pfk_ifp_bydev(st->out ? st->out :
(skb->dev ? skb->dev : NULL));
if (!ifp) if (!ifp)
return NF_ACCEPT; return NF_ACCEPT;
+17 -4
View File
@@ -54,9 +54,6 @@ pfk_ioctl_io(struct file *filp, unsigned int cmd, unsigned long arg)
p.p_ucred = &cred; p.p_ucred = &cred;
p.p_p = &pp; p.p_p = &pp;
if (cmd == DIOCADDRULE)
pr_info("pfkE: ioctl sz=%d kern_size=%d rule=%d\n", (int)sz,
(int)sizeof(struct pfioc_rule), (int)sizeof(struct pf_rule));
kdata = kzalloc(sz ? sz : sizeof(long), GFP_KERNEL); kdata = kzalloc(sz ? sz : sizeof(long), GFP_KERNEL);
if (!kdata) if (!kdata)
return -ENOMEM; return -ENOMEM;
@@ -96,6 +93,10 @@ static struct miscdevice pfk_dev = {
extern void pf_status_init(void); extern void pf_status_init(void);
extern int pfattach(int); extern int pfattach(int);
extern int pfk_divert_sock_register(void);
extern int pfk_pflog_register(void);
extern void pfk_pflog_unregister(void);
extern void pfk_divert_sock_unregister(void);
static void static void
pfk_pfi_event(int added, struct pfk_ifnet *ifp) pfk_pfi_event(int added, struct pfk_ifnet *ifp)
@@ -134,15 +135,25 @@ static int __init pfk_init(void)
pfattach(0); pfattach(0);
pfk_if_set_event_cb(pfk_pfi_event); pfk_if_set_event_cb(pfk_pfi_event);
pfk_if_iterate(pfk_pfi_attach_one); pfk_if_iterate(pfk_pfi_attach_one);
err = pfk_hooks_register(); err = pfk_pflog_register();
if (err) if (err)
goto err_if; goto err_if;
err = pfk_divert_sock_register();
if (err)
goto err_pflog;
err = pfk_hooks_register();
if (err)
goto err_divert;
err = misc_register(&pfk_dev); err = misc_register(&pfk_dev);
if (err) if (err)
goto err_hooks; goto err_hooks;
pr_info("pfk: PF-on-Linux engine loaded (OpenBSD 8.0 base)\n"); pr_info("pfk: PF-on-Linux engine loaded (OpenBSD 8.0 base)\n");
return 0; return 0;
err_hooks: err_hooks:
pfk_divert_sock_unregister();
err_divert:
pfk_pflog_unregister();
err_pflog:
pfk_hooks_unregister(); pfk_hooks_unregister();
err_if: err_if:
pfk_if_exit(); pfk_if_exit();
@@ -161,6 +172,8 @@ static void __exit pfk_exit(void)
* self-rearms (pf_purge re-arms on every run) and would keep the * self-rearms (pf_purge re-arms on every run) and would keep the
* workqueues non-empty forever (observed rmmod hang). */ * workqueues non-empty forever (observed rmmod hang). */
misc_deregister(&pfk_dev); misc_deregister(&pfk_dev);
pfk_divert_sock_unregister();
pfk_pflog_unregister();
pfk_net_lock(); pfk_net_lock();
pf_status.running = 0; pf_status.running = 0;
pfk_net_unlock(); pfk_net_unlock();
+299
View File
@@ -0,0 +1,299 @@
/*
* PF-on-Linux: pflog backend (ISC 2026)
*
* OpenBSD logs matched packets to the pflog(4) *network interface*, which
* pflogd(8) reads through bpf(4). Linux has neither if_pflog-style virtual
* interfaces exposed to bpf nor a DLT_PFLOG consumer, so this port offers the
* same record format over a character device:
*
* /dev/pflog (0600) - read() returns one record at a time:
* struct pflog_hdr followed by the captured
* packet bytes (truncated to PFLOG_COPY_SIZE).
*
* poll() reports readable when a record is queued. A single consumer is the
* real use case (pflogd), which is why a chardev - not netlink multicast -
* was chosen; the deviation is documented in docs/porting-notes.md.
*
* The records are byte-compatible with OpenBSD's pflog(4) so tcpdump/wireshark
* read the pcap with linktype DLT_PFLOG (117).
*/
#include <linux/kernel.h>
#include <linux/module.h>
#include <linux/miscdevice.h>
#include <linux/fs.h>
#include <linux/mm.h>
#include <linux/poll.h>
#include <linux/slab.h>
#include <linux/spinlock.h>
#include <linux/wait.h>
#include <linux/timekeeping.h>
#include <linux/uaccess.h>
#include <linux/netdevice.h>
#include <pfk.h>
#include <pfk_api.h>
/* OpenBSD sys/net/pflog.h */
#define PFLOG_IFNAMSIZ 16
#define PFLOG_RULESET_NAME_SIZE 16
#define PFLOG_HDRLEN 64 /* sizeof(struct pfk_pflog_hdr) */
#define PFLOG_COPY_SIZE 160
/* byte-compatible with OpenBSD's <net/pflog.h> (sizeof == 64) */
struct pfk_pflog_hdr {
struct {
s64 tv_sec;
s64 tv_usec;
} pflog_ts;
u8 pflog_af;
u8 pflog_reason;
u8 pflog_ifname[PFLOG_IFNAMSIZ];
u8 pflog_ruleset[PFLOG_RULESET_NAME_SIZE];
u8 pflog_nr;
u8 pflog_anc;
u8 pflog_flags;
u8 pflog_pad[9];
u16 pflog_len; /* captured packet length */
} __packed;
struct pfk_pflog_rec {
struct list_head list;
size_t len; /* header + payload */
char data[]; /* pfk_pflog_hdr, then the packet */
};
#define PFK_PFLOG_MAX_QUEUE 256u
#define PFK_PFLOG_MAX_BYTES (1u << 20)
static LIST_HEAD(pflog_list);
static DEFINE_SPINLOCK(pflog_lock);
static DECLARE_WAIT_QUEUE_HEAD(pflog_wq);
static unsigned long pflog_queued, pflog_bytes, pflog_dropped;
static u64 pflog_seq;
/*
* Queue one record. Called from the packet path (process context here: the
* data path runs in pfk_netisr_wq), so a GFP_ATOMIC allocation and a bounded
* queue keep it safe even if a future caller appears in softirq context.
*/
static void
pfk_pflog_put(struct pfk_pflog_hdr *hdr, const void *pkt, size_t pktlen)
{
struct pfk_pflog_rec *rec;
size_t len = sizeof(*hdr) + pktlen;
unsigned long flags;
if (READ_ONCE(pflog_queued) >= PFK_PFLOG_MAX_QUEUE ||
READ_ONCE(pflog_bytes) + len > PFK_PFLOG_MAX_BYTES) {
pflog_dropped++;
return;
}
rec = kmalloc(struct_size(rec, data, len), GFP_ATOMIC);
if (rec == NULL) {
pflog_dropped++;
return;
}
rec->len = len;
memcpy(rec->data, hdr, sizeof(*hdr));
memcpy(rec->data + sizeof(*hdr), pkt, pktlen);
spin_lock_irqsave(&pflog_lock, flags);
list_add_tail(&rec->list, &pflog_list);
pflog_queued++;
pflog_bytes += len;
pflog_seq++;
spin_unlock_irqrestore(&pflog_lock, flags);
wake_up_interruptible(&pflog_wq);
}
/* copy the leading bytes of the packet (the mbuf chain may be a wrapper) */
static size_t
pfk_pflog_pull(struct mbuf *m, char *buf, size_t want)
{
struct sk_buff *skb = m ? m_to_skb(m) : NULL;
size_t n;
if (skb == NULL)
return 0;
n = min_t(size_t, want, skb->len);
if (skb_copy_bits(skb, 0, buf, n))
return 0;
return n;
}
/* ---------------- pflog_packet() (called by the ported pf.c) ---------------- */
int
pflog_packet(struct pf_pdesc *pd, u_int8_t reason, struct pf_rule *rm,
struct pf_rule *am, struct pf_ruleset *ruleset, struct pf_rule *cm)
{
struct pfk_pflog_hdr hdr;
char pkt[PFLOG_COPY_SIZE];
struct pf_rule *r;
size_t n;
if (pd == NULL || pd->m == NULL)
return (0);
memset(&hdr, 0, sizeof(hdr));
{
struct timespec64 ts;
ktime_get_real_ts64(&ts);
hdr.pflog_ts.tv_sec = ts.tv_sec;
hdr.pflog_ts.tv_usec = ts.tv_nsec / 1000;
}
hdr.pflog_af = pd->af;
hdr.pflog_reason = reason;
r = cm ? cm : (am ? am : rm);
if (r) {
strscpy((char *)hdr.pflog_ifname,
pd->kif ? pd->kif->pfik_name : "",
sizeof(hdr.pflog_ifname));
strscpy((char *)hdr.pflog_ruleset,
(ruleset && ruleset->anchor) ? ruleset->anchor->name : "",
sizeof(hdr.pflog_ruleset));
hdr.pflog_nr = r->nr;
hdr.pflog_anc = 0;
hdr.pflog_flags = r->log;
}
n = pfk_pflog_pull(pd->m, pkt, sizeof(pkt));
hdr.pflog_len = cpu_to_be16(n); /* BSD stores it in network order */
pfk_pflog_put(&hdr, pkt, n);
return (0);
}
/* ---------------- /dev/pflog ---------------- */
static int
pfk_pflog_open(struct inode *inode, struct file *filp)
{
filp->private_data = NULL;
return nonseekable_open(inode, filp);
}
static ssize_t
pfk_pflog_read(struct file *filp, char __user *buf, size_t count, loff_t *ppos)
{
struct pfk_pflog_rec *rec = filp->private_data;
unsigned long flags;
size_t off, n;
spin_lock_irqsave(&pflog_lock, flags);
if (rec == NULL) {
if (list_empty(&pflog_list)) {
spin_unlock_irqrestore(&pflog_lock, flags);
if (filp->f_flags & O_NONBLOCK)
return -EAGAIN;
if (wait_event_interruptible(pflog_wq,
!list_empty(&pflog_list)))
return -ERESTARTSYS;
spin_lock_irqsave(&pflog_lock, flags);
if (list_empty(&pflog_list)) {
spin_unlock_irqrestore(&pflog_lock, flags);
return -EAGAIN;
}
}
rec = list_first_entry(&pflog_list, struct pfk_pflog_rec, list);
list_del(&rec->list);
pflog_queued--;
pflog_bytes -= rec->len;
filp->private_data = rec;
}
spin_unlock_irqrestore(&pflog_lock, flags);
/* partial reads resume through *ppos (record is pinned to the file) */
off = *ppos;
if (off >= rec->len) {
kfree(rec);
filp->private_data = NULL;
*ppos = 0;
return 0;
}
n = min(count, rec->len - off);
if (copy_to_user(buf, rec->data + off, n))
return -EFAULT;
*ppos += n;
if (*ppos == rec->len) {
kfree(rec);
filp->private_data = NULL;
*ppos = 0;
}
return n;
}
static __poll_t
pfk_pflog_poll(struct file *filp, poll_table *wait)
{
__poll_t mask = 0;
poll_wait(filp, &pflog_wq, wait);
if (filp->private_data != NULL)
mask |= EPOLLIN | EPOLLRDNORM;
else if (!list_empty(&pflog_list))
mask |= EPOLLIN | EPOLLRDNORM;
return mask;
}
static long
pfk_pflog_ioctl(struct file *filp, unsigned int cmd, unsigned long arg)
{
struct pfk_pflog_stat st;
switch (cmd) {
case PFKIOCGETPFLOGSTAT:
st.queued = pflog_queued;
st.bytes = pflog_bytes;
st.dropped = pflog_dropped;
st.seq = pflog_seq;
if (copy_to_user((void __user *)arg, &st, sizeof(st)))
return -EFAULT;
return 0;
default:
return -ENOTTY;
}
}
static const struct file_operations pfk_pflog_fops = {
.owner = THIS_MODULE,
.open = pfk_pflog_open,
.read = pfk_pflog_read,
.poll = pfk_pflog_poll,
.unlocked_ioctl = pfk_pflog_ioctl,
.compat_ioctl = compat_ptr_ioctl,
};
static struct miscdevice pfk_pflog_dev = {
.minor = MISC_DYNAMIC_MINOR,
.name = "pflog",
.fops = &pfk_pflog_fops,
.mode = 0600,
};
int
pfk_pflog_register(void)
{
return misc_register(&pfk_pflog_dev);
}
void
pfk_pflog_unregister(void)
{
struct pfk_pflog_rec *rec, *tmp;
misc_deregister(&pfk_pflog_dev);
spin_lock(&pflog_lock);
list_for_each_entry_safe(rec, tmp, &pflog_list, list) {
list_del(&rec->list);
kfree(rec);
}
pflog_queued = 0;
pflog_bytes = 0;
spin_unlock(&pflog_lock);
}
+77
View File
@@ -0,0 +1,77 @@
{"version": 2, "width": 80, "height": 24, "timestamp": 1794445553, "env": {"SHELL": null, "TERM": "dumb"}}
[1.622488, "o", "\u001b[1m===============================================================\u001b[0m\r\n"]
[1.623391, "o", "\u001b[1m PF on Linux - the OpenBSD PF 8.0 engine inside the Linux kernel\u001b[0m\r\n\u001b[1m===============================================================\u001b[0m\r\n\r\nLab: 3 Alpine VMs under libvirt.\r\n pftest-pf0 = firewall (kernel 7.3.4 built from source + pf.ko)\r\n pftest-cli = client 10.0.1.10 pftest-srv = server 10.0.2.20\r\n\r\n\u001b[1m--- 1. our kernel, the OpenBSD engine as a module ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# uname -r\u001b[0m\r\n"]
[1.885894, "o", "7.3.4\r\n"]
[2.289113, "o", "\u001b[1;36mpftest-pf0# lsmod | grep '^pf ' || echo 'pf: not loaded yet'\u001b[0m\r\n"]
[2.565982, "o", "pf 552960 0\r\n"]
[2.968407, "o", "\u001b[1;36mpftest-pf0# insmod /opt/pf/pf.ko && dmesg | tail -3\u001b[0m\r\n"]
[3.226044, "o", "insmod: ERROR: could not insert module /opt/pf/pf.ko: File exists\r\n"]
[3.629164, "o", "\r\n"]
[3.629206, "o", "\u001b[1m--- 2. pfctl talks to the module over the OpenBSD ioctl ABI ---\u001b[0m\r\n"]
[3.629219, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -s info | head -4\u001b[0m\r\n"]
[3.906215, "o", "Status: Disabled for 0 days 00:03:33 Debug: err\r\n\r\nState Table Total Rate\r\n current entries 0 \r\n"]
[4.310059, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -e && /opt/pf/pfctl -s info | head -1\u001b[0m\r\n"]
[4.574117, "o", "Status: Enabled Debug: err\r\npf enabled\r\n"]
[4.977439, "o", "\r\n\u001b[1m--- 3. a real pf.conf: tables, stateful rules, an explicit drop ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# cat /tmp/demo-pf.conf\u001b[0m\r\n"]
[5.245993, "o", "# PF-on-Linux demo ruleset (pf.conf syntax, real OpenBSD pfctl)\r\nset block-policy return\r\ntable <trusted> { 10.0.1.0/24 }\r\n\r\n# transit traffic: stateful, table-driven\r\npass in quick on ingress proto icmp from <trusted> keep state\r\npass out quick on egress proto icmp keep state\r\n\r\n# deny a specific destination\r\nblock drop in quick proto icmp to 10.0.9.99\r\n\r\n# everything else\r\npass in quick\r\npass out quick\r\n"]
[5.649022, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'rules loaded'\u001b[0m\r\n"]
[5.926196, "o", "rules loaded\r\n"]
[6.33004, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -sr\u001b[0m\r\n"]
[6.614075, "o", "pass in quick on ingress proto icmp from <trusted> to any\r\npass out quick on egress proto icmp all\r\nblock drop in quick inet proto icmp from any to 10.0.9.99\r\npass in quick all flags S/SA\r\npass out quick all flags S/SA\r\n"]
[7.017049, "o", "\r\n\u001b[1m--- 4. transit traffic is allowed and stateful ---\u001b[0m\r\n\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -3\u001b[0m\r\n"]
[8.256385, "o", "--- 10.0.2.20 ping statistics ---\r\n2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.343/0.381/0.419 ms\r\n"]
[8.659624, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -ss | grep -E 'icmp' | head -4\u001b[0m\r\n"]
[8.94608, "o", "all icmp 10.0.2.20:8 <- 10.0.1.10:4987 0:0\r\nall icmp 10.0.1.10:4987 -> 10.0.2.20:8 0:0\r\n"]
[9.348967, "o", "\r\n"]
[9.349022, "o", "\u001b[1m--- 5. tables are live objects ---\u001b[0m\r\n"]
[9.349263, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -t trusted -T show\u001b[0m\r\n"]
[9.618085, "o", " 10.0.1.0/24\r\n"]
[10.022258, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -s Tables\u001b[0m\r\n"]
[10.309891, "o", "trusted\r\n"]
[10.712978, "o", "\r\n\u001b[1m--- 6. the drop rule actually drops ---\u001b[0m\r\n"]
[10.713088, "o", "\u001b[1;36mpftest-pf0# cat > /tmp/demo-block.conf <<EOF\r\nblock drop in quick proto icmp to 10.0.2.20\r\npass in quick\r\npass out quick\r\nEOF\u001b[0m\r\n"]
[11.397835, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-block.conf && echo 'block rules loaded'\u001b[0m\r\n"]
[11.650256, "o", "block rules loaded\r\n"]
[12.05359, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -3\u001b[0m\r\n"]
[15.280329, "o", "\r\n--- 10.0.2.20 ping statistics ---\r\n2 packets transmitted, 0 packets received, 100% packet loss\r\n"]
[15.683815, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -sr -vv | head -6\u001b[0m\r\n"]
[15.98217, "o", "@0 block drop in quick inet proto icmp from any to 10.0.2.20\r\n [ Evaluations: 3 Packets: 2 Bytes: 168 States: 0 ]\r\n [ Inserted: uid 0 pid 1877 State Creations: 0 ]\r\n@1 pass in quick all flags S/SA\r\n [ Evaluations: 1 Packets: 28 Bytes: 9296 States: 1 ]\r\n [ Inserted: uid 0 pid 1877 State Creations: 1 ]\r\n"]
[16.384573, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'back to the stateful ruleset'\u001b[0m\r\n"]
[16.670067, "o", "back to the stateful ruleset\r\n"]
[17.0729, "o", "\r\n\u001b[1m--- 7. NAT: the source is translated on the way out, restored on the way back ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# cat > /tmp/demo-nat.conf <<EOF\r\npass out quick on egress from 10.0.1.0/24 to any nat-to (eth2)\r\npass in quick on ingress proto icmp keep state\r\npass out quick on egress proto icmp keep state\r\nEOF\u001b[0m\r\n"]
[17.740601, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-nat.conf && echo 'nat rules loaded'\u001b[0m\r\n"]
[18.018113, "o", "nat rules loaded\r\n"]
[18.42114, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -3\u001b[0m\r\n"]
[19.636475, "o", "--- 10.0.2.20 ping statistics ---\r\n2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.325/0.362/0.400 ms\r\n"]
[20.038543, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -ss | grep -E 'icmp' | head -4\u001b[0m\r\n"]
[20.310123, "o", "all icmp 10.0.2.20:8 <- 10.0.1.10:4999 0:0\r\nall icmp 10.0.2.1:7697 (10.0.1.10:4999) -> 10.0.2.20:8 0:0\r\n"]
[20.712246, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'back to the stateful ruleset'\u001b[0m\r\n"]
[20.990114, "o", "back to the stateful ruleset\r\n"]
[21.392794, "o", "\r\n"]
[21.393027, "o", "\u001b[1m--- 8. pflog: logged packets reach userspace (/dev/pflog) ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# cat > /tmp/demo-log.conf <<EOF\r\npass in quick log proto icmp from 10.0.1.10 keep state\r\npass out quick\r\nEOF\u001b[0m\r\n"]
[22.057041, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-log.conf && echo 'log rule loaded'\u001b[0m\r\n"]
[22.329918, "o", "log rule loaded\r\n"]
[22.732644, "o", "\u001b[1;36mpftest-pf0# chmod +x /tmp/pflogd; rm -f /tmp/pflog.pcap; (setsid /tmp/pflogd -c 2 /tmp/pflog.pcap >/tmp/pflogd.log 2>&1 </dev/null &); sleep 1; echo 'pflogd collecting 2 records'\u001b[0m\r\n"]
[23.981016, "o", "pflogd collecting 2 records\r\n"]
[24.384736, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -2\u001b[0m\r\n"]
[25.612472, "o", "2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.356/0.429/0.502 ms\r\n"]
[28.017578, "o", "\u001b[1;36mpftest-pf0# cat /tmp/pflogd.log; ls -l /tmp/pflog.pcap; echo 'pcap header (magic d4c3b2a1, linktype 0x75=DLT_PFLOG):'; od -An -tx1 -N24 /tmp/pflog.pcap\u001b[0m\r\n"]
[28.277996, "o", "pflogd: 2 records\r\n-rw------- 1 root root 352 Nov 12 01:06 /tmp/pflog.pcap\r\npcap header (magic d4c3b2a1, linktype 0x75=DLT_PFLOG):\r\n d4 c3 b2 a1 02 00 04 00 00 00 00 00 00 00 00 00\r\n ff ff 00 00 75 00 00 00\r\n"]
[28.681267, "o", "\u001b[1;36mpftest-pf0# pkill pflogd 2>/dev/null; /opt/pf/pfctl -f /tmp/demo-pf.conf >/dev/null\u001b[0m\r\n"]
[29.352889, "o", "\r\n\u001b[1m--- 9. divert-to: the packet goes to userspace and comes back ---\u001b[0m\r\n"]
[29.35314, "o", "\u001b[1;36mpftest-pf0# cat /tmp/demo-divert.conf\u001b[0m\r\n"]
[29.625878, "o", "pass in quick proto icmp from 10.0.1.10 to 10.0.1.1 divert-to \"10.0.1.1\" port 10000 keep state\r\npass out quick\r\n"]
[30.028664, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-divert.conf && echo 'divert rule loaded'\u001b[0m\r\n"]
[30.317998, "o", "divert rule loaded\r\n"]
[30.719927, "o", "\u001b[1;36mpftest-pf0# chmod +x /tmp/pdivert; (setsid /tmp/pdivert -p 10000 -f >/tmp/pdivert.log 2>&1 </dev/null &); sleep 1; pgrep pdivert\u001b[0m\r\n"]
[31.941535, "o", "1956\r\n"]
[32.344, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.1.1 | tail -3\u001b[0m\r\n"]
[33.584192, "o", "--- 10.0.1.1 ping statistics ---\r\n2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.228/0.242/0.257 ms\r\n"]
[33.987279, "o", "\u001b[1;36mpftest-pf0# head -3 /tmp/pdivert.log\u001b[0m\r\n"]
[34.261872, "o", "pdivert: listening on divert port 10000\r\npdivert: got 84 bytes 10.0.1.10 -> 10.0.1.1\r\npdivert: got 84 bytes 10.0.1.10 -> 10.0.1.1\r\n"]
[34.664226, "o", " (pdivert flipped the last payload byte and fixed the ICMP checksum)\r\n\r\n"]
[34.664382, "o", "\u001b[1m--- 10. shutdown ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# pkill pdivert; /opt/pf/pfctl -f /dev/null; /opt/pf/pfctl -d; echo 'pf disabled'\u001b[0m\r\n"]
[34.938113, "o", "pf disabled\r\npf disabled\r\n"]
[35.340577, "o", "\u001b[1;36mpftest-pf0# lsmod | grep '^pf '\u001b[0m\r\n"]
[35.617928, "o", "pf 552960 0\r\n"]
[36.021187, "o", "\r\n\u001b[1mdemo over - port, gates and docs:\u001b[0m\r\n\u001b[1m https://git.labexposed.com/lgcosta/pf-linux-port\u001b[0m\r\n\r\n"]
+161
View File
@@ -0,0 +1,161 @@
#!/usr/bin/env python3
"""
PF-on-Linux demo recorder -> asciicast v2 (.cast)
Every byte shown comes from the REAL lab (Alpine VMs under libvirt, kernel
7.3.4 built from source with our pf.ko). Only the pacing is scripted.
Usage:
./scripts/demo-record.py [--out out/demo-pf-linux.cast] [--quick]
Play back with: asciinema play out/demo-pf-linux.cast
Upload with: asciinema upload out/demo-pf-linux.cast
"""
import argparse
import json
import os
import shlex
import subprocess
import sys
import time
REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
DEB = os.environ.get("DEB", "root@192.168.1.242")
PF0 = os.environ.get("PF0_IP", "192.168.122.8")
CLI = os.environ.get("CLI_IP", "10.0.1.10")
SRV = os.environ.get("SRV_IP", "10.0.2.20")
KEY = os.path.join(os.environ.get("HOME", "/root"), ".ssh/pflab_ed")
CONF = """# PF-on-Linux demo ruleset (pf.conf syntax, real OpenBSD pfctl)
set block-policy return
table <trusted> { 10.0.1.0/24 }
# transit traffic: stateful, table-driven
pass in quick on ingress proto icmp from <trusted> keep state
pass out quick on egress proto icmp keep state
# deny a specific destination
block drop in quick proto icmp to 10.0.9.99
# everything else
pass in quick
pass out quick
"""
DIVERT_CONF = """pass in quick proto icmp from 10.0.1.10 to 10.0.1.1 divert-to "10.0.1.1" port 10000 keep state
pass out quick
"""
def sh(cmd, timeout=40):
p = subprocess.run(cmd, shell=True, capture_output=True, text=True,
timeout=timeout)
return (p.stdout or "") + (p.stderr or "")
def on_pf0(cmd, timeout=40):
return sh(f"ssh -o ConnectTimeout=8 -o StrictHostKeyChecking=accept-new "
f"-i {KEY} root@{PF0} {shlex.quote(cmd)}", timeout)
def on_vm(ip, cmd, timeout=40):
return sh(f"ssh -o ConnectTimeout=8 -o StrictHostKeyChecking=accept-new "
f"-i {KEY} root@{ip} {shlex.quote(cmd)}", timeout)
def on_deb(cmd, timeout=40):
return sh(f"ssh -o ConnectTimeout=8 {DEB} {shlex.quote(cmd)}", timeout)
def stage():
"""put the demo ruleset + pdivert on pf0 (through the lab host)"""
with open("/tmp/demo-pf.conf", "w") as f:
f.write(CONF)
with open("/tmp/demo-divert.conf", "w") as f:
f.write(DIVERT_CONF)
sh(f"scp -q /tmp/demo-pf.conf /tmp/demo-divert.conf "
f"{os.path.join(REPO, 'tools/out/pdivert')} {DEB}:/tmp/", timeout=90)
on_deb(f"scp -q -o StrictHostKeyChecking=accept-new -i {KEY} "
f"/tmp/demo-pf.conf /tmp/demo-divert.conf /tmp/pdivert "
f"root@{PF0}:/tmp/ 2>&1", timeout=90)
SCENARIO = [
("local", "echo '=== PF on Linux — OpenBSD PF 8.0 engine running inside the Linux 7.3.4 kernel ==='"),
("local", "echo 'lab: 3 Alpine VMs under libvirt (pf0 = firewall, cli/srv = transit endpoints)'"),
("pf0", "uname -r"),
("pf0", "lsmod | grep '^pf ' || echo 'pf: not loaded'"),
("pf0", "insmod /opt/pf/pf.ko && dmesg | tail -3"),
("pf0", "/opt/pf/pfctl -s info | head -4"),
("pf0", "/opt/pf/pfctl -e && /opt/pf/pfctl -s info | head -1"),
("pf0", "cat /tmp/demo-pf.conf"),
("pf0", "/opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'rules loaded' && /opt/pf/pfctl -sr"),
("pf0", "/opt/pf/pfctl -sr -vv | head -8"),
("cli", f"ping -c2 -W2 {SRV} | tail -3"),
("pf0", "/opt/pf/pfctl -ss"),
("pf0", "/opt/pf/pfctl -t trusted -T show"),
("pf0", "/opt/pf/pfctl -s Tables"),
("cli", "ping -c2 -W2 10.0.9.99 | tail -3"),
("pf0", "/opt/pf/pfctl -sr -vv | head -6"),
("pf0", "/opt/pf/pfctl -f /tmp/demo-divert.conf && echo 'divert rule loaded'"),
("pf0", "(setsid /tmp/pdivert -p 10000 -f >/tmp/pdivert.log 2>&1 </dev/null &); sleep 1; pgrep pdivert"),
("cli", "ping -c2 -W2 10.0.1.1 | tail -3"),
("pf0", "head -3 /tmp/pdivert.log"),
("pf0", "pkill pdivert; /opt/pf/pfctl -f /dev/null; /opt/pf/pfctl -d; echo 'pf disabled'"),
]
def record(out_path, quick=False):
os.makedirs(os.path.dirname(out_path) or ".", exist_ok=True)
events = []
t = 0.0
def emit(text, delay):
nonlocal t
t += delay
events.append([round(t, 3), "o", text])
header = {
"version": 2, "width": 100, "height": 26,
"timestamp": int(time.time()),
"title": "PF on Linux — OpenBSD PF engine inside the Linux kernel (lab demo)",
"env": {"SHELL": "/bin/sh", "TERM": "xterm-256color"},
}
runners = {
"pf0": lambda c: on_pf0(c),
"cli": lambda c: on_vm(CLI, c),
"srv": lambda c: on_vm(SRV, c),
"local": lambda c: sh(c),
}
labels = {"pf0": "pftest-pf0", "cli": "pftest-cli", "srv": "pftest-srv",
"local": "lab-host"}
stage()
with open(out_path, "w") as f:
f.write(json.dumps(header) + "\n")
for kind, cmd in SCENARIO:
emit(f"\x1b[1;36m{labels[kind]}\x1b[0m:\x1b[1;37m {cmd}\x1b[0m\r\n",
0.35)
try:
out = runners[kind](cmd)
except subprocess.TimeoutExpired:
out = "[timeout]\r\n"
except Exception as e: # noqa: BLE001
out = f"[error: {e}]\r\n"
out = out.replace("\r\n", "\n").replace("\n", "\r\n")
emit(out or "(no output)\r\n", min(1.4, 0.3 + len(out) / 5000.0))
with open(out_path, "a") as f:
for ev in events:
f.write(json.dumps(ev) + "\n")
print(f"WROTE {out_path}: {len(events)} events, {t:.1f}s")
print("play: asciinema play " + out_path)
print("upload: asciinema upload " + out_path)
if __name__ == "__main__":
ap = argparse.ArgumentParser()
ap.add_argument("--out", default=os.path.join(REPO, "out",
"demo-pf-linux.cast"))
ap.add_argument("--quick", action="store_true")
a = ap.parse_args()
record(a.out, a.quick)
+169
View File
@@ -0,0 +1,169 @@
#!/usr/bin/env bash
# Demo session for PF-on-Linux: a scripted terminal tour of the lab.
# Recorded with: asciinema rec out/demo-pf-linux.cast -c "bash scripts/demo-session.sh"
#
# Everything printed is the REAL output of the lab (Alpine VMs under libvirt
# running the kernel built from source with our pf.ko). The VM management
# addresses are resolved from the hypervisor (they are DHCP), the lab
# topology (10.0.1.0/24, 10.0.2.0/24, ...) is fixed.
set -u
DEB=${DEB:-root@192.168.1.242}
CLI_IP=${CLI_IP:-10.0.1.10}
SRV_IP=${SRV_IP:-10.0.2.20}
KEY=${KEY:-$HOME/.ssh/pflab_ed}
bold() { printf '\033[1m%s\033[0m\n' "$*"; }
cyan() { printf '\033[1;36m%s\033[0m\n' "$*"; }
# management address of a lab VM (DHCP, so ask the hypervisor)
mgmt() {
ssh -o ConnectTimeout=8 "$DEB" "virsh domifaddr $1 | awk '/vnet/{print \$4}' | cut -d/ -f1" \
2>/dev/null | tr -d '\r' | head -1
}
PF0_MGMT=$(mgmt pftest-pf0)
CLI_MGMT=$(mgmt pftest-cli)
[ -n "$PF0_MGMT" ] || PF0_MGMT=192.168.122.8
[ -n "$CLI_MGMT" ] || CLI_MGMT=192.168.122.80
# run a command on a lab VM (through the hypervisor)
onvm() {
local ip=$1; shift
ssh -o ConnectTimeout=10 -o StrictHostKeyChecking=accept-new \
-o ProxyJump=root@192.168.1.242 -i "$KEY" root@"$ip" "$@" 2>&1
}
p0() {
cyan "pftest-pf0# $*"
onvm "$PF0_MGMT" "$@"
sleep 0.4
}
vmc() {
cyan "pftest-cli# $*"
onvm "$CLI_MGMT" "$@"
sleep 0.4
}
CONF=/tmp/demo-pf.conf
DIV=/tmp/demo-divert.conf
cat > "$CONF" <<'CONF'
# PF-on-Linux demo ruleset (pf.conf syntax, real OpenBSD pfctl)
set block-policy return
table <trusted> { 10.0.1.0/24 }
# transit traffic: stateful, table-driven
pass in quick on ingress proto icmp from <trusted> keep state
pass out quick on egress proto icmp keep state
# deny a specific destination
block drop in quick proto icmp to 10.0.9.99
# everything else
pass in quick
pass out quick
CONF
cat > "$DIV" <<CONF
pass in quick proto icmp from $CLI_IP to 10.0.1.1 divert-to "10.0.1.1" port 10000 keep state
pass out quick
CONF
# the pf0 interface towards the server (used by the NAT pool)
EGRESS_IF=$(onvm "$PF0_MGMT" "ip route get $SRV_IP | grep -o 'dev [a-z0-9]*' | cut -d' ' -f2" | tr -d '\r')
[ -n "$EGRESS_IF" ] || EGRESS_IF=eth2
scp -q -o ProxyJump=root@192.168.1.242 -i "$KEY" "$CONF" "$DIV" \
tools/out/pdivert tools/out/pflogd "root@$PF0_MGMT:/tmp/" 2>/dev/null
bold "==============================================================="
bold " PF on Linux - the OpenBSD PF 8.0 engine inside the Linux kernel"
bold "==============================================================="
echo
echo "Lab: 3 Alpine VMs under libvirt."
echo " pftest-pf0 = firewall (kernel 7.3.4 built from source + pf.ko)"
echo " pftest-cli = client 10.0.1.10 pftest-srv = server 10.0.2.20"
echo
bold "--- 1. our kernel, the OpenBSD engine as a module ---"
p0 "uname -r"
p0 "lsmod | grep '^pf ' || echo 'pf: not loaded yet'"
p0 "insmod /opt/pf/pf.ko && dmesg | tail -3"
echo
bold "--- 2. pfctl talks to the module over the OpenBSD ioctl ABI ---"
p0 "/opt/pf/pfctl -s info | head -4"
p0 "/opt/pf/pfctl -e && /opt/pf/pfctl -s info | head -1"
echo
bold "--- 3. a real pf.conf: tables, stateful rules, an explicit drop ---"
p0 "cat /tmp/demo-pf.conf"
p0 "/opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'rules loaded'"
p0 "/opt/pf/pfctl -sr"
echo
bold "--- 4. transit traffic is allowed and stateful ---"
vmc "ping -c2 -W2 $SRV_IP | tail -3"
p0 "/opt/pf/pfctl -ss | grep -E 'icmp' | head -4"
echo
bold "--- 5. tables are live objects ---"
p0 "/opt/pf/pfctl -t trusted -T show"
p0 "/opt/pf/pfctl -s Tables"
echo
bold "--- 6. the drop rule actually drops ---"
p0 "cat > /tmp/demo-block.conf <<EOF
block drop in quick proto icmp to $SRV_IP
pass in quick
pass out quick
EOF"
p0 "/opt/pf/pfctl -f /tmp/demo-block.conf && echo 'block rules loaded'"
vmc "ping -c2 -W2 $SRV_IP | tail -3"
p0 "/opt/pf/pfctl -sr -vv | head -6"
p0 "/opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'back to the stateful ruleset'"
echo
bold "--- 7. NAT: the source is translated on the way out, restored on the way back ---"
p0 "cat > /tmp/demo-nat.conf <<EOF
pass out quick on egress from 10.0.1.0/24 to any nat-to ($EGRESS_IF)
pass in quick on ingress proto icmp keep state
pass out quick on egress proto icmp keep state
EOF"
p0 "/opt/pf/pfctl -f /tmp/demo-nat.conf && echo 'nat rules loaded'"
vmc "ping -c2 -W2 $SRV_IP | tail -3"
p0 "/opt/pf/pfctl -ss | grep -E 'icmp' | head -4"
p0 "/opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'back to the stateful ruleset'"
echo
bold "--- 8. pflog: logged packets reach userspace (/dev/pflog) ---"
p0 "cat > /tmp/demo-log.conf <<EOF
pass in quick log proto icmp from $CLI_IP keep state
pass out quick
EOF"
p0 "/opt/pf/pfctl -f /tmp/demo-log.conf && echo 'log rule loaded'"
p0 "chmod +x /tmp/pflogd; rm -f /tmp/pflog.pcap; (setsid /tmp/pflogd -c 2 /tmp/pflog.pcap >/tmp/pflogd.log 2>&1 </dev/null &); sleep 1; echo 'pflogd collecting 2 records'"
vmc "ping -c2 -W2 $SRV_IP | tail -2"
sleep 2
p0 "cat /tmp/pflogd.log; ls -l /tmp/pflog.pcap; echo 'pcap header (magic d4c3b2a1, linktype 0x75=DLT_PFLOG):'; od -An -tx1 -N24 /tmp/pflog.pcap"
p0 "pkill pflogd 2>/dev/null; /opt/pf/pfctl -f /tmp/demo-pf.conf >/dev/null"
echo
bold "--- 9. divert-to: the packet goes to userspace and comes back ---"
p0 "cat /tmp/demo-divert.conf"
p0 "/opt/pf/pfctl -f /tmp/demo-divert.conf && echo 'divert rule loaded'"
p0 "chmod +x /tmp/pdivert; (setsid /tmp/pdivert -p 10000 -f >/tmp/pdivert.log 2>&1 </dev/null &); sleep 1; pgrep pdivert"
vmc "ping -c2 -W2 10.0.1.1 | tail -3"
p0 "head -3 /tmp/pdivert.log"
echo " (pdivert flipped the last payload byte and fixed the ICMP checksum)"
echo
bold "--- 10. shutdown ---"
p0 "pkill pdivert; /opt/pf/pfctl -f /dev/null; /opt/pf/pfctl -d; echo 'pf disabled'"
p0 "lsmod | grep '^pf '"
echo
bold "demo over - port, gates and docs:"
bold " https://git.labexposed.com/lgcosta/pf-linux-port"
echo
+27 -5
View File
@@ -17,20 +17,42 @@ reset_pf0() {
return 1 return 1
} }
deploy() { deploy() {
scp -q -o ProxyJump=root@192.168.1.242 -o StrictHostKeyChecking=accept-new \ # The scp through the libvirt jump host is occasionally refused; a silent
# failure used to leave the previous gate's module/pfctl in place, which
# showed up as a bogus gate failure. Retry and verify the copy.
local i
for i in 1 2 3; do
local extra=()
[ -x "$REPO/tools/out/pdivert" ] && extra+=("$REPO/tools/out/pdivert")
[ -x "$REPO/tools/out/pflogd" ] && extra+=("$REPO/tools/out/pflogd")
if scp -q -o ProxyJump=root@192.168.1.242 -o StrictHostKeyChecking=accept-new \
-i "$HOME/.ssh/pflab_ed" "$REPO/module/pf.ko" \ -i "$HOME/.ssh/pflab_ed" "$REPO/module/pf.ko" \
"$REPO/tools/out/pfctl" "$REPO/tests/confs/"*.conf pf0:/tmp/ 2>/dev/null || \ "$REPO/tools/out/pfctl" "${extra[@]}" "$REPO/tests/confs/"*.conf pf0:/tmp/ 2>/dev/null; then
ssh "$DEB" "mkdir -p /opt/pf" break
fi
sleep 2
done
# stage onto pf0 /opt/pf via mgmt alias already copied to /tmp # stage onto pf0 /opt/pf via mgmt alias already copied to /tmp
ssh "$DEB" "$SSH 'mkdir -p /opt/pf; mv /tmp/pf.ko /tmp/pfctl /opt/pf/ 2>/dev/null; true'" >/dev/null ssh "$DEB" "$SSH 'mkdir -p /opt/pf; mv /tmp/pf.ko /tmp/pfctl /tmp/pdivert /tmp/pflogd /opt/pf/ 2>/dev/null; chmod +x /opt/pf/pfctl /opt/pf/pdivert /opt/pf/pflogd 2>/dev/null; true'" >/dev/null
ssh "$DEB" "$SSH 'test -s /opt/pf/pf.ko && test -x /opt/pf/pfctl'" >/dev/null 2>&1 || {
echo "deploy: pf.ko/pfctl missing on pf0"; return 1; }
} }
PUSH=0 FAIL=0 PUSH=0 FAIL=0
# Never leave pf0 with pf enabled when the runner exits (a failed gate
# would otherwise keep filtering the lab traffic).
pf_disable_pf0() {
ssh -o ConnectTimeout=8 "$DEB" "$SSH '/opt/pf/pfctl -d >/dev/null 2>&1; true'" \
>/dev/null 2>&1 || true
}
trap pf_disable_pf0 EXIT INT TERM
ONLY="${1:-}"
for t in "$REPO"/tests/vm/[0-9]*.sh; do for t in "$REPO"/tests/vm/[0-9]*.sh; do
[ -n "$ONLY" ] && case "$t" in *"$ONLY"*) ;; *) continue ;; esac
[ -e "$t" ] || continue [ -e "$t" ] || continue
name="$(basename "$t")" name="$(basename "$t")"
echo "=== $name ===" echo "=== $name ==="
reset_pf0 || { echo "FAIL $name (vm reset)"; FAIL=$((FAIL+1)); continue; } reset_pf0 || { echo "FAIL $name (vm reset)"; FAIL=$((FAIL+1)); continue; }
deploy deploy || { echo "FAIL $name (deploy)"; FAIL=$((FAIL+1)); continue; }
if bash "$t" >"$LOGD/$name.log" 2>&1; then if bash "$t" >"$LOGD/$name.log" 2>&1; then
echo "PASS $name"; PUSH=$((PUSH+1)) echo "PASS $name"; PUSH=$((PUSH+1))
else else
+1 -1
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash #!/usr/bin/env bash
# M2 gate 1: stateful transit + state visibility # M2 gate 1: stateful transit + state visibility
set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh
pfensure pf0 'insmod /tmp/pf.ko 2>/dev/null || insmod /opt/pf/pf.ko; true'
pf0 '/opt/pf/pfctl -e; /opt/pf/pfctl -f /dev/null; echo READY' | grep -q READY || { bad load; finish; } pf0 '/opt/pf/pfctl -e; /opt/pf/pfctl -f /dev/null; echo READY' | grep -q READY || { bad load; finish; }
cat > /tmp/g1.conf <<'C' cat > /tmp/g1.conf <<'C'
pass in quick proto icmp keep state pass in quick proto icmp keep state
+1 -1
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash #!/usr/bin/env bash
# M2 gate 2: block drop + block return-rst # M2 gate 2: block drop + block return-rst
set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh
pfensure; pf0 '/opt/pf/pfctl -e' >/dev/null pf0 'insmod /tmp/pf.ko 2>/dev/null || insmod /opt/pf/pf.ko; true'; pf0 '/opt/pf/pfctl -e' >/dev/null
cat > /tmp/g2a.conf <<'C' cat > /tmp/g2a.conf <<'C'
block drop in quick proto icmp from any to any block drop in quick proto icmp from any to any
pass out quick pass out quick
+1 -1
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash #!/usr/bin/env bash
# M2 gate 3: pfr tables via pfctl -t # M2 gate 3: pfr tables via pfctl -t
set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh
pfensure; pf0 '/opt/pf/pfctl -e' >/dev/null pf0 'insmod /tmp/pf.ko 2>/dev/null || insmod /opt/pf/pf.ko; true'; pf0 '/opt/pf/pfctl -e' >/dev/null
cat > /tmp/g3.conf <<'C' cat > /tmp/g3.conf <<'C'
table <blk> { 10.0.1.10 } table <blk> { 10.0.1.10 }
block in quick proto icmp from <blk> to any block in quick proto icmp from <blk> to any
+43 -12
View File
@@ -1,19 +1,50 @@
#!/usr/bin/env bash #!/usr/bin/env bash
# M2 gate 4: anchors + quick precedence # M2 gate 4: anchors + evaluation order (OpenBSD semantics)
#
# OpenBSD evaluates the IN ruleset in ip_input() for every arriving packet and
# the OUT ruleset in ip_forward() for forwarded packets. A `block in ... icmp`
# rule therefore also sees the *reply* of a transit flow - a state created by
# an anchor rule does NOT rescue the reply at input time. This gate keeps the
# ruleset OpenBSD-correct and isolates the anchor semantics:
#
# anchor "restricted" -> child: pass in quick ... from <client> keep state
# block drop in quick proto icmp from any to <server> (would drop the request)
# pass in quick / pass out quick
#
# The request must be passed by the ANCHOR child rule (the later block rule
# would drop it), and a state must exist. After flushing the anchor the very
# same request must be dropped - proving the anchor is what allowed it.
set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh
pfensure; pf0 '/opt/pf/pfctl -e; /opt/pf/pfctl -f /dev/null' >/dev/null
cat > /tmp/g4main.conf <<'C' pf0 'insmod /opt/pf/pf.ko 2>/dev/null || insmod /tmp/pf.ko; true'
pf0 '/opt/pf/pfctl -e; /opt/pf/pfctl -f /dev/null' >/dev/null
cat > /tmp/g4main.conf <<C
anchor "restricted" anchor "restricted"
block drop in quick proto icmp from any to any block drop in quick proto icmp from any to $SRV_IP
pass in quick pass in quick
pass out quick pass out quick
C C
pfload /tmp/g4main.conf || { bad mainload; finish; } cat > /tmp/g4anc.conf <<C
cat > /tmp/g4anc.conf <<'C' pass in quick proto icmp from $CLI_IP to any keep state
pass in quick proto icmp from 10.0.1.10 to any
C C
r=$(pfput /tmp/g4anc.conf); pf0 "/opt/pf/pfctl -a restricted -f $r" || { bad anchorload; finish; }
cli "ping -c1 -W2 $SRV_IP >/dev/null 2>&1" && ok "anchor pass evaluated before block" || bad "anchor pass not honored" pfload /tmp/g4main.conf || { bad "main ruleset load"; finish; }
# anchor rules are evaluated BEFORE the main-ruleset block line (top placement) ANC=$(pfput /tmp/g4anc.conf) || { bad "anchor conf upload"; finish; }
pf0 '/opt/pf/pfctl -s Anchors' | grep -q restricted && ok "anchors listed" || bad "anchor list" pf0 "/opt/pf/pfctl -a restricted -f $ANC" || { bad "anchor ruleset load"; finish; }
pf0 '/opt/pf/pfctl -d; /opt/pf/pfctl -f /dev/null' >/dev/null; finish
pf0 '/opt/pf/pfctl -sr' | grep -q 'anchor "restricted"' && ok "anchor rule in main ruleset" || bad "anchor rule missing"
pf0 '/opt/pf/pfctl -a restricted -sr' | grep -q 'proto icmp from' && ok "anchor rules listed" || bad "anchor rules missing"
# the request must pass through the anchor (the block rule would drop it)
cli "ping -c2 -W2 $SRV_IP >/dev/null 2>&1" && ok "anchor pass honoured (request allowed)" \
|| bad "anchor pass not honored"
pf0 '/opt/pf/pfctl -ss' | grep -q "$SRV_IP" && ok "state created by anchor rule" || bad "no state from anchor"
# without the anchor rule the request hits the block rule -> dropped
pf0 "/opt/pf/pfctl -a restricted -F all" >/dev/null 2>&1
cli "ping -c1 -W2 $SRV_IP >/dev/null 2>&1" && bad "request passed without anchor rule" \
|| ok "request dropped without anchor rule (block applies)"
pf0 '/opt/pf/pfctl -d; /opt/pf/pfctl -f /dev/null' >/dev/null
finish
+46
View File
@@ -0,0 +1,46 @@
#!/usr/bin/env bash
# M3 gate: nat-to — source NAT of transit traffic to the egress address.
#
# OpenBSD 8.0 unified the old "nat on ..." rule into the rule syntax:
# pass out on egress from <net> to any nat-to (egress)
#
# Expected: the reply path is unaffected, srv sees the packet with
# src = pf0's egress address (not the client's), and pfctl shows the rule.
set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh
FAILED=0
# pf calls the interface "egress"; the OS names it ethX - resolve both
EGRESS_DEV=$(pf0 "ip route get $SRV_IP | grep -o 'dev [a-z0-9]*' | cut -d' ' -f2")
EGRESS_IP=$(pf0 "ip -4 addr show $EGRESS_DEV | grep -o 'inet [0-9.]*' | head -1 | cut -d' ' -f2")
[ -n "$EGRESS_IP" ] || EGRESS_IP=192.168.122.8
pf0 'insmod /opt/pf/pf.ko 2>/dev/null || insmod /tmp/pf.ko; true'
pf0 '/opt/pf/pfctl -e; /opt/pf/pfctl -f /dev/null' >/dev/null
# OpenBSD expands "(egress)" (an interface *group*) into the addresses of all
# its members - on a multi-NIC host that is ambiguous, so the gate uses the
# concrete transit interface (the OpenBSD-recommended form for NAT pools).
cat > /tmp/g05.conf <<C
pass out quick on egress from 10.0.1.0/24 to any nat-to ($EGRESS_DEV)
pass in quick on ingress proto icmp keep state
pass out quick on egress proto icmp keep state
C
pfload /tmp/g05.conf || { bad "nat rule load"; finish; }
pf0 '/opt/pf/pfctl -sr' | grep -q 'nat-to' && ok "nat-to rule listed" || bad "nat-to not listed"
pf0 "tcpdump -ni $EGRESS_DEV -c 4 -e icmp > /tmp/nat.td 2>&1 &"
sleep 1
cli "ping -c2 -W2 $SRV_IP >/dev/null 2>&1" && ok "transit ping through NAT" || bad "transit ping"
sleep 2
TD=$(pf0 'cat /tmp/nat.td')
if echo "$TD" | grep -q "$CLI_IP"; then
bad "client address $CLI_IP still visible on egress"
else
ok "source rewritten on egress (no $CLI_IP)"
fi
echo "$TD" | grep -q "$EGRESS_IP" && ok "egress source is $EGRESS_IP" || bad "egress source not seen"
pf0 '/opt/pf/pfctl -ss' | grep -q "$SRV_IP" && ok "state present" || bad "no state"
pf0 '/opt/pf/pfctl -d' >/dev/null
finish
+69
View File
@@ -0,0 +1,69 @@
#!/usr/bin/env bash
# M3 gate: rdr-to — destination/port redirect.
#
# Lab: the client connects to the firewall's own address 10.0.1.1:8080; pf
# redirects it to the server (10.0.2.20:80, busybox httpd). This exercises
# the inbound translation *and* the re-route of a packet whose destination pf
# rewrote (the packet is no longer local to the firewall).
set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh
pf0 'insmod /opt/pf/pf.ko 2>/dev/null || insmod /tmp/pf.ko; true'
pf0 '/opt/pf/pfctl -e; /opt/pf/pfctl -f /dev/null' >/dev/null
# the runner only resets pf0 between gates - clear any responder a previous
# run (or a manual session) left on the server, or it answers first and this
# gate sees the wrong payload.
srv 'pkill -f '[l]oop.sh' 2>/dev/null; pkill -f '[b]ig.sh' 2>/dev/null; pkill nc 2>/dev/null; true' >/dev/null
sleep 1
# a tiny responder on srv:80 (base64-encoded so it survives the two ssh hops
# without nested quoting problems; detached so ssh returns)
LOOP=$(printf 'while :; do nc -l -p 80 < /tmp/resp.txt >/dev/null 2>&1; done\n' | base64 | tr -d '\n')
# NOTE: never pkill -f a pattern that also appears in this very command line -
# it kills the invoking shell. Use a pidfile and check the listening socket.
srv "echo PF-RDR-OK > /tmp/resp.txt; echo $LOOP | base64 -d > /tmp/loop.sh; [ -f /tmp/loop.pid ] && kill \$(cat /tmp/loop.pid) 2>/dev/null; pkill nc 2>/dev/null; setsid sh /tmp/loop.sh >/dev/null 2>&1 </dev/null & echo \$! > /tmp/loop.pid; sleep 1; netstat -lnt 2>/dev/null | grep -q ':80 ' && echo RESPONDER_UP" | grep -q RESPONDER_UP && ok "responder up on srv:80" || bad "responder start"
cat > /tmp/g06.conf <<C
pass in quick proto tcp from 10.0.1.0/24 to 10.0.1.1 port 8080 rdr-to $SRV_IP port 80 keep state
pass out quick proto tcp keep state
C
pfload /tmp/g06.conf || { bad "rdr rule load"; finish; }
pf0 '/opt/pf/pfctl -sr' | grep -q 'rdr-to' && ok "rdr rule listed" || bad "rdr not listed"
# the client talks to the firewall's address; pf redirects to srv:80
RESP=$(cli 'printf "GET / HTTP/1.0\r\n\r\n" | nc -w3 10.0.1.1 8080' 2>/dev/null)
if echo "$RESP" | grep -q 'PF-RDR-OK'; then
ok "redirect delivered the response"
else
bad "no redirected response"
printf '%s\n' "$RESP" | head -4 | sed 's/^/ /'
fi
# the state must show the translated tuple (server:80 with the original in parens)
pf0 '/opt/pf/pfctl -ss' | grep -E "$SRV_IP:80 .*$CLI_IP" >/dev/null && ok "state shows the translation" || bad "no translated state"
# the reply path must survive the un-redirect
pf0 '/opt/pf/pfctl -s info' | grep -qiE 'match' && ok "counters readable" || bad "counters"
srv '[ -f /tmp/loop.pid ] && kill $(cat /tmp/loop.pid) 2>/dev/null; pkill nc 2>/dev/null; true' >/dev/null
# bulk (GSO/TSO) through the redirect: 2 MB must arrive byte-identical.
# This is the regression that "materialize the checksum in software" introduced:
# computing the transport checksum once for a GSO skb corrupts every segment
# after the first, and the peer silently stalls (sshd mute, transfers hang).
B64=$(printf 'head -c 2000000 /dev/zero | tr "\0" A > /tmp/big.txt\n' | base64 | tr -d '\n')
srv "echo $B64 | base64 -d > /tmp/mkbig.sh; sh /tmp/mkbig.sh; pkill nc 2>/dev/null; sleep 1; nohup setsid nc -l -p 9091 < /tmp/big.txt >/dev/null 2>&1 & sleep 1; netstat -lnt | grep -q 9091 && echo BULK_UP" | grep -q BULK_UP || bad "bulk listener"
pf0 "printf 'pass in quick proto tcp from 10.0.1.0/24 to 10.0.1.1 port 9091 rdr-to $SRV_IP port 9091 keep state\npass out quick proto tcp keep state\n' > /tmp/g06b.conf; /opt/pf/pfctl -f /tmp/g06b.conf && echo BULK_RULE" >/dev/null
GOT=$(cli 'nc -w10 10.0.1.1 9091 | wc -c' | tr -d '[:space:]')
EXP=$(srv 'wc -c < /tmp/big.txt' | tr -d '[:space:]')
if [ "$GOT" = "$EXP" ] && [ "${GOT:-0}" -ge 2000000 ]; then
ok "2 MB through the redirect intact ($GOT bytes)"
else
bad "bulk through redirect: got $GOT want $EXP"
fi
# the firewall must still answer ssh (the GSO path must not wedge the box)
pf0 'echo SSH_ALIVE' | grep -q SSH_ALIVE && ok "pf0 sshd still responsive" || bad "pf0 unreachable after bulk"
srv 'pkill nc 2>/dev/null; true' >/dev/null
pf0 '/opt/pf/pfctl -d' >/dev/null
finish
+35
View File
@@ -0,0 +1,35 @@
#!/usr/bin/env bash
# M4 gate: divert — AF_DIVERT family end-to-end with packet-level proof.
#
# Scenario (lab):
# rule: pass in quick proto icmp from cli to pf0-lan divert-to "<pf0-lan>" port 10000 keep state
# (a) no listener on the divert port -> ping cli->pf0 FAILS (BSD parity: divs_noport)
# (b) pdivert -f running -> ping SUCCEEDS and pdivert rewrites the
# payload (last byte flipped), proving the packet went to userspace and back.
set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh
PORT=10000
PFLAN=10.0.1.1
pf0 'insmod /opt/pf/pf.ko 2>/dev/null || insmod /tmp/pf.ko; true'
pf0 '/opt/pf/pfctl -e; /opt/pf/pfctl -f /dev/null' >/dev/null
pf0 'pkill pdivert 2>/dev/null; true'
cat > /tmp/g11.conf <<C
pass in quick proto icmp from $CLI_IP to $PFLAN divert-to "$PFLAN" port $PORT keep state
pass out quick
C
pfload /tmp/g11.conf || { bad "divert rule load"; finish; }
pf0 '/opt/pf/pfctl -sr' | grep -q 'divert-to' && ok "divert rule loaded" || bad "divert rule missing"
# (a) no listener -> BSD drops (divs_noport)
cli "ping -c1 -W2 $PFLAN >/dev/null 2>&1" && bad "passed without divert listener" || ok "drop without divert listener"
# (b) listener present -> passes through userspace
PDIV=$(pfput ../../tools/out/pdivert) || bad "pdivert deploy"
pf0 "chmod +x $PDIV; (setsid $PDIV -p $PORT -f > /tmp/pdiv.log 2>&1 < /dev/null &); sleep 1"
pf0 "pgrep pdivert >/dev/null && echo RUNNING" | grep -q RUNNING && ok "pdivert listening" || bad "pdivert start"
cli "ping -c2 -W2 $PFLAN >/dev/null 2>&1" && ok "ping passes through divert" || bad "ping with listener"
pf0 'cat /tmp/pdiv.log' | grep -qi 'divert' && ok "pdivert received packet" || bad "pdivert saw nothing"
pf0 'pkill pdivert; /opt/pf/pfctl -d' >/dev/null 2>&1
finish
+48
View File
@@ -0,0 +1,48 @@
#!/usr/bin/env bash
# M4 gate: pflog — logged packets must reach userspace.
#
# pflogd reads /dev/pflog (the port's chardev backend) and writes a pcap with
# linktype DLT_PFLOG (117). A `log` rule + ICMP traffic must produce records
# that contain the real packet bytes (checked by searching the client address
# in the capture) and a valid pcap header.
set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh
pf0 'insmod /opt/pf/pf.ko 2>/dev/null || insmod /tmp/pf.ko; true'
pf0 '/opt/pf/pfctl -e; /opt/pf/pfctl -f /dev/null' >/dev/null
pf0 'pkill -f "[p]flogd" 2>/dev/null; rm -f /tmp/pflog.pcap; true'
LOGD=$(pfput ../../tools/out/pflogd) || { bad "pflogd deploy"; finish; }
pf0 "test -c /dev/pflog && echo DEV_OK" | grep -q DEV_OK || { bad "/dev/pflog missing"; finish; }
pf0 "chmod +x $LOGD; (setsid $LOGD -c 4 -f /dev/pflog /tmp/pflog.pcap >/tmp/pflogd.log 2>&1 </dev/null &); sleep 1; pgrep pflogd >/dev/null && echo DAEMON_UP" \
| grep -q DAEMON_UP || { bad "pflogd start"; finish; }
cat > /tmp/g12.conf <<C
pass in quick log proto icmp from $CLI_IP keep state
pass out quick proto icmp keep state
C
pfload /tmp/g12.conf || { bad "log rule load"; finish; }
cli "ping -c3 -W2 $SRV_IP >/dev/null 2>&1"
sleep 2
# pcap header: magic d4c3b2a1 (LE) and network = 117 at offset 20
HDR=$(pf0 "od -An -tx1 -N24 /tmp/pflog.pcap 2>/dev/null | tr -d '[[:space:]]'")
if [ "${HDR:0:8}" = "d4c3b2a1" ]; then ok "pcap magic ok"; else bad "pcap header: $HDR"; fi
if [ "${HDR:40:4}" = "7500" ] || [ "${HDR:40:8}" = "75000000" ]; then
ok "linktype DLT_PFLOG (117)"
else
bad "linktype: ${HDR:40:8}"
fi
SZ=$(pf0 'wc -c < /tmp/pflog.pcap' | tr -d '[:space:]')
if [ "${SZ:-0}" -gt 24 ]; then ok "records captured ($SZ bytes)"; else bad "no records ($SZ)"; fi
# the client address must appear inside a captured packet
if pf0 "od -An -tx1 /tmp/pflog.pcap | tr -d '[[:space:]]' | grep -q 0a00010a"; then
ok "captured payload contains $CLI_IP"
else
bad "client address not in capture"
fi
pf0 'pkill pflogd 2>/dev/null; /opt/pf/pfctl -d' >/dev/null
finish
+51
View File
@@ -0,0 +1,51 @@
#!/usr/bin/env bash
# M6 gate: soak + unload/leak discipline.
#
# 1) load pf with a stateful ruleset, drive mixed traffic for ~20s
# 2) assert no BUG/WARNING/Oops in dmesg
# 3) disable + rmmod: the module must unload cleanly (no refcount leak)
# 4) insmod/rmmod cycles: slab objects for the pf caches must return to the
# pre-load baseline (no leak) and a reload must work
set -uo pipefail; cd "$(dirname "$0")"; . ./lib.sh
HELPER=$(pfput ./soak-helper.sh) || { bad "helper upload"; finish; }
pf0 "chmod +x $HELPER" >/dev/null
pf0 'insmod /opt/pf/pf.ko 2>/dev/null || insmod /tmp/pf.ko; true'
pf0 '/opt/pf/pfctl -e; /opt/pf/pfctl -f /dev/null' >/dev/null
BEFORE=$(pf0 "$HELPER slab")
cat > /tmp/g14.conf <<C
table <peers> { $CLI_IP }
pass in quick on ingress proto icmp from <peers> keep state
pass out quick on egress proto icmp keep state
pass out quick proto tcp from any to any port 22 keep state
C
pfload /tmp/g14.conf || { bad "soak ruleset"; finish; }
# mixed traffic: ICMP + TCP handshakes for ~20s
cli "ping -q -c 40 -i 0.5 $SRV_IP >/dev/null 2>&1" 2>/dev/null
cli "for i in 1 2 3 4 5; do nc -w1 -z $SRV_IP 22; done" 2>/dev/null
ST=$(pf0 "$HELPER states")
[ "${ST:-0}" -ge 1 ] && ok "states under load ($ST)" || bad "no states under load"
ANOM=$(pf0 "$HELPER dmesg")
if [ -z "$ANOM" ]; then
ok "no kernel BUG/WARN/Oops"
else
bad "dmesg anomalies:"
printf '%s\n' "$ANOM" | sed 's/^/ /'
fi
pf0 '/opt/pf/pfctl -d; /opt/pf/pfctl -f /dev/null' >/dev/null
pf0 'rmmod pf && echo UNLOAD_OK' | grep -q UNLOAD_OK && ok "clean unload (refcounts released)" || bad "rmmod failed"
sleep 1
pf0 'insmod /opt/pf/pf.ko 2>/dev/null || insmod /tmp/pf.ko; true; (/opt/pf/pfctl -s info >/dev/null && echo RELOAD_OK)' \
| grep -q RELOAD_OK && ok "reload after unload" || bad "reload failed"
pf0 'rmmod pf && echo UNLOAD_OK2' | grep -q UNLOAD_OK2 && ok "second unload" || bad "second rmmod"
sleep 1
AFTER=$(pf0 "$HELPER slab")
LEAK=$(join <(echo "$BEFORE") <(echo "$AFTER") 2>/dev/null | awk '$3-$2 > 0 {print $1, $3-$2}')
if [ -n "$LEAK" ]; then bad "slab growth after cycles: $LEAK"; else ok "no slab growth after unload cycles"; fi
finish
+15 -5
View File
@@ -8,14 +8,24 @@ pf0() { ssh -o ConnectTimeout=10 "$DEB" "$SSHBASE$PF0_IP \"$*\""; }
cli() { ssh -o ConnectTimeout=10 "$DEB" "$SSHBASE$CLI_IP \"$*\""; } cli() { ssh -o ConnectTimeout=10 "$DEB" "$SSHBASE$CLI_IP \"$*\""; }
srv() { ssh -o ConnectTimeout=10 "$DEB" "$SSHBASE$SRV_IP \"$*\""; } srv() { ssh -o ConnectTimeout=10 "$DEB" "$SSHBASE$SRV_IP \"$*\""; }
gw2() { ssh -o ConnectTimeout=10 "$DEB" "$SSHBASE$GW2_IP \"$*\""; } gw2() { ssh -o ConnectTimeout=10 "$DEB" "$SSHBASE$GW2_IP \"$*\""; }
# Upload a config to pf0. The scp through the libvirt jump host is
# occasionally refused ("stdio forwarding failed"); a silent failure used to
# leave a *stale* config on pf0 (or none at all), which showed up as a
# bogus gate failure. Retry and fail loudly instead.
pfput() { pfput() {
local f="$1" local f="$1" i
scp -q -o ProxyJump=root@192.168.1.242 -o StrictHostKeyChecking=accept-new \ for i in 1 2 3; do
-i "$HOME/.ssh/pflab_ed" "$f" pf0:/tmp/ 2>/dev/null || \ if scp -q -o ProxyJump=root@192.168.1.242 -o StrictHostKeyChecking=accept-new \
ssh "$DEB" "true" # alias must exist; fallback no-op -i "$HOME/.ssh/pflab_ed" "$f" pf0:/tmp/ 2>/dev/null; then
echo "/tmp/$(basename "$f")" echo "/tmp/$(basename "$f")"
return 0
fi
sleep 2
done
echo "pfput: upload of $f to pf0 failed" >&2
return 1
} }
pfload() { local r; r=$(pfput "$1"); pf0 "/opt/pf/pfctl -f $r" && return 0; return 1; } pfload() { local r; r=$(pfput "$1") || return 1; pf0 "/opt/pf/pfctl -f $r" && return 0; return 1; }
ok() { echo "OK $*"; } ok() { echo "OK $*"; }
bad() { echo "NOT OK: $*" >&2; FAILED=1; } bad() { echo "NOT OK: $*" >&2; FAILED=1; }
finish(){ [ "${FAILED:-0}" = 1 ] && exit 1; exit 0; } finish(){ [ "${FAILED:-0}" = 1 ] && exit 1; exit 0; }
+18
View File
@@ -0,0 +1,18 @@
#!/usr/bin/env bash
# Helper executed ON pf0 by 14-soak.sh (uploaded with pfput to avoid quoting
# hell through two ssh hops).
# $1 = "slab" | "dmesg" | "states"
case "${1:-}" in
slab)
grep -E '^(pf|pfk)' /proc/slabinfo | tr -s ' ' | cut -d' ' -f1,3 | sort
;;
dmesg)
# the CPU's Speculative Return Stack Overflow advisory is a kernel
# build/CPU feature notice, not a fault of this module
dmesg | grep -E 'BUG:|WARNING:|Oops|general protection|kernel BUG' \
| grep -v 'Speculative Return Stack Overflow' || true
;;
states)
/opt/pf/pfctl -s states 2>/dev/null | grep -c 'icmp' || true
;;
esac
+22 -1
View File
@@ -57,7 +57,7 @@ GOODTESTS := tests/01_basic.conf tests/02_translations.conf \
tests/03_queues_scrub.conf tests/03_queues_scrub.conf
.PHONY: all pfctl abitest test abi clean .PHONY: all pfctl abitest test abi clean
all: pfctl abitest all: pfctl abitest pdivert pflogd
pfctl: $(OUT)/pfctl pfctl: $(OUT)/pfctl
@@ -178,3 +178,24 @@ test: $(OUT)/pfctl
clean: clean:
rm -rf $(OUT) rm -rf $(OUT)
rm -f $(GENHDRS) rm -f $(GENHDRS)
# ---------------------------------------------------------------------------
# pdivert — divert(4) relay for the in-module AF_DIVERT family (self-contained)
PD := $(OUT)/pdivert
pdivert: $(PD)
$(PD): pdivert/pdivert.c
@mkdir -p $(OUT)
$(CC) $(CFLAGS) $(LDFLAGS) -o $@ pdivert/pdivert.c
clean:
# ---------------------------------------------------------------------------
# pflogd - reads /dev/pflog and writes DLT_PFLOG pcap (self-contained)
LOGD := $(OUT)/pflogd
pflogd: $(LOGD)
$(LOGD): pflogd/pflogd.c
@mkdir -p $(OUT)
$(CC) $(CFLAGS) $(LDFLAGS) -o $@ pflogd/pflogd.c
+17 -1
View File
@@ -97,8 +97,24 @@ main(int argc, char **argv)
fprintf(stderr, "pdivert: got %zd bytes %s -> %s\n", fprintf(stderr, "pdivert: got %zd bytes %s -> %s\n",
n, src, dst); n, src, dst);
} }
if (flip && n > 0) if (flip && n > 0) {
buf[n - 1] ^= 0xff; buf[n - 1] ^= 0xff;
/* fix ICMP checksum after payload mutation */
if (n >= 28) {
unsigned short *icmp = (unsigned short *)(buf + 20);
unsigned int sum = 0;
int len = n - 20;
icmp[1] = 0; /* checksum field: exclude */
for (int i = 0; i < len / 2; i++)
sum += ntohs(icmp[i]);
if (len & 1)
sum += (unsigned char)buf[20 + len - 1] << 8;
sum = (sum >> 16) + (sum & 0xffff);
sum += (sum >> 16);
icmp[1] = htons((unsigned short)(~sum));
}
}
if (send(fd, buf, (size_t)n, 0) == -1) if (send(fd, buf, (size_t)n, 0) == -1)
perror("send"); perror("send");
} }
+82
View File
@@ -1562,6 +1562,84 @@ ifa_exists(const char *ifa_name)
return (NULL); return (NULL);
} }
/*
* PFLINUX: interface group emulation.
*
* OpenBSD creates the "ingress" and "egress" interface groups (ifgroups)
* and pfctl expands "(egress)" in a pool into the addresses of the group
* members via the SIOCGIFGMEMB socket ioctl. Linux has neither ifgroups
* nor that ioctl, so resolve the two groups locally:
*
* egress -> the interface of the default route (the same interface the
* kernel module marks as the pf "egress" interface)
* ingress -> every non-loopback interface
*/
static struct node_host *
ifa_group_members(const char *group, int flags)
{
struct node_host *n, *h = NULL, *c;
struct sockaddr_in sin;
socklen_t slen = sizeof(sin);
int s;
if (iftab == NULL)
ifa_load();
if (!strcmp(group, "egress")) {
/* source address of the default route */
memset(&sin, 0, sizeof(sin));
sin.sin_family = AF_INET;
sin.sin_port = htons(9);
sin.sin_addr.s_addr = htonl(0x01010101); /* discard route */
if ((s = socket(AF_INET, SOCK_DGRAM, 0)) != -1) {
if (connect(s, (struct sockaddr *)&sin,
sizeof(sin)) == 0 &&
getsockname(s, (struct sockaddr *)&sin, &slen) == 0) {
close(s);
for (n = iftab; n; n = n->next) {
if (n->af != AF_INET)
continue;
if (n->addr.v.a.addr.v4.s_addr !=
sin.sin_addr.s_addr)
continue;
if ((c = calloc(1, sizeof(*c))) == NULL)
err(1, "calloc");
*c = *n;
c->next = NULL;
c->tail = c;
return (c);
}
return (NULL);
}
close(s);
}
return (NULL);
}
/* "ingress" and any other group: every non-loopback interface */
for (n = iftab; n; n = n->next) {
if (n->af == AF_LINK)
continue;
if (n->ifa_flags & IFF_LOOPBACK)
continue;
if ((flags & PFI_AFLAG_BROADCAST) && n->af != AF_INET)
continue;
if ((c = calloc(1, sizeof(*c))) == NULL)
err(1, "calloc");
*c = *n;
c->next = NULL;
c->tail = c;
if (h == NULL)
h = c;
else {
h->tail->next = c;
h->tail = c->tail;
}
}
return (h);
}
struct node_host * struct node_host *
ifa_grouplookup(const char *ifa_name, int flags) ifa_grouplookup(const char *ifa_name, int flags)
{ {
@@ -1576,6 +1654,10 @@ ifa_grouplookup(const char *ifa_name, int flags)
strlcpy(ifgr.ifgr_name, ifa_name, sizeof(ifgr.ifgr_name)); strlcpy(ifgr.ifgr_name, ifa_name, sizeof(ifgr.ifgr_name));
if (ioctl(s, SIOCGIFGMEMB, (caddr_t)&ifgr) == -1) { if (ioctl(s, SIOCGIFGMEMB, (caddr_t)&ifgr) == -1) {
close(s); close(s);
/* PFLINUX: interface group emulation (see above) */
if (!strcmp(ifa_name, "ingress") ||
!strcmp(ifa_name, "egress"))
return (ifa_group_members(ifa_name, flags));
return (NULL); return (NULL);
} }
+184
View File
@@ -0,0 +1,184 @@
/*
* pflogd for PF-on-Linux (ISC 2026)
*
* Reads records from /dev/pflog (see module/pfsrc/pfk_pflog.c) and writes a
* pcap file with linktype DLT_PFLOG (117) - the same format OpenBSD's pflogd
* produces, so tcpdump -r / wireshark decode it.
*
* pflogd [-i iface] [-f /dev/pflog] [-p pidfile] [-c count] <file>
*
* A "-" as <file> writes to stdout. Omitting <file> prints a human-readable
* one-line summary per record (useful in the lab gates).
*/
#include <errno.h>
#include <fcntl.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <signal.h>
#include <unistd.h>
#include <sys/select.h>
#include <sys/stat.h>
#include <sys/ioctl.h>
#include <netinet/in.h>
#define PFLOG_IFNAMSIZ 16
#define PFLOG_RULESET_NAME 16
#define DLT_PFLOG 117
struct pflog_hdr {
int64_t ts_sec;
int64_t ts_usec;
uint8_t af;
uint8_t reason;
uint8_t ifname[PFLOG_IFNAMSIZ];
uint8_t ruleset[PFLOG_RULESET_NAME];
uint8_t nr;
uint8_t anc;
uint8_t flags;
uint8_t pad[9];
uint16_t pktlen; /* network order, as in BSD */
} __attribute__((packed));
struct pcap_file_header {
uint32_t magic;
uint16_t major, minor;
int32_t thiszone;
uint32_t sigfigs, snaplen, network;
};
struct pcap_pkthdr {
uint32_t ts_sec, ts_usec, caplen, len;
};
static volatile int running = 1;
static void onterm(int s) { (void)s; running = 0; }
static const char *reason_name(uint8_t r)
{
static const char *n[] = { "pass", "drop", "scrub", "noscrub",
"nat", "nonat", "rdr", "nordr" };
return r < 8 ? n[r] : "?";
}
int
main(int argc, char **argv)
{
const char *dev = "/dev/pflog", *file = NULL, *pidfile = NULL;
long want = -1;
int fd, out = 1, ch, wrote_header = 0, nrec = 0;
unsigned char buf[sizeof(struct pflog_hdr) + 2048];
while ((ch = getopt(argc, argv, "f:c:p:")) != -1)
switch (ch) {
case 'f': dev = optarg; break;
case 'c': want = atol(optarg); break;
case 'p': pidfile = optarg; break;
default: goto usage;
}
if (optind < argc)
file = argv[optind];
signal(SIGINT, onterm);
signal(SIGTERM, onterm);
fd = open(dev, O_RDONLY);
if (fd < 0) {
fprintf(stderr, "pflogd: open %s: %s\n", dev, strerror(errno));
return 1;
}
if (file && strcmp(file, "-") != 0) {
out = open(file, O_WRONLY | O_CREAT | O_TRUNC, 0600);
if (out < 0) {
fprintf(stderr, "pflogd: open %s: %s\n", file,
strerror(errno));
return 1;
}
}
if (pidfile) {
FILE *p = fopen(pidfile, "w");
if (p) { fprintf(p, "%d\n", (int)getpid()); fclose(p); }
}
while (running) {
ssize_t n, off = 0;
struct pflog_hdr *h;
/* read one full record: the chardev returns header+payload
* consecutively; a short read just continues where we left */
while (off < (ssize_t)sizeof(*h)) {
n = read(fd, buf + off, sizeof(buf) - off);
if (n <= 0) {
if (n < 0 && errno == EINTR)
goto cont;
if (n < 0 && (errno == EAGAIN || errno == EWOULDBLOCK)) {
fd_set r;
struct timeval tv = { 0, 500000 };
FD_ZERO(&r); FD_SET(fd, &r);
if (select(fd + 1, &r, NULL, NULL, &tv) <= 0)
goto cont;
continue;
}
goto cont;
}
off += n;
}
h = (struct pflog_hdr *)buf;
{
uint16_t plen = ntohs(h->pktlen);
while (off < (ssize_t)(sizeof(*h) + plen)) {
n = read(fd, buf + off, sizeof(buf) - off);
if (n <= 0)
break;
off += n;
}
if (off < (ssize_t)(sizeof(*h) + plen))
goto cont;
if (file) {
struct pcap_file_header g = {
.magic = 0xa1b2c3d4, .major = 2,
.minor = 4, .thiszone = 0,
.sigfigs = 0, .snaplen = 65535,
.network = DLT_PFLOG,
};
struct pcap_pkthdr ph = {
.ts_sec = (uint32_t)h->ts_sec,
.ts_usec = (uint32_t)h->ts_usec,
.caplen = sizeof(*h) + plen,
.len = sizeof(*h) + plen,
};
if (!wrote_header) {
if (write(out, &g, sizeof(g)) != sizeof(g))
break;
wrote_header = 1;
}
if (write(out, &ph, sizeof(ph)) != sizeof(ph) ||
write(out, buf, ph.caplen) != (ssize_t)ph.caplen)
break;
} else {
printf("%lld.%06lld %s if=%s ruleset=%s nr=%u "
"len=%u\n", (long long)h->ts_sec,
(long long)h->ts_usec, reason_name(h->reason),
(char *)h->ifname, (char *)h->ruleset,
h->nr, plen);
fflush(stdout);
}
nrec++;
if (want > 0 && nrec >= want)
break;
}
cont:
if (want > 0 && nrec >= want)
break;
}
if (file && strcmp(file, "-") != 0)
close(out);
close(fd);
fprintf(stderr, "pflogd: %d records\n", nrec);
return 0;
usage:
fprintf(stderr, "usage: pflogd [-f dev] [-c count] [-p pidfile] [file]\n");
return 2;
}