mirror of
https://github.com/lgcosta/pf-linux-port.git
synced 2026-11-16 04:34:44 -03:00
Compare commits
62
Commits
f121f496b4
..
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
0a8ba69340 | ||
|
|
928322edf7 | ||
|
|
45ba489672 | ||
|
|
131672d6ce | ||
|
|
dff2185b20 | ||
|
|
cc67531602 | ||
|
|
fe324259c0 | ||
|
|
90c51f43fc | ||
|
|
4bade69cf9 | ||
|
|
ccad35b247 | ||
|
|
14ff7d1c39 | ||
|
|
f34c4f92a9 | ||
|
|
ca75fc49cc | ||
|
|
12e9c1a2f3 | ||
|
|
c2d1fc4c53 | ||
|
|
3235af7f0b | ||
|
|
422a325a56 | ||
|
|
80396e0b36 | ||
|
|
b3e7358868 | ||
|
|
251e5c09e0 | ||
|
|
e26c6d4a36 | ||
|
|
e7e941047f | ||
|
|
1bda8b4fa2 | ||
|
|
dc73274b19 | ||
|
|
ecab31d704 | ||
|
|
2668d99d5a | ||
|
|
bc5b8a4a1e | ||
|
|
06ad1baa3a | ||
|
|
f263b63b8e | ||
|
|
92c015b97b | ||
|
|
7a81076c6a | ||
|
|
dbb21048e4 | ||
|
|
0eb040fcc8 | ||
|
|
5af7adb08e | ||
|
|
d9fc3a7e3f | ||
|
|
b554c9a6ef | ||
|
|
6cc4e21ae2 | ||
|
|
2cd13eb806 | ||
|
|
e03df9adc8 | ||
|
|
7d1e4b81e9 | ||
|
|
f3143a54a8 | ||
|
|
917d3e3fe0 | ||
|
|
d520172753 | ||
|
|
9c3c4b6bbc | ||
|
|
c449e01b9a | ||
|
|
525fe7ee28 | ||
|
|
18c0a69f74 | ||
|
|
3aa0c2d0d0 | ||
|
|
66939c839a | ||
|
|
444a0555c6 | ||
|
|
bdf9db7a21 | ||
|
|
57ecc15606 | ||
|
|
4728648a0c | ||
|
|
da1f678125 | ||
|
|
fd0be917fe | ||
|
|
4994c577cd | ||
|
|
7014628e8d | ||
|
|
493ec25fb3 | ||
|
|
1ec52e890d | ||
|
|
0fe4d83b93 | ||
|
|
ac56534c3b | ||
|
|
fe6f767561 |
No files matched your search
+15
-1
@@ -1,5 +1,16 @@
|
||||
_vendor/
|
||||
out/
|
||||
out/*
|
||||
!out/demo-pf-linux.cast
|
||||
!out/screencast/
|
||||
out/screencast/*
|
||||
!out/screencast/art/
|
||||
!out/screencast/art/*
|
||||
!out/screencast/en/
|
||||
out/screencast/en/*
|
||||
!out/screencast/en/*.mp4
|
||||
!out/screencast/pt/
|
||||
out/screencast/pt/*
|
||||
!out/screencast/pt/*.mp4
|
||||
*.o
|
||||
*.ko
|
||||
*.mod
|
||||
@@ -13,3 +24,6 @@ tools/out/
|
||||
lab/seeds/
|
||||
*.pcap
|
||||
*.log
|
||||
|
||||
__pycache__/
|
||||
*.pyc
|
||||
+210
@@ -0,0 +1,210 @@
|
||||
# Changelog
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Debian 13 implementation manual
|
||||
|
||||
`docs/en/debian13.md` + `docs/pt-BR/debian13.md` — the complete from-zero
|
||||
path on Debian 13 (trixie): host preparation, kernel 7.3.4, `pf.ko`, the
|
||||
userland, the libvirt lab, the gate suite and the stress test. Every command
|
||||
was executed on the lab's Debian 13.7 host; the toolchain output, the
|
||||
kernel.org checksum and the measured numbers are the real ones.
|
||||
|
||||
- `scripts/debian13/prepare-host.sh` — idempotent host preparation
|
||||
(packages + toolchain report). Verified on trixie: gcc 14.2.0, make 4.4.1,
|
||||
bison 3.8.2, flex 2.6.4, libvirt 11.3.0, QEMU 10.0.13.
|
||||
- **Two build-script bugs fixed** (they broke the plain
|
||||
`./scripts/build-kernel.sh` invocation the manual documents):
|
||||
`scripts/kernel-config.sh` resolved its default kernel tree to
|
||||
`../../linux_kernel/linux-7.3.4` (one level too many — it only worked when
|
||||
`KERNELDIR` was exported), and `scripts/build-kernel.sh` did not pass the
|
||||
tree it resolved on to `kernel-config.sh`, so the two could configure
|
||||
different trees. Both now agree on `<repo>/../linux-7.3.4`.
|
||||
- **gcc note**: Debian 13 ships gcc 14 and has no `gcc-15` in trixie. The
|
||||
7.3.4 kernel and `pf.ko` build with gcc 14 — no patch needed.
|
||||
|
||||
### Stress test (`tests/vm/16-stress.sh` + `scripts/stress/run-stress.sh`)
|
||||
|
||||
The project had no performance/load gate; the stress is a new gate that
|
||||
asserts *invariants under load* and reports throughput informationally, per
|
||||
the design decision that functional gates are the bar:
|
||||
|
||||
| Phase | Assertion |
|
||||
|---|---|
|
||||
| baseline / overhead | throughput with the module out of the path vs. with PF enabled (information + a configurable overhead limit) |
|
||||
| state churn | states appear under 300 concurrent connections and drain back after `pfctl -F s` (no state-table leak) |
|
||||
| rule churn | 200 reloads of a 200-rule ruleset, timed inside the VM, zero failures, stable rule count |
|
||||
| table churn | 2000 `pfr` entries added and flushed back to 0 |
|
||||
| integrity | 2 MB through `nat-to` under a concurrent stream — sha256 must match |
|
||||
| health | no `BUG/WARNING/Oops`, PF counters moving, the firewall still routing |
|
||||
|
||||
Report and raw log land in `out/stress/<timestamp>/report.md`; the guest's
|
||||
serial console is captured during the run so a panic is diagnosable.
|
||||
|
||||
Measured on the lab (full profile): 400 Mbit/s sustained with PF enabled at
|
||||
0% overhead against the no-module baseline, 300/300 concurrent flows tracked
|
||||
as states and the table drained back to 0, 200 reloads of a 202-rule ruleset
|
||||
with zero failures (11 ms average, 20 ms worst), 2000 `pfr` entries flushed
|
||||
back to 0, 2 MB through NAT byte-identical under load, and no
|
||||
`BUG/WARNING/Oops` in `dmesg`.
|
||||
|
||||
### Capacity finding: the workqueue backlog OOMs the guest above ~1 Gbit/s
|
||||
|
||||
Measured while building the stress test, and now documented in
|
||||
`docs/*/caveats.md` §13: PF steals every skb onto one ordered workqueue, so
|
||||
the backlog grows with the offered rate. On the 1 GB lab guest, 400 Mbit/s
|
||||
through a stateful ruleset is stable and ~1 Gbit/s **panics the kernel**
|
||||
("System is deadlocked on memory"). The stress test therefore runs its
|
||||
traffic phases at a bounded rate; the functional gates are unaffected.
|
||||
|
||||
- **M5 (first step)**: OpenBSD's `hfsc.c` and `fq_codel.c` now compile and link
|
||||
into `pf.ko` (157 scheduler symbols reachable from `pf_ioctl`). Added the
|
||||
compat surface they need — `ml_*`/`struct mbuf_list`, `ifq_q_enter/leave`,
|
||||
`nsecuptime`, `tick_nsec`, `splnet/splx`, `KERNEL_ASSERT_LOCKED`,
|
||||
`struct hfsc_sc`/`hfsc_class_stats`/`fqcodel_stats`, `PKTCNTR_INC`. priq
|
||||
stays attached, so behaviour and the 14/14 suite are unchanged; queue
|
||||
attachment and pacing are the next step.
|
||||
|
||||
## v0.6.0 — 2026-11-11
|
||||
|
||||
Adds scrub, route pools and `reply-to` verification. Suite: 14 gates, all green.
|
||||
|
||||
| Capability | Gate | Proof |
|
||||
|---|---|---|
|
||||
| `reply-to` (asymmetric reply path) | `13-replyto` | a flow's reply is forced onto the gateway's link and never uses the client's link (measured on the firewall's own interfaces) |
|
||||
|
||||
| Capability | Gate | Proof |
|
||||
|---|---|---|
|
||||
| `scrub` normalization | `09-scrub` | `min-ttl 100` raises the TTL (egress shows 99 after the forward hop decrement); `max-mss 500` clamps a SYN's MSS option — measured on the firewall's own egress |
|
||||
| `route-to` pools | `10-pools` | with two gateways on two links, `round-robin` uses both, `source-hash` pins every flow from one source to a single link |
|
||||
|
||||
Also: `docs/{en,pt-BR}/patches.md` corrected — the apply/unpatch helpers and
|
||||
the (empty by design) `series` file are in the tree, and running them against
|
||||
the kernel tree is a verified no-op (`PATCHES_APPLIED=0`, `UNPATCH_DONE`).
|
||||
|
||||
## v0.5.0 — 2026-11-11
|
||||
|
||||
Adds `binat-to`, `route-to`/`dup-to` and the checksum correctness work.
|
||||
Suite: 11 gates, all green in the libvirt lab.
|
||||
|
||||
### Verified in the lab (new since v0.4.0)
|
||||
|
||||
| Capability | Gate | What it proves |
|
||||
|---|---|---|
|
||||
| `binat-to` (1:1 bidirectional NAT) | `07-binat` | pfctl's expansion into `nat-to … static-port` + `rdr-to` both work: the peer sees the mapped address, the original never leaks, the reply is translated back |
|
||||
| `route-to` (forced nexthop) | `08-routeto` | the packet leaves through the gateway's link instead of the normal egress (proved on the firewall's own interfaces) |
|
||||
| `dup-to` (packet duplication) | `08-routeto` | the original path keeps working and a copy is emitted to the gateway |
|
||||
| bulk data through translated flows | `06-rdr` | 2 MB pulled through a redirect, byte-identical, firewall still responsive afterwards |
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Neighbour resolution for forced routes**: Linux only ARPs the gateway when
|
||||
the route declares one, so `route-to` ARPed the *final* destination on the
|
||||
gateway's link. The port now sets `rt_gw4`/`rt_gw_family` on the looked-up
|
||||
route (the same pattern OVS uses).
|
||||
- **`route-to` looked the route up with the packet's source**, which is not
|
||||
local for transit traffic → `ENETUNREACH` → silent drop. Destination-only
|
||||
lookup now.
|
||||
- **`if_output_tso` reference imbalance**: the stack's output path consumed the
|
||||
hook queue's skb reference, so the work queue's cleanup double-freed the skb
|
||||
and corrupted the slab (observed as the firewall dying mid-test).
|
||||
- **GSO/TSO checksums**: materializing a transport checksum in software for a
|
||||
translated skb covers only the first segment; every later segment is then
|
||||
wrong, bulk transfers stall and the firewall's own `sshd` starves. The port
|
||||
now recomputes in software only for non-GSO skbs and hands `CHECKSUM_PARTIAL`
|
||||
back to the NIC otherwise (regression guarded by gate `06-rdr`).
|
||||
- Gate `08` counts only echo *requests* (a reply also contains the client
|
||||
address) and tolerates a not-yet-created capture file.
|
||||
|
||||
### Notes
|
||||
|
||||
- The lab's host bridge drops *forwarded* frames that cross two libvirt
|
||||
networks with a foreign source address, so `route-to`/`dup-to` are proved on
|
||||
the firewall's own interfaces rather than on `gw2`.
|
||||
|
||||
## 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.
|
||||
@@ -1,7 +1,7 @@
|
||||
# PF-on-Linux top-level make
|
||||
KERNELDIR ?= $(HOME)/lab/linux_kernel/linux-7.3.4
|
||||
|
||||
.PHONY: module tools kernel test clean vm vm-destroy docs
|
||||
.PHONY: module tools kernel test stress clean vm vm-destroy docs demo
|
||||
|
||||
module:
|
||||
$(MAKE) -C $(KERNELDIR) M=$(CURDIR)/module modules
|
||||
@@ -21,11 +21,22 @@ vm-destroy:
|
||||
test:
|
||||
./scripts/vm-run-tests.sh
|
||||
|
||||
# Stress: throughput/state/rule/table churn against the lab, with a report in
|
||||
# out/stress/<timestamp>/report.md. Pass options through, e.g.
|
||||
# make stress ARGS="--quick"
|
||||
stress:
|
||||
./scripts/stress/run-stress.sh $(ARGS)
|
||||
|
||||
docs:
|
||||
@for f in docs/en/*.md; do echo "EN $$f"; done
|
||||
@for f in docs/pt-BR/*.md; do echo "PT $$f"; done
|
||||
|
||||
# Record the narrated screencasts (real shell sessions, MiniMax voice).
|
||||
# Needs MINIMAX_API_KEY and the VM lab up; see docs/*/screencast.md.
|
||||
screencast:
|
||||
./scripts/screencast/build-all.sh
|
||||
|
||||
clean:
|
||||
$(MAKE) -C $(KERNELDIR) M=$(CURDIR)/module clean || true
|
||||
$(MAKE) -C tools clean || true
|
||||
rm -rf out/
|
||||
@find out -maxdepth 1 -type f ! -name '*.cast' -delete 2>/dev/null || true
|
||||
@@ -1,17 +1,33 @@
|
||||
# PF on Linux
|
||||
|
||||
Port of the OpenBSD **PF** (packet filter) to **Linux 7.3.4** as out-of-tree
|
||||
kernel modules — the real PF engine (`pf.c`, `pf_norm.c`, `pf_table.c`,
|
||||
`pf_lb.c`, … ported from OpenBSD 8.0 sources) driven by the real OpenBSD
|
||||
`pfctl` over the `/dev/pf` ioctl ABI.
|
||||
Port of the OpenBSD **PF** (packet filter) to **Linux 7.3.4** as an
|
||||
out-of-tree kernel module — the real PF engine (`pf.c`, `pf_norm.c`,
|
||||
`pf_table.c`, `pf_lb.c`, `hfsc.c`, … ported from OpenBSD 8.0 sources) driven by
|
||||
the real OpenBSD `pfctl` over the `/dev/pf` ioctl ABI.
|
||||
|
||||
**Status:** implementation in progress — see
|
||||
[`docs/superpowers/plans/2026-11-11-pf-linux-port.md`](docs/superpowers/plans/2026-11-11-pf-linux-port.md)
|
||||
for task progress and
|
||||
[`docs/superpowers/specs/2026-11-11-pf-linux-port-design.md`](docs/superpowers/specs/2026-11-11-pf-linux-port-design.md)
|
||||
for the design.
|
||||
**Status:** the filter core, stateful filtering, tables, anchors, NAT
|
||||
(`nat-to`/`rdr-to`/`binat-to`), forced routing (`route-to`/`dup-to`/`reply-to`),
|
||||
pools, `divert`, `pflog` and the OpenBSD 8.0 **queues (HFSC)** are **verified
|
||||
in a real libvirt lab** — 16/16 gates green. What is still pending is stated
|
||||
per feature in [`docs/en/feature-matrix.md`](docs/en/feature-matrix.md).
|
||||
|
||||
## What you get (planned)
|
||||
Screencasts (EN + PT, narrated): [`docs/en/screencast.md`](docs/en/screencast.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 |
|
||||
|---|---|---|
|
||||
| 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 | **done** — gates 05/06/07/09 (incl. 2 MB integrity through a redirect, min-ttl/max-mss measured) |
|
||||
| M4 | route-to/dup-to/reply-to, pools, divert e2e, pflog | **done** — divert (11), pflog (12), route-to/dup-to (08), pools (10), reply-to (13) verified |
|
||||
| M5 | queues: HFSC back end in the data path | **done (mechanical)** — gate 15: queues load, hfsc attaches, `pfctl -s queue -v` reports class stats, a 2 MB queued flow is counted by the class. `bandwidth` = HFSC linkshare (guarantee, not cap; 8.0 has no upperlimit syntax) |
|
||||
| M6 | docs complete, patchset tidy, full suite green, tagged release | **done** — docs EN+PT-BR, 16/16 suite green, tagged (`v1.0.0`) |
|
||||
|
||||
## What you get
|
||||
|
||||
| Area | Feature |
|
||||
|---|---|
|
||||
@@ -19,36 +35,67 @@ for the design.
|
||||
| State/Tables | stateful firewall engine, `pfr` tables (radix + hash, `pfctl -t`) |
|
||||
| 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` |
|
||||
| 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`) |
|
||||
| Route | `route-to` (pools rr/hash-source/hash-state, `fail-to`), `reply-to`, `dup-to` |
|
||||
| Logging | `pflogd` via netlink pflog channel (DLT_PFLOG pcap) |
|
||||
| QoS (ALTQ successor) | `queue`/`queue on` with OpenBSD 8.0 `ifq` schedulers: **HFSC verified in the data path** (gate 15), priq default, FQ-CoDel compiled; `pfctl -s queue -v` works |
|
||||
| Divert | `divert-to` / `divert` tag + `pdivert` relay over an in-module `PF_DIVERT` socket family (verified: packet to userspace and back) |
|
||||
| Route | `route-to`/`dup-to`/`reply-to` + pools (`round-robin`, `source-hash`) verified (`fail-to` no longer exists in OpenBSD 8.0) |
|
||||
| Logging | `pflogd` via `/dev/pflog` (DLT_PFLOG pcap, OpenBSD record layout) — verified |
|
||||
| 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
|
||||
instances, classic-ALTQ-only schedulers (cbq/wfq/red — removed upstream before
|
||||
OpenBSD 8.0).
|
||||
|
||||
## Quick start (after M1+)
|
||||
## Screencasts
|
||||
|
||||
Seven narrated screencasts per language (English and Portuguese), 1080p30 with
|
||||
burned-in subtitles, the lab's network diagram drawn over the terminal, and a
|
||||
continuous film that crossfades the phases together. Every video is a **real
|
||||
shell session** against the Alpine VMs — commands typed key by key, the kernel
|
||||
answering live — with a MiniMax female voice narrating:
|
||||
|
||||
```sh
|
||||
./scripts/fetch-sources.sh # OpenBSD 8.0 sources (C3SL mirror, checksummed)
|
||||
./scripts/apply-patches.sh ../linux-7.3.4 # core export patch(es)
|
||||
make module tools # pf.ko, pfq.ko, pfctl, pdivert, pflogd
|
||||
sudo insmod module/pf.ko module/pfq.ko
|
||||
./scripts/screencast/build-all.sh # -> out/screencast/{en,pt}/*.mp4
|
||||
```
|
||||
|
||||
Details, per-phase breakdown and the YouTube description text:
|
||||
[`docs/en/screencast.md`](docs/en/screencast.md) ·
|
||||
[`docs/pt-BR/screencast.md`](docs/pt-BR/screencast.md)
|
||||
|
||||
## Quick start
|
||||
|
||||
Full recipe: [`docs/en/install.md`](docs/en/install.md). **Debian 13 (trixie)
|
||||
from zero** (host prep → kernel → module → tools → lab → stress):
|
||||
[`docs/en/debian13.md`](docs/en/debian13.md). Short version
|
||||
(commands are read from the scripts):
|
||||
|
||||
```sh
|
||||
./scripts/fetch-sources.sh # OpenBSD 8.0 sources (C3SL mirror, sha256-pinned)
|
||||
./scripts/vendorize.sh # stage the pristine files we port
|
||||
./scripts/build-kernel.sh # kernel 7.3.4: bzImage + modules_prepare (export patch: none needed)
|
||||
./scripts/build-module.sh # -> module/pf.ko
|
||||
make -C tools # -> tools/out/{pfctl,pdivert,pflogd,abitest}
|
||||
sudo insmod module/pf.ko # /dev/pf (0600) + netfilter hooks
|
||||
sudo pfctl -f /etc/pf.conf && sudo pfctl -e
|
||||
```
|
||||
|
||||
VM validation lab (Alpine on libvirt): see `docs/en/vm-lab.md`.
|
||||
Documentação em português: [`README.pt-BR.md`](README.pt-BR.md) e `docs/pt-BR/`.
|
||||
Every feature listed above is exercised by the lab suite before you need it;
|
||||
[`docs/en/feature-matrix.md`](docs/en/feature-matrix.md) says which gate proves
|
||||
what, and [`docs/en/pf-guide.md`](docs/en/pf-guide.md) lists the deviations you
|
||||
should know before putting PF on a path that matters.
|
||||
|
||||
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
|
||||
|
||||
- `module/` — kernel sources (ported PF + compat layer + pfq qdisc)
|
||||
- `tools/` — pfctl/pdivert/pflogd Linux builds
|
||||
- `patches/kernel/` — documented Linux core patches (export symbols only)
|
||||
- `scripts/` — fetch/build/patch/VM automation
|
||||
- `tests/` — VM suite (`tests/vm/NN-*.sh`, scapy helpers)
|
||||
- `module/` — kernel sources: ported PF engine (`module/pfsrc`) + Linux compat layer (`module/compat`)
|
||||
- `tools/` — pfctl (static Linux build), pdivert relay, pflogd, ABI harness (`make -C tools abi`)
|
||||
- `patches/kernel/` — Linux core patch set (currently empty; evidence in `p1-needs.txt`, see `docs/en/patches.md`)
|
||||
- `scripts/` — fetch/build/patch/VM automation, plus `scripts/screencast/` for the videos
|
||||
- `scripts/debian13/` — Debian 13 host preparation (`prepare-host.sh`)
|
||||
- `scripts/stress/` — stress runner (`run-stress.sh`) + report writer
|
||||
- `tests/vm/` — VM suite: 16 gates (`tests/vm/NN-*.sh`) + `lib.sh`
|
||||
- `docs/en/` + `docs/pt-BR/` — full bilingual documentation
|
||||
- `docs/superpowers/` — design spec + implementation plan
|
||||
|
||||
|
||||
+76
-25
@@ -1,52 +1,103 @@
|
||||
# PF no Linux
|
||||
|
||||
Port do **PF** (packet filter) do OpenBSD para o **Linux 7.3.4** como módulos
|
||||
out-of-tree — o engine PF real (`pf.c`, `pf_norm.c`, `pf_table.c`, `pf_lb.c`, …
|
||||
portados dos fontes do OpenBSD 8.0) controlado pelo `pfctl` real do OpenBSD via
|
||||
a ABI ioctl de `/dev/pf`.
|
||||
Port do **PF** (packet filter) do OpenBSD para o **Linux 7.3.4** como um
|
||||
módulo de kernel out-of-tree — o engine PF real (`pf.c`, `pf_norm.c`,
|
||||
`pf_table.c`, `pf_lb.c`, `hfsc.c`, … portados dos fontes do OpenBSD 8.0)
|
||||
controlado pelo `pfctl` real do OpenBSD via a ABI ioctl de `/dev/pf`.
|
||||
|
||||
**Status:** implementação em andamento — veja o
|
||||
[plano de implementação](docs/superpowers/plans/2026-11-11-pf-linux-port.md) e o
|
||||
[design doc](docs/superpowers/specs/2026-11-11-pf-linux-port-design.md).
|
||||
**Status:** o núcleo de filtragem, a filtragem stateful, tabelas, anchors, NAT
|
||||
(`nat-to`/`rdr-to`/`binat-to`), roteamento forçado (`route-to`/`dup-to`/
|
||||
`reply-to`), pools, `divert`, `pflog` e as **filas do OpenBSD 8.0 (HFSC)** estão
|
||||
**verificados num lab libvirt real** — 16/16 gates verdes. O que ainda está
|
||||
pendente está dito por feature em
|
||||
[`docs/pt-BR/feature-matrix.md`](docs/pt-BR/feature-matrix.md).
|
||||
|
||||
## O que você obtém (planejado)
|
||||
Screencasts (EN + PT, com narração): [`docs/pt-BR/screencast.md`](docs/pt-BR/screencast.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 |
|
||||
|---|---|---|
|
||||
| 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 | **concluído** — gates 01/02/03/04 verdes |
|
||||
| M3 | NAT (`nat-to`/`rdr-to`/`binat-to`), scrub | **concluído** — gates 05/06/07/09 (incl. 2 MB íntegros através de um redirect, min-ttl/max-mss medidos) |
|
||||
| M4 | route-to/dup-to/reply-to, pools, divert e2e, pflog | **concluído** — divert (11), pflog (12), route-to/dup-to (08), pools (10), reply-to (13) verificados |
|
||||
| M5 | filas: back end HFSC no caminho de dados | **concluído (mecânico)** — gate 15: as filas carregam, o hfsc é anexado, `pfctl -s queue -v` mostra as estatísticas das classes, e um fluxo de 2 MB pela fila é contado pela classe. `bandwidth` = linkshare do HFSC (garantia, não teto; o 8.0 não tem sintaxe de upperlimit) |
|
||||
| M6 | docs completas, patchset arrumado, suíte inteira verde, release com tag | **concluído** — docs EN+PT-BR, 16/16 da suíte verdes, tag `v1.0.0` |
|
||||
|
||||
## O que você obtém
|
||||
|
||||
| Área | Recurso |
|
||||
|---|---|
|
||||
| Filtragem | regras, anchors, quick, `match`/`block`(drop/return/return-rst)/`pass`, `keep state`, syncookies |
|
||||
| Estado/Tables | firewall stateful, tables `pfr` (radix + hash, `pfctl -t`) |
|
||||
| NAT | `nat-to` (pools de portas, sticky-port, static-port), `rdr-to`, `binat-to` |
|
||||
| Scrub | remontagmento 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` |
|
||||
| Divert | `divert-to` / tag `divert` + canal userspace `pdivert` (netlink; Linux não tem `AF_DIVERT`) |
|
||||
| Roteamento | `route-to` (pools rr/hash-source/hash-state, `fail-to`), `reply-to`, `dup-to` |
|
||||
| Logging | `pflogd` via canal netlink pflog (pcap DLT_PFLOG) |
|
||||
| Scrub | remontagem 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: **HFSC verificado no caminho de dados** (gate 15), priq como default, FQ-CoDel compilado; `pfctl -s queue -v` funciona |
|
||||
| Divert | `divert-to` / tag `divert` + relay `pdivert` sobre uma família de sockets `PF_DIVERT` dentro do módulo (verificado: pacote vai para o userspace e volta) |
|
||||
| Roteamento | `route-to`/`dup-to`/`reply-to` + pools (`round-robin`, `source-hash`) verificados (`fail-to` não existe mais no OpenBSD 8.0) |
|
||||
| Logging | `pflogd` via `/dev/pflog` (pcap DLT_PFLOG, layout de registro do OpenBSD) — verificado |
|
||||
| Controle | `/dev/pf` (0600), ABI ioctl do OpenBSD 8.0, `pfctl` compilado para Linux (binário único) |
|
||||
|
||||
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
|
||||
OpenBSD antes da 8.0).
|
||||
|
||||
## Início rápido (após M1+)
|
||||
## Screencasts
|
||||
|
||||
Sete screencasts narrados por idioma (inglês e português), 1080p30 com
|
||||
legendas queimadas, o diagrama de rede do lab desenhado sobre o terminal e um
|
||||
filme contínuo que emenda as fases com transições. Cada vídeo é uma **sessão
|
||||
shell real** contra as VMs Alpine — comandos digitados tecla a tecla, o kernel
|
||||
respondendo ao vivo — com narração de voz feminina gerada pelo MiniMax:
|
||||
|
||||
```sh
|
||||
./scripts/fetch-sources.sh # fontes OpenBSD 8.0 (mirror C3SL, com checksum)
|
||||
./scripts/apply-patches.sh ../linux-7.3.4 # patch(es) de core (exports)
|
||||
make module tools # pf.ko, pfq.ko, pfctl, pdivert, pflogd
|
||||
sudo insmod module/pf.ko module/pfq.ko
|
||||
./scripts/screencast/build-all.sh # -> out/screencast/{en,pt}/*.mp4
|
||||
```
|
||||
|
||||
Detalhes, quebra por fase e o texto de descrição do YouTube:
|
||||
[`docs/pt-BR/screencast.md`](docs/pt-BR/screencast.md) ·
|
||||
[`docs/en/screencast.md`](docs/en/screencast.md)
|
||||
|
||||
## Início rápido
|
||||
|
||||
Receita completa: [`docs/pt-BR/install.md`](docs/pt-BR/install.md). **Do zero no
|
||||
Debian 13 (trixie)** (preparar host → kernel → módulo → ferramentas → lab →
|
||||
stress): [`docs/pt-BR/debian13.md`](docs/pt-BR/debian13.md). Versão
|
||||
curta (comandos lidos dos scripts):
|
||||
|
||||
```sh
|
||||
./scripts/fetch-sources.sh # fontes OpenBSD 8.0 (mirror C3SL, sha256 fixado)
|
||||
./scripts/vendorize.sh # staging dos arquivos upstream portados
|
||||
./scripts/build-kernel.sh # kernel 7.3.4: bzImage + modules_prepare (patch de export: nenhum necessário)
|
||||
./scripts/build-module.sh # -> module/pf.ko
|
||||
make -C tools # -> tools/out/{pfctl,pdivert,pflogd,abitest}
|
||||
sudo insmod module/pf.ko # /dev/pf (0600) + hooks netfilter
|
||||
sudo pfctl -f /etc/pf.conf && sudo pfctl -e
|
||||
```
|
||||
|
||||
Lab de validação em VMs (Alpine via libvirt): `docs/pt-BR/vm-lab.md`.
|
||||
Documentation in English: [`README.md`](README.md) and `docs/en/`.
|
||||
Toda feature listada acima é exercitada pela suíte do lab antes de você
|
||||
precisar dela; [`docs/pt-BR/feature-matrix.md`](docs/pt-BR/feature-matrix.md)
|
||||
diz qual gate prova o quê, e [`docs/pt-BR/pf-guide.md`](docs/pt-BR/pf-guide.md)
|
||||
lista as divergências que você deve conhecer antes de colocar o PF num
|
||||
caminho que importa.
|
||||
|
||||
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
|
||||
|
||||
- `module/` — fontes de kernel (PF portado + camada de compat + qdisc pfq)
|
||||
- `tools/` — builds Linux de pfctl/pdivert/pflogd
|
||||
- `patches/kernel/` — patches documentados no core do Linux (apenas exports)
|
||||
- `scripts/` — automação de fetch/build/patch/VM
|
||||
- `tests/` — suíte em VM (`tests/vm/NN-*.sh`, helpers scapy)
|
||||
- `module/` — fontes de kernel: engine PF portado (`module/pfsrc`) + camada de compat Linux (`module/compat`)
|
||||
- `tools/` — pfctl (build estático Linux), relay pdivert, pflogd, verificador de ABI (`make -C tools abi`)
|
||||
- `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, mais `scripts/screencast/` para os vídeos
|
||||
- `scripts/debian13/` — preparação do host Debian 13 (`prepare-host.sh`)
|
||||
- `scripts/stress/` — runner do stress (`run-stress.sh`) + gerador de relatório
|
||||
- `tests/vm/` — suíte em VM: 16 gates (`tests/vm/NN-*.sh`) + `lib.sh`
|
||||
- `docs/en/` + `docs/pt-BR/` — documentação completa bilíngue
|
||||
- `docs/superpowers/` — design + plano de implementação
|
||||
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# 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`, `hfsc.c`, …) running as the out-of-tree module
|
||||
`pf.ko`, driven by the real OpenBSD `pfctl` over the `/dev/pf` ioctl ABI.
|
||||
|
||||
## Index
|
||||
|
||||
| Doc | What it covers |
|
||||
|---|---|
|
||||
| [guide.md](guide.md) | One-page architecture: components, data path, control plane, milestones |
|
||||
| [install.md](install.md) | Apply/build/install recipe (kernel, module, tools) |
|
||||
| [debian13.md](debian13.md) | Full from-zero implementation on Debian 13 (trixie): host prep, kernel/module/tools build, libvirt lab, stress test |
|
||||
| [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 of the 16 gates proves |
|
||||
| [feature-matrix.md](feature-matrix.md) | Per-feature status: VERIFIED-in-VM / VERIFIED-offline / COMPILES-untested / NOT-ENABLED |
|
||||
| [pf-guide.md](pf-guide.md) | Daily use: what works today in `/etc/pf.conf`, and the deviations to know about |
|
||||
| [screencast.md](screencast.md) | The narrated videos (English and Portuguese): phases, pipeline, how to re-record |
|
||||
| [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 + the deviation record (the truth about compat-layer divergences)
|
||||
|
||||
Feature-status vocabulary used across these docs:
|
||||
|
||||
- **VERIFIED-in-VM** — exercised end-to-end in the libvirt lab; the gate that proves it is named (see [vm-lab.md](vm-lab.md)).
|
||||
- **VERIFIED-offline** — proven by a fixture or ABI test, not by traffic.
|
||||
- **COMPILES-untested** — the code is built into `pf.ko`/`pfctl` but no gate has exercised it.
|
||||
- **NOT-ENABLED** — the code exists but the feature is off in this build.
|
||||
- **OUT-OF-SCOPE** — non-goal by design (spec §3).
|
||||
|
||||
The lab suite is **16/16 green** (`./scripts/vm-run-tests.sh`).
|
||||
@@ -0,0 +1,141 @@
|
||||
# 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` (a single module: the BSD
|
||||
`ifq`/`pfq` interface lives inside it, it is not a separate `tc` qdisc). 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`, `pfk_pflog.c`, `hfsc.c`, `fq_codel.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`, `pdivert`, `pflogd`, `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` — the divert relay, built from `tools/pdivert/`. It talks to the
|
||||
`AF_DIVERT` socket family the module registers at runtime
|
||||
(`socket(PF_DIVERT=32, SOCK_RAW, IPPROTO_DIVERT=254)`); gate `11-divert.sh`
|
||||
proves the round trip.
|
||||
- `pflogd` — reads `/dev/pflog` and writes a DLT_PFLOG pcap whose record
|
||||
layout is byte-compatible with OpenBSD `pflog(4)`; gate `12-pflog.sh`.
|
||||
|
||||
## 7. Screencasts — `scripts/screencast/build-all.sh`
|
||||
|
||||
Not part of the kernel build, but part of the deliverable. The pipeline:
|
||||
|
||||
| Stage | Script | What it does |
|
||||
|---|---|---|
|
||||
| narration text | `make_narration.py` | writes `scripts/screencast/narration/<phase>.{en,pt}.json` (one segment per beat of the session) |
|
||||
| voice | `make_audio.py` | MiniMax TTS, one MP3 per segment, female voice per language |
|
||||
| session | `record.py` | real SSH session on the lab: commands typed key by key, captured as asciicast v2 |
|
||||
| video | `render_video.py` | replays the capture through a terminal emulator, draws the lab diagram, burns the subtitles |
|
||||
| assembly | `assemble.py` | mixes the narration onto the timeline |
|
||||
| full film | `join.py` | crossfades the phases through chapter cards |
|
||||
|
||||
`make screencast` (or the script) runs all of it; it needs
|
||||
`MINIMAX_API_KEY` and the lab up. Details: [screencast.md](screencast.md).
|
||||
|
||||
## 8. Root `Makefile`
|
||||
|
||||
`make module | tools | kernel | vm | vm-destroy | test | screencast | docs | clean` — thin
|
||||
wrappers over the scripts above. `make test` runs the VM suite
|
||||
([vm-lab.md](vm-lab.md)); `make screencast` renders the videos;
|
||||
`make docs` just lists the bilingual doc set.
|
||||
|
||||
## What has been exercised vs. not
|
||||
|
||||
- Stages 1–6 have each been run repeatedly on the build host (artifacts exist
|
||||
in-tree: `out/`, `module/pf.ko`, `tools/out/{pfctl,pdivert,pflogd}`), and the
|
||||
scripts above were verified line-by-line for this document.
|
||||
- Stage 7 (the screencasts) has been run end to end for all seven phases in
|
||||
both languages; the videos are in `out/screencast/{en,pt}/`.
|
||||
- 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.
|
||||
@@ -0,0 +1,233 @@
|
||||
# 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: PF evaluates the **out** ruleset at `FORWARD` (OpenBSD does
|
||||
the same in `ip_forward()`), and `POSTROUTING` is skipped once that pass is
|
||||
done. `nat-to`/`rdr-to` were validated against this ordering (gates 05/06).
|
||||
- The "overlapping policy with conntrack" warning from the design still
|
||||
applies: if iptables/nft SNAT also runs, PF's translation happens at the
|
||||
layer it is hooked into, and double translation is yours to avoid.
|
||||
|
||||
## Control plane / lifecycle
|
||||
|
||||
### 6. Unload is hardened and soak-verified
|
||||
|
||||
`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`. Gate `14-soak.sh`
|
||||
drives ICMP+TCP traffic, checks `dmesg` for faults, then runs
|
||||
`rmmod` → `insmod` → `rmmod` and compares the slab footprint before and
|
||||
after: clean unload, successful reload, no growth. Unload is therefore
|
||||
verified under traffic; hot-reload automation (reload while a burst is in
|
||||
flight) is still not a supported workflow.
|
||||
|
||||
## Behavioral notes verified today
|
||||
|
||||
### 7. `pfctl -s states` lists real states, including translations
|
||||
|
||||
The earlier anomaly was a use-after-free: `refcnt_rele()` had inverted
|
||||
polarity, so live state keys were freed while still linked in the state
|
||||
RBT — that both hid states and crashed the tree walk (`pfctl -s states`
|
||||
hanging the box). After the fix, gates 01/04/05/06/07 assert on the listed
|
||||
states, and translated flows print both tuples (`10.0.2.1:59335
|
||||
(10.0.1.10:4380) -> 10.0.2.20:8`).
|
||||
|
||||
### 8. Consumers still required for two features
|
||||
|
||||
`divert-to` needs a process bound to the divert port (`tools/pdivert`); with
|
||||
no listener the packet is dropped, exactly like BSD's `divs_noport`, and the
|
||||
kernel prints `pfk: divert port N: no socket bound`. `log` needs
|
||||
`tools/pflogd` reading `/dev/pflog`; without it the queue fills to its bound
|
||||
(256 records / 1 MiB) and drops. Neither is a stub any more, but neither does
|
||||
anything until its consumer runs (see [pf-guide.md](pf-guide.md)).
|
||||
|
||||
### 9. Queues: path verified; shaping semantics are HFSC's, not a bug
|
||||
|
||||
`15-queue.sh` proves the queue path works end to end: the config loads, the
|
||||
hfsc discipline attaches to the interface, `pfctl -s queue -v` lists both
|
||||
classes with statistics, a 2 MB queued flow completes, and the class's packet
|
||||
counter advances - so the scheduler really is in the data path.
|
||||
|
||||
What the lab cannot show is a *rate cap*, and that is HFSC semantics rather
|
||||
than a port defect: OpenBSD 8.0's `pf.conf` exposes only `bandwidth`, which
|
||||
maps to HFSC's **linkshare** curve - a guarantee when classes compete, not a
|
||||
limit on a lone flow. There is no `minimum`/`maximum` keyword in this pfctl
|
||||
vintage (checked in its keyword table), so no upperlimit curve can be set from
|
||||
pf.conf. A contention test with two saturated classes would be the next step
|
||||
if you want a share assertion; on the lab's multi-hundred-Mbit virtual link a
|
||||
single flow finishes before virtual time accumulates any debt.
|
||||
|
||||
Bugs found and fixed while getting here (details in `docs/porting-notes.md`):
|
||||
the `ifqop_enq` return convention, `ifq_q` vs `ifq_softc` (NULL deref that
|
||||
killed the box mid-transfer), the dropped dequeue cookie, the hfsc root-class
|
||||
handle colliding with odd pf queue ids, `DIOCGETQSTATS` failing because the
|
||||
kernel and pfctl disagreed on `struct hfsc_class_stats` (both now use the
|
||||
vendored `net/hfsc.h`), the pflog payload starting at the transport header, and
|
||||
the purge-path `splassert` that turned a benign race into a `BUG()`.
|
||||
|
||||
## 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.
|
||||
|
||||
## Screencast pipeline (2026-11-12)
|
||||
|
||||
### 10. MiniMax video generation is not enabled on this account
|
||||
|
||||
Every MiniMax video model (`T2V-01`, `T2V-01-Director`, `MiniMax-Hailuo-02`)
|
||||
answers with API error **2068 — "The current Token Plan tier does not support
|
||||
this model"**. The narration (TTS) and the title artwork work fine; only the
|
||||
video models are blocked. The phase transitions are therefore rendered
|
||||
locally with ffmpeg (a crossfade over a chapter card) instead of AI-generated
|
||||
clips. Upgrading the plan is the only thing needed to change that — the
|
||||
extension point is `scripts/screencast/join.py`, which builds the cards.
|
||||
|
||||
### 11. The narration is a separate track, not a dubbing of the video
|
||||
|
||||
Each phase is recorded **once** and serves both languages: the terminal
|
||||
session is language-neutral, and the two narrated versions differ only in the
|
||||
audio track and the burned-in subtitles. The recorder holds each beat on
|
||||
screen for as long as the longest narration segment (EN or PT) needs, so the
|
||||
voice and the terminal action stay in step in both.
|
||||
|
||||
### 12. What the videos do not show
|
||||
|
||||
The videos are a demonstration, not a test run: the lab's own gate suite
|
||||
(`scripts/vm-run-tests.sh`) is the authority for PASS/FAIL, and its logs live
|
||||
in `out/test-logs/`. The screencasts show the same commands, but a video frame
|
||||
is not a verdict.
|
||||
|
||||
## Capacity findings (2026-11-12, from `scripts/stress/run-stress.sh`)
|
||||
|
||||
### 13. The workqueue backlog grows with the offered rate: above ~1 Gbit/s the guest OOM-panics
|
||||
|
||||
This is the sharpest consequence of §1 and it is **reproducible**, not
|
||||
theoretical. PF steals every skb onto one ordered workqueue and runs the
|
||||
engine in process context, so the number of packets in flight is bounded only
|
||||
by the memory the backlog takes.
|
||||
|
||||
Measured on the lab (Alpine guest, **1 GB** RAM, 4 TCP streams through a
|
||||
stateful ruleset):
|
||||
|
||||
| Offered rate (per stream × 4) | Result |
|
||||
|---|---|
|
||||
| 50 Mbit/s (200 Mbit/s total) | stable |
|
||||
| 100 Mbit/s (400 Mbit/s total) | stable |
|
||||
| 250 Mbit/s (**1 Gbit/s** total) | **kernel panic: "System is deadlocked on memory"** |
|
||||
|
||||
The panic is an OOM with no killable process; the slab at that moment shows
|
||||
`kmalloc-8k` ≈ 50 MB, `skbuff_head_cache` ≈ 18 MB and `files_cache` ≈ 40 MB,
|
||||
i.e. the backlog is what ate the 1 GB. The guest reboots (120 s watchdog
|
||||
delay) and every connection through the firewall is lost with it.
|
||||
|
||||
Practical consequences:
|
||||
|
||||
- **Rate-limit what you point at PF**, and size the box for the backlog:
|
||||
memory needed grows with the offered rate, not with the number of
|
||||
concurrent flows.
|
||||
- The stress test (`tests/vm/16-stress.sh`) therefore runs its traffic phases
|
||||
at a **bounded** rate (default 100 Mbit/s per stream = 400 Mbit/s total) —
|
||||
the regime this port survives — and reports the ceiling separately instead
|
||||
of OOM-killing the firewall under test.
|
||||
- The functional gates (01-15) are unaffected: they move megabytes, not gigabits
|
||||
per second.
|
||||
|
||||
What would fix it is a real fast path (evaluate `pf_test()` inline in
|
||||
softirq, as OpenBSD does) or a bounded queue with a drop policy — both are
|
||||
design changes beyond this port's scope.
|
||||
|
||||
## 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).
|
||||
@@ -0,0 +1,498 @@
|
||||
# PF on Linux — implementing it from scratch on Debian 13 (trixie)
|
||||
|
||||
This document is the complete path, from zero, to run **PF-on-Linux** (the
|
||||
OpenBSD 8.0 PF ported to Linux as an out-of-tree kernel module) on a
|
||||
**Debian 13 (trixie)** machine: prepare the host, build the 7.3.4 kernel,
|
||||
build `pf.ko` and `pfctl`, bring up the libvirt lab, run the 16-gate suite
|
||||
and the **stress test**.
|
||||
|
||||
Every command below was executed on the lab's Debian 13.7 (`trixie`) host and
|
||||
the real output is shown. Where a number matters, it is the measured number —
|
||||
not an estimate.
|
||||
|
||||
---
|
||||
|
||||
## 0. What has to be clear before you start
|
||||
|
||||
| Fact | Practical consequence |
|
||||
|---|---|
|
||||
| `pf.ko` is built against the **Linux 7.3.4** tree and carries that kernel's `vermagic` | It does **not** load on the Debian 13 kernel (6.12). Do not try `insmod pf.ko` on 6.12: the `vermagic` differs and the load is refused. |
|
||||
| The module registers **netfilter** hooks in `init_net` (IPv4 and IPv6, 5 points each) | PF coexists with `nftables`/`iptables`; it does not replace the Debian firewall. |
|
||||
| PF runs in **one network namespace only** (`init_net`) | There is no per-netns PF instance. |
|
||||
| The OpenBSD `pfctl` talks to the module through the `/dev/pf` ioctl ABI | The `pfctl` in this tree is **OpenBSD 8.0** compiled for Linux, not Debian's. |
|
||||
|
||||
Three roles fit on one Debian 13 machine — and that is how the lab was
|
||||
validated:
|
||||
|
||||
| Role | What it does | Where |
|
||||
|---|---|---|
|
||||
| **build host** | builds the 7.3.4 kernel, `pf.ko` and the userland | `~/lab/linux_kernel/pf_port` |
|
||||
| **hypervisor** | hosts the 4 test VMs (libvirt/KVM) | same host, `libvirtd` |
|
||||
| **PF host** (optional) | runs PF on Debian 13 itself, after booting the 7.3.4 kernel | same host — see the warning in §9 |
|
||||
|
||||
---
|
||||
|
||||
## 1. Step 1 — prepare the host
|
||||
|
||||
```sh
|
||||
git clone <repo-url> ~/lab/linux_kernel/pf_port # or: cp -a /path/pf_port ~/lab/linux_kernel/
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
sudo ./scripts/debian13/prepare-host.sh
|
||||
```
|
||||
|
||||
The script is idempotent: it installs the packages and prints the toolchain
|
||||
state. Real output on Debian 13.7:
|
||||
|
||||
```
|
||||
== toolchain
|
||||
gcc 14
|
||||
make GNU Make 4.4.1
|
||||
bison bison (GNU Bison) 3.8.2
|
||||
flex flex 2.6.4
|
||||
bc bc 1.07.1
|
||||
rsync rsync version 3.5.0 protocol version 32
|
||||
libvirt 11.3.0
|
||||
qemu QEMU emulator version 10.0.13 (Debian 1:10.0.13+ds-0+deb13u1)
|
||||
geniso genisoimage 1.1.11 (Linux)
|
||||
|
||||
PREPARE_HOST_OK
|
||||
```
|
||||
|
||||
**About the compiler.** Debian 13 ships `gcc-14` as the default and has **no
|
||||
`gcc-15` in trixie** (`apt-cache policy gcc-15` → no candidate). The
|
||||
`docs/en/install.md` asks for "gcc ≥ 15" because the original development
|
||||
host is Fedora. On Debian 13 the build uses **gcc 14.2.0** — the 7.3.4 kernel
|
||||
and `pf.ko` compile without a patch (verified, §4).
|
||||
|
||||
To split the roles, use `--build-only` or `--lab-only`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Step 2 — get the sources
|
||||
|
||||
### 2.1 The 7.3.4 kernel tree
|
||||
|
||||
The repository does **not** ship the kernel: it expects the tree at
|
||||
`~/lab/linux_kernel/linux-7.3.4` (sibling of the repository). From zero:
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel
|
||||
curl -fLO https://cdn.kernel.org/pub/linux/kernel/v7.x/linux-7.3.4.tar.xz
|
||||
curl -fLO https://cdn.kernel.org/pub/linux/kernel/v7.x/sha256sums.asc
|
||||
sha256sum -c --ignore-missing sha256sums.asc # checks only the tarball you fetched
|
||||
tar xf linux-7.3.4.tar.xz
|
||||
```
|
||||
|
||||
The hash matches what kernel.org publishes:
|
||||
|
||||
```
|
||||
b11b6df8295e8e991ff040b71aaa4994a8b55caa23b6b092907f195b5840fd1f linux-7.3.4.tar.xz
|
||||
```
|
||||
|
||||
### 2.2 The OpenBSD 8.0 sources (PF itself)
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
./scripts/fetch-sources.sh # fetches sys.tar.gz + src.tar.gz, verifies sha256 (pins in VERSIONS)
|
||||
./scripts/vendorize.sh # extracts only the ported files -> _vendor/upstream + IDS.txt
|
||||
```
|
||||
|
||||
Wait for the `OK sys.tar.gz` and `OK src.tar.gz` lines. `fetch-sources.sh`
|
||||
tries the `openbsd.c3sl.ufpr.br` mirror first and falls back to
|
||||
`cdn.openbsd.org`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Step 3 — build the 7.3.4 kernel
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
KERNELDIR=~/lab/linux_kernel/linux-7.3.4 ./scripts/build-kernel.sh
|
||||
```
|
||||
|
||||
What the script does, in order:
|
||||
|
||||
1. `scripts/kernel-config.sh` — starts from `make defconfig` and enables
|
||||
`VIRTIO_BLK/PCI/NET=y`, `EXT4_FS=y`, `NETFILTER=y`, `NET_SCHED=y`,
|
||||
`INET=y`, `IPV6=y`, `SERIAL_8250(+CONSOLE)=y` (this is what lets the `pf0`
|
||||
VM boot the kernel directly, **with no initrd**) and runs
|
||||
`make olddefconfig`;
|
||||
2. `make -j$(nproc-2) bzImage modules_prepare` — compiles the kernel and
|
||||
prepares the tree for out-of-tree modules;
|
||||
3. copies `vmlinux.symvers` → `Module.symvers` (kbuild does not write the
|
||||
former) and makes sure `scripts/module.lds` exists;
|
||||
4. publishes into `out/`: `linux-7.3.4-bzImage`, `System.map`, `.config`,
|
||||
`kernelversion`, `bzImage.sha256`.
|
||||
|
||||
It ends with:
|
||||
|
||||
```
|
||||
KERNEL_BUILD_OK 7.3.4
|
||||
```
|
||||
|
||||
Reference time on the lab host (Debian 13, 12 threads): **~4 min** for the
|
||||
kernel build itself (`bzImage` + `modules_prepare`) on a tree that already
|
||||
carried objects, and the whole script — configure, build, publish the
|
||||
artifacts — in under 3 minutes. A tree straight from the tarball starts
|
||||
empty; expect the `make` step to dominate there.
|
||||
|
||||
---
|
||||
|
||||
## 4. Step 4 — build the `pf.ko` module
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
./scripts/build-module.sh # == make -C $KERNELDIR M=$PWD/module
|
||||
```
|
||||
|
||||
Output: `MODULE_BUILD_OK` and the artifact `module/pf.ko`.
|
||||
|
||||
**Check the `vermagic`** — it decides where the module can load:
|
||||
|
||||
```sh
|
||||
modinfo module/pf.ko | grep vermagic
|
||||
# vermagic: 7.3.4 SMP preempt mod_unload
|
||||
```
|
||||
|
||||
This is why kernel and module must come from the **same** tree: a `pf.ko`
|
||||
built against another 7.3.4 tree can have a subtly different `vermagic`
|
||||
(`SMP preempt mod_unload modversions` plus the build's `CONFIG_*`) and the
|
||||
load is refused.
|
||||
|
||||
### 4.1 Userspace ↔ kernel ABI check
|
||||
|
||||
`pfctl` talks to the kernel through shared structs. The `abitest` harness
|
||||
compares the layout on both sides:
|
||||
|
||||
```sh
|
||||
make -C tools abi # builds abitest (userspace) and abitest-module (kernel),
|
||||
# dumps both size/offset tables and diffs them
|
||||
```
|
||||
|
||||
No diff output = the ABI is intact.
|
||||
|
||||
---
|
||||
|
||||
## 5. Step 5 — build the userland
|
||||
|
||||
```sh
|
||||
make -C tools # -> tools/out/{pfctl,pdivert,pflogd} + abitest
|
||||
```
|
||||
|
||||
`pfctl` is produced **statically** (`-static`) so it can be copied into the
|
||||
Alpine VMs without dependencies. Offline check (needs no `/dev/pf`):
|
||||
|
||||
```sh
|
||||
(cd tools && ./out/pfctl -nf tests/01_basic.conf) # parse-only: no output = ok
|
||||
make -C tools test # runs every test .conf
|
||||
make -C tools abi # userspace vs kernel ABI tables
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.1 What the Debian 13 build produced (verified)
|
||||
|
||||
Everything below was built and run on Debian 13.7 with **gcc 14.2.0** — no
|
||||
patch, no backport:
|
||||
|
||||
```
|
||||
$ ./scripts/build-module.sh
|
||||
...
|
||||
MODULE_BUILD_OK
|
||||
$ modinfo module/pf.ko | grep vermagic
|
||||
vermagic: 7.3.4 SMP preempt mod_unload
|
||||
$ make -C tools test
|
||||
PASS tests/01_basic.conf (exit 0)
|
||||
PASS tests/02_translations.conf (exit 0)
|
||||
PASS tests/03_queues_scrub.conf (exit 0)
|
||||
PASS tests/broken.conf rejected (non-zero exit)
|
||||
$ make -C tools abi
|
||||
ABI OK: identical tables
|
||||
```
|
||||
|
||||
The `vermagic` printed by the Debian build is identical to the one the lab
|
||||
VM accepts. Verified end to end: the module built on Debian 13 was copied
|
||||
into the lab VM and loaded there —
|
||||
|
||||
```
|
||||
INSMOD_DEBIAN_MODULE_OK
|
||||
Status: Enabled
|
||||
crw------- 1 root root 10, 259 /dev/pf
|
||||
[ 119.057040] pfk: netfilter hooks registered (10, netisr wq data path)
|
||||
```
|
||||
|
||||
— as long as it was built from the same tree as the kernel the VM boots.
|
||||
|
||||
---
|
||||
|
||||
## 6. Step 6 — the libvirt lab on Debian 13
|
||||
|
||||
The lab is 4 Alpine VMs (`pf0` = the firewall under test, plus `cli`, `srv`,
|
||||
`gw2`), a DHCP management network and three isolated bridges
|
||||
`pf-lan`/`pf-wan`/`pf-wan2`. The topology lives in `lab/ips.env`.
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
./scripts/vm-create.sh --pf0-kernel=out/linux-7.3.4-bzImage
|
||||
```
|
||||
|
||||
The command is idempotent: it tears down and recreates the `pftest-*`
|
||||
domains, generates the cloud-init seeds, syncs the shared Alpine base image
|
||||
and starts everything. Without `--pf0-kernel=`, `pf0` boots the kernel from
|
||||
its own Alpine image — and then `pf.ko` **does not load** (vermagic). Always
|
||||
pass `--pf0-kernel=` when the intent is to test PF.
|
||||
|
||||
Deploy the artifacts into the VM:
|
||||
|
||||
```sh
|
||||
./scripts/vm-deploy.sh # build host -> deb ($DEPLOY_DIR) -> pf0:/opt/pf/
|
||||
```
|
||||
|
||||
Check the VM:
|
||||
|
||||
```sh
|
||||
ssh pf0 'uname -r; lsmod | grep -w pf; ls -l /opt/pf/'
|
||||
```
|
||||
|
||||
Expected: `7.3.4`, the `pf` module loaded, and `pf.ko`/`pfctl`/`pdivert`/
|
||||
`pflogd` in `/opt/pf/`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Step 7 — the 16-gate suite
|
||||
|
||||
```sh
|
||||
./scripts/vm-run-tests.sh # or: make test
|
||||
```
|
||||
|
||||
The runner restarts `pf0` before every gate (clean state), re-deploys the
|
||||
module and the tools, and runs the gate from the build host. Expected output:
|
||||
|
||||
```
|
||||
PASS=16 FAIL=0
|
||||
```
|
||||
|
||||
Per-gate logs land in `out/test-logs/<gate>.sh.log`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Step 8 — the stress test
|
||||
|
||||
The project had no performance gate (`docs/en/vm-lab.md` recorded that gap
|
||||
explicitly). The stress test is a new gate, `tests/vm/16-stress.sh`, which
|
||||
asks different questions from the functional gates: *"does the engine stay
|
||||
correct, bounded and leak-free while traffic, states, rules and tables
|
||||
churn?"*
|
||||
|
||||
```sh
|
||||
./scripts/stress/run-stress.sh # default profile
|
||||
./scripts/stress/run-stress.sh --quick # short profile (smoke)
|
||||
./scripts/stress/run-stress.sh --seconds 30 --connections 2000 --reloads 500
|
||||
```
|
||||
|
||||
Options: `--seconds`, `--parallel`, `--rate`, `--connections`, `--reloads`,
|
||||
`--rules`, `--table-entries`, `--max-overhead`. The runner resets `pf0`,
|
||||
deploys, runs the gate and writes `out/stress/<timestamp>/report.md`.
|
||||
|
||||
> **The traffic phases run at a bounded rate** (`--rate`, default 100 Mbit/s
|
||||
> per stream = 400 Mbit/s total). This is not a convenience: PF steals every
|
||||
> skb onto one ordered workqueue and runs the engine in process context, so the
|
||||
> backlog — and the memory it takes — grows with the offered rate. On the
|
||||
> 1 GB lab guest, 400 Mbit/s is stable and **~1 Gbit/s OOM-panics the
|
||||
> kernel** ("System is deadlocked on memory"). The stress test therefore
|
||||
> works in the regime the port survives and reports the ceiling separately
|
||||
> instead of killing the firewall under test. Details in
|
||||
> [`caveats.md` §13](caveats.md).
|
||||
|
||||
### 8.1 What each phase measures
|
||||
|
||||
| Phase | What it does | How it is judged |
|
||||
|---|---|---|
|
||||
| 0 — baseline | throughput `cli -> srv` at the bounded rate with the **module out of the path** (`rmmod pf`) | must be > 0 Mbit/s (otherwise the rest is meaningless) |
|
||||
| 1 — overhead | the same traffic with PF enabled and stateful rules | overhead % = (baseline − with PF) / baseline, against the limit (30% by default) — at the capped rate this says "PF sustains the offered rate" |
|
||||
| 2 — state churn | 300 concurrent TCP connections to a dedicated listener on the server | states **appear** in the table (`pfctl -s states`) and **vanish** after `pfctl -sr` → no leak |
|
||||
| 3 — rule churn | 200 reloads of a 200-rule ruleset | zero load failures, reload time measured **inside** the VM (min/avg/max), rule count stable |
|
||||
| 4 — table churn | 2000 entries in a `pfr` table | entries are gone after the flush → no table leak |
|
||||
| 5 — integrity | 2 MB crossing `nat-to` **while** a stream saturates the link | sha256 of the received file = sha256 of the source |
|
||||
| 6 — health | `dmesg`, PF counters, and a final ping | no `BUG/WARNING/Oops`; counters move; the firewall still routes |
|
||||
|
||||
### 8.2 Reading the report
|
||||
|
||||
A real run on the lab (full profile, `out/stress/<timestamp>/report.md`):
|
||||
|
||||
```
|
||||
STRESS phase=baseline baseline_mbit=400 seconds=10 parallel=4 rate_per_stream=100M
|
||||
STRESS phase=overhead pf_mbit=400 overhead_pct=0 limit_pct=30 rate_per_stream=100M
|
||||
STRESS phase=state_churn connections=300 states_before=0 states_created=300 states_after_reset=0 established_on_srv=214 rules_loaded=3 pf_status=Enabled
|
||||
STRESS phase=rule_churn reloads=200 rules_per_load=200 reload_fails=0 reload_ms_avg=11 reload_ms_max=20 rules_final=202
|
||||
STRESS phase=table_churn entries_requested=2000 entries_added=2000 add_errors=0 entries_after_flush=0
|
||||
STRESS phase=integrity bytes=2000000 sha256_match=yes
|
||||
STRESS phase=health dmesg_anomalies=0 match=5855 state_entries=7
|
||||
```
|
||||
|
||||
Reading it: PF sustains the capped 400 Mbit/s with **0% overhead** against the
|
||||
no-module baseline, tracks **300/300** concurrent flows as states and drains
|
||||
the table back to 0, reloads a 202-rule ruleset **200 times** with no failure
|
||||
(11 ms average, 20 ms worst), flushes **2000** table entries back to 0, moves
|
||||
2 MB through NAT byte-identically while a stream runs, and leaves no
|
||||
`BUG/WARNING/Oops` behind.
|
||||
|
||||
The runner prints `STRESS RESULT: PASS` or `FAIL` and exits with the gate's
|
||||
status.
|
||||
|
||||
> **Honesty note:** the throughput numbers come from a virtualized lab (KVM,
|
||||
> 2 vCPU per VM, `virtio` NICs bridged on the host). They are meant to
|
||||
> *compare* baseline against PF in the same environment, not to predict
|
||||
> production. The measured overhead includes the packet copy and PF's
|
||||
> software path — the price of a stateful filter.
|
||||
|
||||
---
|
||||
|
||||
## 9. Step 9 (optional) — running PF on Debian 13 itself
|
||||
|
||||
This is **not** required for the lab, and it has a cost: the lab host is also
|
||||
the hypervisor — rebooting into another kernel takes the VMs down.
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/linux-7.3.4
|
||||
sudo make modules_install # pf.ko -> /lib/modules/7.3.4/
|
||||
sudo cp arch/x86/boot/bzImage /boot/vmlinuz-7.3.4
|
||||
sudo update-initramfs -u -k 7.3.4 # or: update-grub
|
||||
sudo reboot # ⚠ takes the lab VMs down
|
||||
```
|
||||
|
||||
After the boot (with 7.3.4 active):
|
||||
|
||||
```sh
|
||||
uname -r # 7.3.4
|
||||
sudo insmod /lib/modules/7.3.4/pf.ko # creates /dev/pf (0600) and registers the hooks
|
||||
ls -l /dev/pf
|
||||
sudo cp ~/lab/linux_kernel/pf_port/tools/out/pfctl /usr/local/sbin/
|
||||
sudo pfctl -e
|
||||
sudo pfctl -f /etc/pf.conf
|
||||
sudo pfctl -s info
|
||||
```
|
||||
|
||||
A minimal `/etc/pf.conf` (OpenBSD 8.0 syntax):
|
||||
|
||||
```
|
||||
set skip on lo
|
||||
block return
|
||||
pass on egress
|
||||
```
|
||||
|
||||
To keep PF up across reboots, a simple unit:
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/pf.service
|
||||
[Unit]
|
||||
Description=PF-on-Linux engine
|
||||
After=network-pre.target
|
||||
Before=multi-user.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
RemainAfterExit=yes
|
||||
ExecStart=/sbin/modprobe pf
|
||||
ExecStart=/usr/local/sbin/pfctl -e
|
||||
ExecStop=/usr/local/sbin/pfctl -d
|
||||
ExecStop=/sbin/modprobe -r pf
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
And `pflogd` (writes a `DLT_PFLOG` pcap with the OpenBSD `pflog(4)` record
|
||||
layout):
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/pflogd.service
|
||||
[Unit]
|
||||
Description=PF log daemon
|
||||
After=pf.service
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/sbin/pflogd /var/log/pf/pflog.pcap
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
> `pflogd` reads `/dev/pflog` (created by the module, 0600). This `pfctl`
|
||||
> has **no** `-s pflog` modifier: logging is turned on per rule with the
|
||||
> OpenBSD keyword (`pass log on egress ...`, `block log ...`). The on-disk
|
||||
> pcap lives wherever you point `pflogd`.
|
||||
|
||||
---
|
||||
|
||||
## 10. Verification checklist
|
||||
|
||||
```sh
|
||||
# 1. module loaded and device created
|
||||
lsmod | grep -w pf && ls -l /dev/pf
|
||||
|
||||
# 2. PF enabled
|
||||
pfctl -s info | head -2 # Status: Enabled
|
||||
|
||||
# 3. the OpenBSD 8.0 parser in the Debian binary
|
||||
pfctl -nf /etc/pf.conf
|
||||
|
||||
# 4. hooks registered
|
||||
dmesg | grep pfk # "pfk: netfilter hooks registered (10, netisr wq data path)"
|
||||
|
||||
# 5. the firewall really filters
|
||||
pfctl -sr; pfctl -s states
|
||||
|
||||
# 6. the full suite
|
||||
./scripts/vm-run-tests.sh # PASS=16 FAIL=0
|
||||
|
||||
# 7. stress
|
||||
./scripts/stress/run-stress.sh # STRESS RESULT: PASS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Troubleshooting
|
||||
|
||||
| Symptom | Cause | Action |
|
||||
|---|---|---|
|
||||
| `insmod: ERROR: could not insert 'pf.ko': Invalid module format` | `vermagic` differs from the running kernel | kernel and module must come from the **same** tree; rebuild both |
|
||||
| `insmod` fails on the Debian kernel (6.12) | the module targets 7.3.4 | boot the 7.3.4 kernel (§9) or test inside the lab VM |
|
||||
| `pfctl: Permission denied` | `/dev/pf` is 0600 root | run as root |
|
||||
| `pfctl: Device not configured` | module loaded but `pfctl -e` never ran | `sudo pfctl -e` |
|
||||
| `virsh: cannot connect to qemu:///system` | libvirt is down | `sudo systemctl enable --now libvirtd` |
|
||||
| `Cannot find device 'eth2'` | interface names changed | resolve with `ip route get <ip> \| grep -o 'dev [a-z0-9]*'` (gate 15 does this) |
|
||||
| a gate fails right after the deploy | `pf.ko` was not copied | the runner checks `test -s /opt/pf/pf.ko`; see `out/test-logs/<gate>.sh.log` |
|
||||
| stress: `baseline throughput unavailable` | `iperf3` is not running on the server | `srv 'pkill -x iperf3; iperf3 -s -D'` and check `netstat -lnt \| grep 5201` |
|
||||
| stress: `state churn` fails | the guest's `bash` has no `/dev/tcp` | the gate falls back to `nc`; check `bash --version` in the VM |
|
||||
| the guest reboots during a stress run | the offered rate exhausted the guest's memory (workqueue backlog) | lower `--rate`; see [caveats.md §13](caveats.md) — the ceiling measured on the lab is ~1 Gbit/s on a 1 GB guest |
|
||||
| `gcc-15` not found | it does not exist in trixie | use the default gcc 14 (§1) |
|
||||
|
||||
---
|
||||
|
||||
## 12. Known limits (read before using this in production)
|
||||
|
||||
- This port is **not** OpenBSD PF: the deviations are documented in
|
||||
[`docs/en/caveats.md`](caveats.md) and
|
||||
[`docs/en/feature-matrix.md`](feature-matrix.md).
|
||||
- No `pfsync`/CARP, IPsec/pfkey, `ftp-proxy`, per-netns PF, and none of the
|
||||
`cbq`/`wfq`/`red` schedulers (removed upstream before OpenBSD 8.0).
|
||||
- PF registers netfilter hooks in `init_net` — on a host that already runs
|
||||
`nftables`, traffic traverses both. PF's `bypass` only applies to traffic
|
||||
entering through PF's own hook.
|
||||
- IPv6, OS fingerprinting, `set state-policy`/`allow-opts` and syncookies
|
||||
compile but are **not** covered by a gate (known gap, §5 of
|
||||
[`docs/en/vm-lab.md`](vm-lab.md)).
|
||||
|
||||
---
|
||||
|
||||
## 13. References
|
||||
|
||||
| Document | Contents |
|
||||
|---|---|
|
||||
| [`docs/en/install.md`](install.md) | the generic build recipe (without the Debian walk-through) |
|
||||
| [`docs/en/vm-lab.md`](vm-lab.md) | the lab, topology and gates |
|
||||
| [`docs/en/feature-matrix.md`](feature-matrix.md) | what is verified and what is not |
|
||||
| [`docs/en/caveats.md`](caveats.md) | known deviations from OpenBSD 8.0 |
|
||||
| [`docs/en/pf-guide.md`](pf-guide.md) | day-to-day rulesets and warnings |
|
||||
| Portuguese version | [`docs/pt-BR/debian13.md`](../pt-BR/debian13.md) |
|
||||
@@ -0,0 +1,83 @@
|
||||
# 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)); the gate that proves it is named.
|
||||
- **VERIFIED-offline** — proven by a fixture/ABI test, not by traffic (e.g. `make -C tools test`).
|
||||
- **COMPILES-untested** — built into `pf.ko`/`pfctl`; no gate has exercised it.
|
||||
- **NOT-ENABLED** — the code exists but the feature is off in this build (e.g. `af-to`, which needs the `INET6` paths).
|
||||
- **OUT-OF-SCOPE** — non-goal by design (spec §3).
|
||||
|
||||
As of 2026-11-12; source of per-row evidence: `out/test-logs/`,
|
||||
`docs/porting-notes.md`, milestone commits, and the screencasts
|
||||
([screencast.md](screencast.md)) for the visible proof.
|
||||
|
||||
The suite is **16/16 green** (`./scripts/vm-run-tests.sh`).
|
||||
|
||||
## Control plane & tools
|
||||
|
||||
| Feature | Upstream syntax | Milestone | Status |
|
||||
|---|---|---|---|
|
||||
| Module load, `/dev/pf` (0600) | `insmod pf.ko` | M1 | VERIFIED-in-VM (gate `02-ativacao.sh`) |
|
||||
| Enable/disable | `pfctl -e`, `pfctl -d` | M1 | VERIFIED-in-VM |
|
||||
| Ruleset load | `pfctl -f file` | M2 | VERIFIED-in-VM (every gate loads a real ruleset) |
|
||||
| Parse-only check | `pfctl -n -f file` | M1 | VERIFIED-offline (`make -C tools test`) |
|
||||
| Status/counters | `pfctl -s info [-v]` | M1 | VERIFIED-in-VM |
|
||||
| Rules listing | `pfctl -s rules [-v]`, `pfctl -sr` | M2 | VERIFIED-in-VM (gates 02–06) |
|
||||
| States listing | `pfctl -s states [-v]`, `pfctl -ss` | M2 | VERIFIED-in-VM (gate `01-state.sh`) |
|
||||
| Tables listing/ops | `pfctl -s tables`, `-t t -T show/add/del/kill` | M2 | VERIFIED-in-VM (gate `03-tables.sh`, incl. a live `-T delete` unblocking the flow) |
|
||||
| Anchors | `pfctl -a anchor -f file`, `-s anchors` | M2 | VERIFIED-in-VM (gate `04-anchors.sh`) |
|
||||
| Queue listing | `pfctl -s queue -v` | M5 | VERIFIED-in-VM (gate `15-queue.sh`: both classes with statistics) |
|
||||
| ioctl ABI parity | `make -C tools abi` (abitest tables) | M1 | VERIFIED-offline (userland table); the 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 | VERIFIED-in-VM (gate `01-state.sh`: transit ping through the firewall) |
|
||||
| `block drop` | `block drop in quick …` | M2 | VERIFIED-in-VM (gate `02-block.sh`: ping dies, counters prove it) |
|
||||
| `block return` / `return-rst` / `return-rst after quarter` | `block return-rst in quick proto tcp …` | M2 | VERIFIED-in-VM (gate `02-block.sh`: the client's `nc` gets an RST) |
|
||||
| `keep state` (icmp/tcp/udp), state table, purger | `… keep state` | M2 | VERIFIED-in-VM (gate `01-state.sh`; state visible in `pfctl -ss`) |
|
||||
| `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 | VERIFIED-in-VM (gate `03-tables.sh`) |
|
||||
| Anchors + include + quick precedence | `anchor "x"`, `load anchor …` | M2 | VERIFIED-in-VM (gate `04-anchors.sh`) |
|
||||
| IPv6 for all of the above | same syntax, v6 | M2+ | COMPILES-untested — the engine is v6-complete by construction, but the v6 path is not exercised by a gate |
|
||||
| Non-IPv4/IPv6 traffic (ARP…) | — | M2 | PFLINUX by construction: netfilter IPv4/IPv6 hooks only — ARP never enters the PF path (no gate) |
|
||||
|
||||
## 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-VM** — gate `05-nat.sh`: source NAT works end to end (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`). |
|
||||
| `rdr-to` | `pass in … to <fw> port 8080 rdr-to <srv> port 80 keep state` | M3 | **VERIFIED-in-VM** — 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` | `pass quick proto icmp from 10.0.2.20 to 10.0.1.10 binat-to 10.0.2.50 keep state` | M3 | **VERIFIED-in-VM** — gate `07-binat.sh`. pfctl expands one `binat-to` rule into the documented pair (`pass out … nat-to <mapped> static-port` + `pass in … rdr-to <real>`), and both halves work: the peer sees the mapped address, the original never leaks, and the reply is translated back. |
|
||||
| NAT pools (`round-robin`, `source-hash`) | `nat-to { 10.0.2.1, 10.0.3.1 } round-robin` | M4 | **VERIFIED-in-VM** — gate `10-pools.sh`, and visible in the screencast: round-robin alternates the source address between the members (3 packets each), source-hash keeps one origin on one member. |
|
||||
| Scrub/normalize: reassembly, `fragment drop-overlap`, `min-ttl`, `max-mss`, `df`/`no-df`, `random-id`, `set reassemble yes` | `match in all scrub (min-ttl 100 max-mss 500)` | M3 | **VERIFIED-in-VM** — gate `09-scrub.sh`: `min-ttl` raises the TTL (egress shows 99 after the forward decrement) and `max-mss` clamps a SYN's MSS option, both measured on the firewall's own egress. Reassembly/overlap paths are compiled and reached but not gated. |
|
||||
| OS fingerprinting in states | `pass … set os A` + `/etc/pf.os` | bonus | COMPILES-untested (`pf_osfp.c` compiled; no fingerprint packaging yet — a missing `/etc/pf.os` is tolerated) |
|
||||
|
||||
## Routing / divert / queues / logging
|
||||
|
||||
| Feature | Upstream syntax | Milestone | Status |
|
||||
|---|---|---|---|
|
||||
| `route-to` / `dup-to` / `reply-to` | `pass in … route-to { 10.0.3.2 } keep state`, `reply-to { gw }` | M4 | **VERIFIED-in-VM** — gates `08-routeto.sh` (route-to leaves via the gateway's link, dup-to copies while keeping the flow) and `13-replyto.sh` (the reply of a flow is forced onto the gateway link instead of the client's). Deviation: the forced nexthop is installed by setting `rt_gw4`/`rt_gw_family` on the looked-up route (Linux only ARPs the gateway when the route declares one). `fail-to` is **not a keyword in OpenBSD 8.0** (removed upstream), so it is out of scope. |
|
||||
| `divert-to` / `divert` tag | `pass in … divert-to <host> port <n>` | M4 | **VERIFIED-in-VM** — gate `11-divert.sh`. 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 (`queue`, `queue on`, `pfctl -s queue -v`) | `queue rootq on eth2 bandwidth 10Mbit` + `queue leafq on eth2 bandwidth 2Mbit parent rootq default` | M5 | **VERIFIED-in-VM** — gate `15-queue.sh`: the queue config loads, the hfsc discipline attaches to the interface, `pfctl -s queue -v` lists both classes with statistics, a 2 MB queued flow completes, and the class's packet counter advances (the scheduler is in the data path). Note `bandwidth` is HFSC *linkshare* — a guarantee under contention, not a cap: OpenBSD 8.0's pf.conf has no `minimum`/`maximum`, so a lone flow is not rate-limited, on Linux or on OpenBSD. |
|
||||
| HFSC | `queue on wan { hfsc … }` | M5 | **VERIFIED-in-VM** — `pfsrc/hfsc.c` (real OpenBSD 8.0 code) is in the module object list and is the discipline the gate exercises. The class handles use the vendored `net/hfsc.h` (root class `0x10000`, default class `0x1000`) shared with `pfctl`, so the stats ABI matches on both sides. |
|
||||
| FQ-CoDel | `queue on wan { fq_codel … }` | M5 | COMPILES-untested — `pfsrc/fq_codel.c` is built into `pf.ko` and the vendored `net/fq_codel.h` is shared with `pfctl`, but no gate drives it. |
|
||||
| `pfq` interface | n/a (BSD `ifq`/`pfq` interface, not a Linux `tc` qdisc) | M5 | **VERIFIED-in-VM** — the port keeps the BSD shape: `compat/pfk_ifq.c` implements the `ifq_ops`/`pfq_ops` interfaces and the OpenBSD back ends plug into them (`pfq` is not a Linux `tc` qdisc and never was meant to be). priq is the default discipline. |
|
||||
| pflog (`log`, `log all`, `block log`) + `pflogd` pcap (DLT_PFLOG) | `pass out quick log` + `pflogd /tmp/x.pcap` | M4 | **VERIFIED-in-VM** — 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 |
|
||||
| `af-to` (IPv4↔IPv6 translation) | the code sits under `#ifdef INET6` and this build has `INET6 0`; enabling it is a separate milestone, not a missing feature in the base |
|
||||
@@ -0,0 +1,109 @@
|
||||
# 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, `screencast/` (video pipeline) |
|
||||
| `tests/vm/` | VM suite: 16 gates `01-state.sh … 16-stress.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 the OpenBSD 8.0 `queue`/`queue on` syntax and the
|
||||
kernel side implements it in the BSD shape: `compat/pfk_ifq.c` provides the
|
||||
`ifq_ops`/`pfq_ops` interfaces and the OpenBSD back ends (`pfsrc/hfsc.c`,
|
||||
`pfsrc/fq_codel.c`) plug into them; **priq** is the default discipline.
|
||||
Gate `15-queue.sh` proves the **hfsc** discipline end to end: the queue
|
||||
config loads, the discipline attaches to the interface, `pfctl -s queue -v`
|
||||
lists both classes with statistics, a 2 MB queued flow completes and the
|
||||
class's packet counter advances. The class handles and the stats structs
|
||||
come from OpenBSD's own `net/hfsc.h`/`net/fq_codel.h`, vendored so the
|
||||
kernel and `pfctl` cannot drift apart.
|
||||
- **Divert**: `divert-to`/`divert` tag evaluate to PF's `PF_DIVERT` verdict
|
||||
and the module registers an `AF_DIVERT` socket family (`PF_DIVERT=32`) at
|
||||
runtime — no kernel-tree patch. With no listener the packet is dropped
|
||||
(`divs_noport`, BSD parity); with the `pdivert` relay running the packet is
|
||||
delivered to userspace, rewritten and reinjected. Gate `11-divert.sh`.
|
||||
- **pflog**: the engine queues logged packets, `pfsrc/pfk_pflog.c` exposes
|
||||
them through `/dev/pflog`, and `tools/pflogd` writes a DLT_PFLOG pcap whose
|
||||
record layout is byte-compatible with OpenBSD `pflog(4)`. Gate
|
||||
`12-pflog.sh`. The deviation from upstream is the transport (a chardev
|
||||
instead of an `if_pflog`/bpf interface), not the format.
|
||||
|
||||
## Milestones (see feature-matrix.md for per-feature status)
|
||||
|
||||
| Milestone | Scope | Status |
|
||||
|---|---|---|
|
||||
| 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 | **done** — gates 01–04 green |
|
||||
| M3 | NAT (`nat-to`/`rdr-to`/`binat-to`), scrub, pflog | **done** — gates 05/06/07/09 (incl. 2 MB integrity through a redirect) and pflog gate 12 |
|
||||
| M4 | route-to/dup-to/reply-to, pools, divert e2e | **done** — gates 08/10/13 and divert gate 11 |
|
||||
| M5 | queues: ifq back ends (hfsc/fq_codel) | **done (mechanical)** — gate 15: hfsc attaches, `pfctl -s queue -v` reports class stats, a 2 MB queued flow is counted by the class. `bandwidth` = HFSC linkshare (a guarantee under contention, not a cap) |
|
||||
| M6 | docs complete, patchset tidy, full suite green, tagged releases | **done** — docs EN+PT-BR, 16/16 suite green, tagged (`v1.0.0`) |
|
||||
|
||||
## Next reads
|
||||
|
||||
[build.md](build.md) → [vm-lab.md](vm-lab.md) → [pf-guide.md](pf-guide.md) →
|
||||
[feature-matrix.md](feature-matrix.md) → [screencast.md](screencast.md) →
|
||||
[caveats.md](caveats.md).
|
||||
@@ -74,3 +74,45 @@ 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
|
||||
adds a documented `patches/kernel/000N-*.patch` (all such patches: one
|
||||
section each in docs/en/patches.md with what/why/impact/revert).
|
||||
|
||||
## 6. Notes on the steps above (2026-11-12)
|
||||
|
||||
- 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 every userland tool: `make -C tools` targets are `pfctl`,
|
||||
`pdivert`, `pflogd` and the ABI harness (`abitest`, `abi`, `test`, `clean`).
|
||||
- After 2.5, the whole feature set is usable and gated by the lab suite —
|
||||
filtering with state, tables and anchors, NAT (`nat-to`/`rdr-to`/`binat-to`
|
||||
plus pools), scrub, forced routing (`route-to`/`dup-to`/`reply-to`),
|
||||
`divert`, `pflog` and the OpenBSD 8.0 queues (HFSC). The
|
||||
[feature matrix](feature-matrix.md) says which gate proves what; read
|
||||
[pf-guide.md](pf-guide.md) for the deviations before enabling PF on a path
|
||||
you need.
|
||||
|
||||
## 6.1 Optional: the narrated screencasts
|
||||
|
||||
```sh
|
||||
export MINIMAX_API_KEY=... # MiniMax TTS for the narration
|
||||
./scripts/vm-create.sh # the lab must be up
|
||||
./scripts/screencast/build-all.sh # -> out/screencast/{en,pt}/*.mp4
|
||||
```
|
||||
|
||||
It records real shell sessions against the lab, generates the narration with
|
||||
a MiniMax female voice (English and Portuguese) and renders 1080p30 MP4s
|
||||
with burned-in subtitles and the lab's network diagram. Details:
|
||||
[screencast.md](screencast.md).
|
||||
|
||||
## 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) |
|
||||
| Narrated screencasts | [screencast.md](screencast.md) |
|
||||
| Doc index | [README.md](README.md) |
|
||||
@@ -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: `scripts/apply-patches.sh`, `scripts/unpatch.sh` and
|
||||
> `patches/kernel/series` **are in the tree** and are exercised by
|
||||
> `make test`-adjacent scripts; the series is empty by design, so applying it
|
||||
> is a verified no-op (`PATCHES_APPLIED=0`). When a real patch is needed, the
|
||||
> commit that adds it MUST also extend the series file and the 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. |
|
||||
@@ -0,0 +1,107 @@
|
||||
# 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): the filtering core (pass/block/quick/
|
||||
keep state/tables/anchors), the NAT family, scrub, forced routing, pools,
|
||||
`divert`, `pflog` and the OpenBSD 8.0 queues all have **VM evidence** behind
|
||||
them — 16/16 lab gates are green. What is *not* gate-verified is listed
|
||||
explicitly below. 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 lab 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. 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 in the lab: 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.
|
||||
|
||||
**Not gate-verified** (honest gaps): the IPv6 path, OS fingerprinting, the
|
||||
`set` options above, syncookies and the FQ-CoDel discipline. `af-to` is
|
||||
compiled out in this build (`INET6 0`).
|
||||
|
||||
## Feature notes — what each syntax does today
|
||||
|
||||
| Syntax | Until | What happens today |
|
||||
|---|---|---|
|
||||
| `nat-to`, `rdr-to`, `binat-to` | — | **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. `binat-to` is expanded by pfctl into a `nat-to … static-port` + `rdr-to` pair (gate `07-binat`). |
|
||||
| `scrub (min-ttl, max-mss, df, random-id)`, `set reassemble` | — | **Verified in the lab** (gate `09-scrub.sh`): `min-ttl` and `max-mss` measurably rewrite transit packets. |
|
||||
| `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`, `reply-to` | — | **Verified in the lab** (gates `08-routeto.sh`, `13-replyto.sh`): the forced gateway is used instead of the normal egress, `dup-to` copies while keeping the flow, and `reply-to` pushes a flow's answers out through the gateway link. `fail-to` is not a keyword in OpenBSD 8.0 (removed upstream). |
|
||||
| `queue` / `queue on` / `pfctl -s queue` | — | **Verified in the lab** (gate `15-queue.sh`): queues load, hfsc attaches, `pfctl -s queue -v` reports class statistics and a queued 2 MB flow is counted by the class. `bandwidth` is a *guarantee under contention*, not a cap - 8.0's pf.conf has no upperlimit keyword. |
|
||||
| `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).
|
||||
@@ -0,0 +1,123 @@
|
||||
# Screencasts / Videos da demonstracao
|
||||
|
||||
> PT-BR: [docs/pt-BR/screencast.md](../pt-BR/screencast.md) · EN: this page
|
||||
|
||||
Sete videos por idioma, com **narracao com voz feminina** (MiniMax),
|
||||
**legendas queimadas**, **diagrama de rede do lab** e um **filme completo**
|
||||
com transicoes entre as fases. 1920x1080 @ 30fps, H.264/MP4 + AAC — prontos
|
||||
para subir no YouTube.
|
||||
|
||||
Cada video e a gravacao de uma **sessao shell real**: uma conexao SSH de
|
||||
verdade ao firewall Alpine, com os comandos digitados tecla a tecla e a saida
|
||||
do kernel chegando em tempo real. Nada e simulado.
|
||||
|
||||
## As fases
|
||||
|
||||
| # | Video | O que mostra |
|
||||
|---|-------|--------------|
|
||||
| 0 | `00-ambiente.mp4` | O lab: 4 VMs Alpine sob libvirt, as quatro interfaces do firewall, e o diagrama de rede completo |
|
||||
| 1 | `01-implementacao.mp4` | A implementacao no kernel: fontes do OpenBSD 8.0 + camada de compatibilidade = `pf.ko` |
|
||||
| 2 | `02-ativacao.mp4` | `insmod pf.ko`, `/dev/pf`, `pfctl -e`, `pfctl -s info` |
|
||||
| 3 | `03-regras.mp4` | Regras basicas: tabela, anchor, `keep state`, `block drop` (o ping morre) |
|
||||
| 4 | `04-roteamento.mp4` | `route-to` e `reply-to`, com o diagrama mostrando o caminho real do pacote |
|
||||
| 5 | `05-balanceamento.mp4` | Pool `round-robin`, pool `source-hash` e `dup-to` |
|
||||
| 6 | `06-qos.mp4` | Filas `hfsc` do OpenBSD 8.0 e uma transferencia de 2 MB pela classe |
|
||||
|
||||
Mais `pf-on-linux-full.mp4`: o filme completo, com as sete fases emendadas por
|
||||
transicoes (crossfade sobre um cartao de capitulo).
|
||||
|
||||
## Vozes MiniMax
|
||||
|
||||
| Idioma | Voz | Id |
|
||||
|--------|-----|-----|
|
||||
| Ingles (en_US) | Confident Woman | `English_ConfidentWoman` |
|
||||
| Portugues (pt_BR) | Confident Woman | `Portuguese_ConfidentWoman` |
|
||||
|
||||
A audio e gerada pelo MiniMax TTS, **um arquivo por segmento** de fala. Como
|
||||
cada segmento corresponde a uma batida da sessao, a voz comeca exatamente
|
||||
quando a acao correspondente aparece na tela.
|
||||
|
||||
## Como regravar
|
||||
|
||||
```sh
|
||||
# tudo: audio -> sessoes -> videos -> filme completo
|
||||
./scripts/screencast/build-all.sh
|
||||
|
||||
# uma fase so
|
||||
./scripts/screencast/build-all.sh 04-roteamento
|
||||
```
|
||||
|
||||
Etapas individuais:
|
||||
|
||||
```sh
|
||||
python3 scripts/screencast/make_audio.py --lang pt # audio MiniMax
|
||||
python3 scripts/screencast/record.py --plan scripts/screencast/plans/04-roteamento.json \\
|
||||
--out out/screencast/caps/04-roteamento.cast --pace --ensure-pf
|
||||
python3 scripts/screencast/assemble.py --phase 04-roteamento --lang pt
|
||||
python3 scripts/screencast/join.py --lang pt
|
||||
```
|
||||
|
||||
### Como o pipeline funciona
|
||||
|
||||
```
|
||||
planos/*.json --record.py--> caps/*.cast --render_video.py--> video mudo
|
||||
(comandos) (pty real) (asciicast) (pyte + PIL) |
|
||||
|
|
||||
narracao/*.json --make_audio.py--> vo/<fase>.<lang>/*.mp3 ----------+
|
||||
(MiniMax TTS) |
|
||||
assemble.py: mix + legendas
|
||||
|
|
||||
join.py: transicoes
|
||||
```
|
||||
|
||||
Pontos que importam:
|
||||
|
||||
* **Sessao real.** `record.py` abre um pty, faz SSH na VM e digita os comandos
|
||||
um caractere por vez (~34 c/s, com jitter). O `bash --noediting` evita que o
|
||||
editor de linha redesenhe o comando e o tty o repita.
|
||||
* **Pacing.** A gravacao segura a tela enquanto a voz fala: cada batida dura
|
||||
no maximo o trecho de audio que a acompanha (o maior entre EN e PT), para
|
||||
uma unica captura servir as duas versoes.
|
||||
* **Legendas.** O texto da narracao e queimado no video, na lingua da trilha.
|
||||
* **Diagrama.** Nas fases 0, 4 e 5 o mapa do lab e desenhado sobre o
|
||||
terminal, e o caminho em discussao fica destacado (eth1/eth2/eth3).
|
||||
|
||||
Requisitos: `ffmpeg`, `python3` com `PIL` e `pyte`, a fonte DejaVu, a chave
|
||||
`MINIMAX_API_KEY` no ambiente, e o lab de VMs no ar.
|
||||
|
||||
## Onde ficam os arquivos
|
||||
|
||||
| Caminho | Conteudo |
|
||||
|---------|----------|
|
||||
| `out/screencast/en/`, `out/screencast/pt/` | os videos finais |
|
||||
| `out/screencast/caps/` | as capturas asciicast das sessoes |
|
||||
| `out/screencast/vo/` | o audio gerado pelo MiniMax |
|
||||
| `scripts/screencast/plans/` | o roteiro de comandos de cada fase |
|
||||
| `scripts/screencast/narration/` | os textos da narracao (EN e PT) |
|
||||
|
||||
## Texto de descricao (YouTube)
|
||||
|
||||
```
|
||||
PF on Linux - o motor do OpenBSD PF 8.0 dentro do kernel Linux
|
||||
|
||||
Port completo do Packet Filter do OpenBSD 8.0 para o kernel Linux 7.3.4,
|
||||
empacotado como modulo (pf.ko) e controlado pelo pfctl original do OpenBSD
|
||||
sobre a ABI de ioctls do /dev/pf.
|
||||
|
||||
O lab e real: 4 VMs Alpine sob libvirt, kernel compilado do fonte com o
|
||||
modulo, trafego real entre cliente, firewall e servidor.
|
||||
|
||||
Fases:
|
||||
0. O ambiente de testes - as 4 VMs e o diagrama de rede
|
||||
1. Implementacao no kernel - das fontes OpenBSD ao pf.ko
|
||||
2. Ativacao - insmod, /dev/pf, pfctl -e, pfctl -s info
|
||||
3. Regras basicas - tabelas, anchors, keep state, block drop
|
||||
4. Roteamento - route-to e reply-to, com o caminho real no diagrama
|
||||
5. Balanceamento - pools round-robin, source-hash e dup-to
|
||||
6. QOS - filas hfsc do OpenBSD 8.0 no caminho de dados
|
||||
|
||||
Suite automatizada: 15 gates, todos verdes.
|
||||
Codigo e documentacao: https://git.labexposed.com/lgcosta/pf-linux-port
|
||||
|
||||
#linux #kernel #openbsd #pf #firewall #netfilter #screencast
|
||||
```
|
||||
@@ -0,0 +1,163 @@
|
||||
# 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 through M0–M6; the full
|
||||
suite is green (§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`.
|
||||
|
||||
**From pf0 to the other VMs.** The firewall has its own keypair and the
|
||||
peers trust it, so a session on pf0 can drive the client and the server
|
||||
directly — this is what the screencasts do (`ssh cli 'ping …'`):
|
||||
|
||||
```sh
|
||||
# once per lab, from the hypervisor
|
||||
ssh pf0 'ssh-keygen -t ed25519 -N "" -C pf0 -f /root/.ssh/id_ed25519'
|
||||
# then authorize that public key on cli, srv and gw2
|
||||
```
|
||||
|
||||
`/root/.ssh/config` on pf0 maps the short names `cli`, `srv` and `gw2` to
|
||||
10.0.1.10, 10.0.2.20 and 10.0.3.2, and `/etc/hosts` carries the same
|
||||
mapping.
|
||||
|
||||
## 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
|
||||
|
||||
Every gate asserts **real traffic and observable state**, never just an exit
|
||||
code: the packet either arrives, is dropped, or is translated, and the proof
|
||||
is read back from the firewall's own counters, state table, capture files or
|
||||
peer.
|
||||
|
||||
The full list is in §6 (16 gates, all green). Each gate is a shell script in
|
||||
`tests/vm/` that talks to the VMs through deb with nested ssh, using the
|
||||
helpers in `tests/vm/lib.sh` (`pf0`, `cli`, `srv`, `gw2`, `pfput`, `pfload`,
|
||||
`ok`, `bad`). `scripts/vm-run-tests.sh` runs them in order and captures
|
||||
`out/test-logs/<gate>.sh.log`.
|
||||
|
||||
Not gated (honest gaps): the IPv6 path, OS fingerprinting, `set` options
|
||||
(`state-policy`, `allow-opts`) and syncookies — the code is compiled into
|
||||
`pf.ko` but no gate drives it. FQ-CoDel compiles and shares its stats header
|
||||
with `pfctl`, but only the **hfsc** discipline is exercised.
|
||||
|
||||
There is **no numeric performance gate**: the design decision (spec §7) is
|
||||
that *functional gates are the bar* — a perf contract would force a
|
||||
non-faithful rewrite-first shim. What exists instead is a **stress test**
|
||||
(`tests/vm/16-stress.sh`, driven by `scripts/stress/run-stress.sh`) that
|
||||
asserts *invariants under load* — no state/table leak, no rule-load failure,
|
||||
byte-identical payload under a saturating stream, no `BUG/WARNING/Oops`, the
|
||||
firewall still routing — and **reports** the throughput comparison
|
||||
(baseline without the module vs. with PF enabled) as information, without a
|
||||
numeric pass/fail target. Report and raw log land in
|
||||
`out/stress/<timestamp>/`.
|
||||
|
||||
## 6. Current suite status (2026-11-12)
|
||||
|
||||
**16/16 gates green.** A full clean run (`./scripts/vm-run-tests.sh`, ~13 min)
|
||||
recreates and reboots `pftest-pf0` before every gate, redeploys the module
|
||||
and the tools, and ends with `PASS=16 FAIL=0`. The captured logs live in
|
||||
`out/test-logs/<gate>.sh.log`.
|
||||
|
||||
| Gate | What it proves now |
|
||||
|---|---|
|
||||
| `01-state.sh` | `keep state` across a transit ping; the state shows up in `pfctl -ss` |
|
||||
| `02-block.sh` | `block drop` kills the ping; `block return-rst` gets the client an RST |
|
||||
| `03-tables.sh` | a `pfr` table blocks a host; a live `-T delete` unblocks the same flow |
|
||||
| `04-anchors.sh` | an anchor rule is evaluated before a later main-ruleset `block` |
|
||||
| `05-nat.sh` | source NAT: the packet leaves with the pool address, the reply is de-NATed |
|
||||
| `06-rdr.sh` | port redirect end to end, plus 2 MB through it with byte-for-byte integrity |
|
||||
| `07-binat.sh` | `binat-to`: the peer sees the mapped address, the original never leaks |
|
||||
| `08-routeto.sh` | `route-to` leaves via the gateway's link; `dup-to` copies and keeps the flow |
|
||||
| `09-scrub.sh` | `min-ttl` and `max-mss` measured on the firewall's own egress |
|
||||
| `10-pools.sh` | NAT pool selection (`round-robin`, `source-hash`) |
|
||||
| `11-divert.sh` | `divert-to` to the `pdivert` relay: packet to userspace and back |
|
||||
| `12-pflog.sh` | logged packets reach `/dev/pflog` and land in a DLT_PFLOG pcap |
|
||||
| `13-replyto.sh` | `reply-to` forces the reply onto the gateway link |
|
||||
| `14-soak.sh` | ruleset reload under traffic, `rmmod` cycle, leak check |
|
||||
| `15-queue.sh` | hfsc queues: attach, class statistics, a 2 MB queued flow counted by the class |
|
||||
| `16-stress.sh` | stress: throughput baseline vs. PF, state/rule/table churn with leak checks, 2 MB through NAT under a saturating stream, dmesg health (run by `scripts/stress/run-stress.sh`, which writes a report) |
|
||||
|
||||
The screencasts ([screencast.md](screencast.md)) show most of these gates
|
||||
being run, with the lab's network diagram drawn over the terminal.
|
||||
|
||||
## 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).
|
||||
@@ -768,3 +768,290 @@ 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;
|
||||
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).
|
||||
|
||||
## 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.
|
||||
|
||||
## Scheduler back ends in the build (M5, first step)
|
||||
|
||||
`pfsrc/hfsc.c` and `pfsrc/fq_codel.c` are now compiled into `pf.ko` (the
|
||||
`pf_ioctl` queue manager already references `hfsc_initialize`,
|
||||
`hfsc_pf_addqueue`, `ifq_hfsc_ops`, `fqcodel_pf_addqueue`, `ifq_fqcodel_ops`).
|
||||
The priq shim in `compat/pfk_ifq.c` remains the *attached* scheduler, so
|
||||
behaviour is unchanged until the data path enqueues into a queue.
|
||||
|
||||
Compat surface added for the back ends (all in `module/include/pfk.h` /
|
||||
`pfk_if.h` / `compat/pfk_ifq.c`):
|
||||
|
||||
| OpenBSD | This port |
|
||||
|---|---|
|
||||
| `struct mbuf_list` + `ml_init/ml_enqueue/ml_dequeue/ml_dequeue_tail/ml_enlist/ml_len/ml_empty/ml_purge`, `MBUF_LIST_FIRST/INITIALIZER` | inline helpers in `pfk_if.h` (`ml_purge` in `compat/pfk_mbuf.c`) |
|
||||
| `ifq_q_enter()/ifq_q_leave()` (scheduler ownership handshake, guarded by the ifq mutex) | ownership check against `ifq->ifq_ops`, returning `ifq_softc`; `leave` is a no-op (the port has no ifq mutex — the data path is one ordered work queue) |
|
||||
| `nsecuptime()` | `getnsecuptime()` (`ktime_get_ns`) |
|
||||
| `tick_nsec` (`HFSC_CLK_PER_TICK`) | `1000000000 / HZ` |
|
||||
| `splnet()/splx()` | no-ops, kept as markers of the critical regions |
|
||||
| `KERNEL_ASSERT_LOCKED()` | no-op (structural, not runtime) |
|
||||
| `struct hfsc_sc`, `struct hfsc_class_stats`, `struct fqcodel_stats`, `PKTCNTR_INC`, `HFSC_*` limits | declared in `pfk.h` (OpenBSD keeps them in `net/if_hfsc.h` / `net/if_fq_codel.h`) |
|
||||
|
||||
Two port fixes worth recording:
|
||||
|
||||
- `min(cd->drops - 1, nitems(...) - 1)` → `min_t(unsigned int, ...)`: Linux
|
||||
type-checks `min()` and `nitems()` is `size_t`.
|
||||
- `hfsc_more_slots(u_int current)` → renamed the parameter: **`current` is a
|
||||
kernel macro** (`get_current()`), which turned the definition into a K&R
|
||||
function and produced a baffling "makes pointer from integer" error at the
|
||||
call site.
|
||||
|
||||
## ifq contract details found while wiring the schedulers (M5)
|
||||
|
||||
The staged OpenBSD back ends assume three things the first version of the
|
||||
port's ifq shim got wrong. All three were reproduced in the lab and fixed:
|
||||
|
||||
| Assumption | What the port did | Fix |
|
||||
|---|---|---|
|
||||
| `ifqop_enq()` returns **the packet to drop** (NULL = accepted) | treated a non-NULL return as an error (`ENOMEM`) and the NULL return as success → every accepted packet was reported as dropped | `ifq_enqueue()` frees the returned mbuf and reports success |
|
||||
| the scheduler state lives in `ifq->ifq_q` | `ifq_attach()` stored it in `ifq_softc` only → `hfsc_enq()` dereferenced NULL and the box died mid-transfer | `ifq_attach()` keeps both fields in sync |
|
||||
| `ifq_deq_begin()`'s cookie is consumed by `ifq_deq_commit()` | the cookie was dropped on the floor (always NULL) | a per-queue `ifq_dequeue` slot carries it |
|
||||
|
||||
Also fixed: the hfsc **root-class handle** used bit `0x1`, which is exactly the
|
||||
handle of any odd pf queue id, so `hfsc_pf_addqueue()` saw the root class as a
|
||||
duplicate of the queue being added and returned `EBUSY` ("cannot add queue").
|
||||
Handles now use bit `0x80000000`; pf queue ids are `u_int16_t`, so they can
|
||||
never collide.
|
||||
|
||||
### `splassert` under rw-semas
|
||||
|
||||
`PF_ASSERT_UNLOCKED()` (used by `pf_purge_expired_states()`) is a BSD
|
||||
per-CPU-spl check: "this context did not take the lock". With an rw-semaphore
|
||||
`rw_status()` is global, so the assert fires whenever *another* CPU holds the
|
||||
lock - which is not a bug, and `BUG()` there turned a harmless race into a
|
||||
wedged module (`Unloading`, refcount -1). It now logs once
|
||||
(`pr_warn_ratelimited`) instead of killing the host; the invariant it protects
|
||||
(purge never acquires `pf_lock` itself) is upheld by the call sites, which are
|
||||
only reached from `systqmp` tasks and timer work.
|
||||
|
||||
### What `bandwidth` can and cannot do here
|
||||
|
||||
OpenBSD 8.0's `pfctl` keyword table exposes `burst`, `flows`, `qlimit`,
|
||||
`parent`, `default` - **not** `minimum`/`maximum`. A pf `queue` therefore only
|
||||
sets HFSC's **linkshare** curve (`qspec.linkshare = scspec` in `expand_queue`).
|
||||
Linkshare is a *guarantee under contention*, not a cap: a single active class
|
||||
may run at line rate, and `bandwidth 2Mbit` alone will not make one flow
|
||||
measure 2 Mbit/s. Verifying HFSC in this port therefore requires two competing
|
||||
leaf queues and comparing their shares - which is the remaining M5 item, not a
|
||||
code defect in the queue path (attach, enqueue, drain and transmit are
|
||||
verified: `eth2` carries the hfsc ops, 117 drains observed, transfer completes,
|
||||
box stays alive).
|
||||
|
||||
## Scheduler ABI must be shared, not re-implemented (M5)
|
||||
|
||||
The first version of this note hand-wrote `struct hfsc_class_stats`,
|
||||
`struct fqcodel_stats`, `struct hfsc_sc` and the `HFSC_*` constants in `pfk.h`
|
||||
from memory of the BSD sources. Two consequences showed up in the lab:
|
||||
|
||||
1. `pfctl -s queue -v` failed with `EINVAL` - `hfsc_pf_qstats()` rejects the
|
||||
call when `*nbytes < sizeof(stats)`, and pfctl's struct (from the vendored
|
||||
`net/hfsc.h`) was smaller than the kernel's invented one.
|
||||
2. `HFSC_ROOT_CLASS` was guessed as `0x1`, which is exactly the handle of every
|
||||
odd pf queue id, so `hfsc_pf_addqueue()` refused every root queue with
|
||||
`EBUSY`. The real value is `0x10000`, safely above the `u_int16_t` qid
|
||||
range.
|
||||
|
||||
The port now vendors OpenBSD's `net/hfsc.h` and `net/fq_codel.h` into
|
||||
`module/include/net/` and includes them from `pfk.h`, so kernel and pfctl
|
||||
compile against one definition. Rule for anything else in this area: if a
|
||||
struct crosses the ioctl boundary, take the header from OpenBSD's tree - do not
|
||||
reconstruct it.
|
||||
|
||||
## Screencast pipeline: what the recording taught us (2026-11-12)
|
||||
|
||||
Not a compat-layer deviation, but the same kind of note - the things that
|
||||
only show up when you watch the thing run:
|
||||
|
||||
1. **The tty echo is the terminal, and readline fights it.** With bash's
|
||||
default line editing, the remote tty echoes every keystroke *and*
|
||||
readline redraws the line when you press enter, so the command appeared
|
||||
twice on screen. `bash --noediting` leaves the tty echo alone and the
|
||||
command shows exactly once.
|
||||
2. **`pfctl -e` prints "pf enabled" and so does the `echo` after it.** What
|
||||
looked like a duplicated output line was two different programs saying the
|
||||
same thing; the capture was right.
|
||||
3. **MiniMax returns the audio as a hex string**, not base64 - the payload
|
||||
starts with the ASCII of the ID3 header (`49443304`). Decoding it as
|
||||
base64 produced files that ffmpeg called "Header missing".
|
||||
4. **Pacing has to be driven by the narration.** If the voice for a beat is
|
||||
longer than the beat, the audio runs over the next action. The recorder now
|
||||
holds each beat for as long as the longest segment (EN or PT) needs, so one
|
||||
capture serves both languages.
|
||||
5. **A phase that runs `rmmod` can break another recording.** The activation
|
||||
phase unloads the module on purpose; running two captures at once left the
|
||||
routing phase without `/dev/pf` mid-session. `record.py --ensure-pf` now
|
||||
makes sure the module is in place before the capture starts.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Documentação do 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 **packet filter do
|
||||
OpenBSD 8.0 (PF)** para o **Linux 7.3.4** — o engine PF real (`pf.c`,
|
||||
`pf_norm.c`, `pf_table.c`, `pf_lb.c`, `hfsc.c`, …) rodando como o módulo
|
||||
out-of-tree `pf.ko`, controlado pelo `pfctl` real do OpenBSD sobre a ABI ioctl
|
||||
de `/dev/pf`.
|
||||
|
||||
## Índice
|
||||
|
||||
| Doc | O que cobre |
|
||||
|---|---|
|
||||
| [guide.md](guide.md) | Arquitetura em uma página: componentes, caminho de dados, plano de controle, milestones |
|
||||
| [install.md](install.md) | Receita de apply/build/install (kernel, módulo, ferramentas) |
|
||||
| [debian13.md](debian13.md) | Implementação completa do zero no Debian 13 (trixie): preparar host, compilar kernel/módulo/ferramentas, lab libvirt, teste de stress |
|
||||
| [build.md](build.md) | Pipeline de build em detalhe: fetch → vendorize → kernel → módulo → pfctl |
|
||||
| [vm-lab.md](vm-lab.md) | O lab de validação em libvirt: topologia, recriar/rodar, o que cada um dos 16 gates prova |
|
||||
| [feature-matrix.md](feature-matrix.md) | Status por feature: VERIFIED-in-VM / VERIFIED-offline / COMPILES-untested / NOT-ENABLED |
|
||||
| [pf-guide.md](pf-guide.md) | Uso diário: o que funciona hoje em `/etc/pf.conf` e as divergências a conhecer |
|
||||
| [screencast.md](screencast.md) | Os vídeos narrados (inglês e português): fases, pipeline, como regravar |
|
||||
| [patches.md](patches.md) | Conjunto de patches de core do Linux (hoje vazio) + regras e template para futuros `000N-*.patch` |
|
||||
| [caveats.md](caveats.md) | Divergências conhecidas em relação ao OpenBSD e limitações atuais |
|
||||
|
||||
## Fontes da verdade
|
||||
|
||||
Os docs descrevem o código como ele existe nesta árvore. Na 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 dos milestones (tarefas T1–T19)
|
||||
- `docs/porting-notes.md` — log de staging + registro das divergências (a verdade sobre as divergências da camada de compat)
|
||||
|
||||
Vocabulário de status usado nestes docs:
|
||||
|
||||
- **VERIFIED-in-VM** — exercitado de ponta a ponta no lab libvirt; o gate que prova está nomeado (veja [vm-lab.md](vm-lab.md)).
|
||||
- **VERIFIED-offline** — provado por um teste de fixture ou de ABI, não por tráfego.
|
||||
- **COMPILES-untested** — o código é compilado dentro do `pf.ko`/`pfctl` mas nenhum gate o exercitou.
|
||||
- **NOT-ENABLED** — o código existe mas a feature está desligada neste build.
|
||||
- **OUT-OF-SCOPE** — fora de escopo por desenho (spec §3).
|
||||
|
||||
A suíte do lab está **16/16 verde** (`./scripts/vm-run-tests.sh`).
|
||||
@@ -0,0 +1,146 @@
|
||||
# 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: a
|
||||
interface BSD `ifq`/`pfq` mora dentro dele, não é um qdisc `tc` separado). 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`, `pfk_pflog.c`, `hfsc.c`, `fq_codel.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`, `pdivert`, `pflogd`, `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 relay de divert, compilado a partir de `tools/pdivert/`. Ele
|
||||
fala com a família de sockets `AF_DIVERT` que o módulo registra em runtime
|
||||
(`socket(PF_DIVERT=32, SOCK_RAW, IPPROTO_DIVERT=254)`); o gate
|
||||
`11-divert.sh` prova a ida e a volta.
|
||||
- `pflogd` — lê `/dev/pflog` e escreve um pcap DLT_PFLOG cujo layout de
|
||||
registro é byte a byte compatível com o `pflog(4)` do OpenBSD; gate
|
||||
`12-pflog.sh`.
|
||||
|
||||
## 7. Screencasts — `scripts/screencast/build-all.sh`
|
||||
|
||||
Não faz parte do build do kernel, mas faz parte da entrega. O pipeline:
|
||||
|
||||
| Etapa | Script | O que faz |
|
||||
|---|---|---|
|
||||
| texto da narração | `make_narration.py` | escreve `scripts/screencast/narration/<fase>.{en,pt}.json` (um segmento por batida da sessão) |
|
||||
| voz | `make_audio.py` | TTS do MiniMax, um MP3 por segmento, voz feminina por idioma |
|
||||
| sessão | `record.py` | sessão SSH real no lab: comandos digitados tecla a tecla, capturada como asciicast v2 |
|
||||
| vídeo | `render_video.py` | reproduz a captura por um emulador de terminal, desenha o diagrama do lab, queima as legendas |
|
||||
| montagem | `assemble.py` | mixa a narração na linha do tempo |
|
||||
| filme completo | `join.py` | emenda as fases com crossfade sobre cartões de capítulo |
|
||||
|
||||
`make screencast` (ou o script) roda tudo; precisa de `MINIMAX_API_KEY` e do
|
||||
lab no ar. Detalhes: [screencast.md](screencast.md).
|
||||
|
||||
## 8. `Makefile` raiz
|
||||
|
||||
`make module | tools | kernel | vm | vm-destroy | test | screencast | docs | clean` —
|
||||
wrappers finos sobre os scripts acima. `make test` roda a suíte em VM
|
||||
([vm-lab.md](vm-lab.md)); `make screencast` renderiza os vídeos;
|
||||
`make docs` apenas lista o conjunto bilíngue.
|
||||
|
||||
## O que já foi exercitado vs. não
|
||||
|
||||
- As etapas 1–6 foram rodadas repetidamente no host de build (há artefatos
|
||||
na árvore: `out/`, `module/pf.ko`, `tools/out/{pfctl,pdivert,pflogd}`), e os
|
||||
scripts acima foram verificados linha a linha para este documento.
|
||||
- A etapa 7 (os screencasts) foi rodada de ponta a ponta para as sete fases
|
||||
nos dois idiomas; os vídeos estão em `out/screencast/{en,pt}/`.
|
||||
- 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.
|
||||
@@ -0,0 +1,238 @@
|
||||
# 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: o PF avalia o ruleset **out** no `FORWARD` (o OpenBSD
|
||||
faz o mesmo no `ip_forward()`), e o `POSTROUTING` é pulado depois que essa
|
||||
avaliação roda. `nat-to`/`rdr-to` foram validados contra essa ordem (gates
|
||||
05/06).
|
||||
- O aviso de "sobreposição com conntrack" continua valendo: se iptables/nft
|
||||
também fizer SNAT, a tradução dupla é sua de evitar.
|
||||
|
||||
## Plano de controle / ciclo de vida
|
||||
|
||||
### 6. O unload está endurecido e verificado sob soak
|
||||
|
||||
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.
|
||||
|
||||
## Notas de comportamento verificadas hoje
|
||||
|
||||
### 7. `pfctl -s states` lista estados reais, incluindo traduções
|
||||
|
||||
A anomalia anterior era um use-after-free: `refcnt_rele()` tinha polaridade
|
||||
invertida, então chaves de estado vivas eram liberadas ainda ligadas no RBT
|
||||
de estados — o que escondia estados e quebrava o walk da árvore (`pfctl -s
|
||||
states` travando a máquina). Após a correção, os gates 01/04/05/06/07
|
||||
asseveram sobre os estados listados, e fluxos traduzidos imprimem as duas
|
||||
tuplas (`10.0.2.1:59335 (10.0.1.10:4380) -> 10.0.2.20:8`).
|
||||
|
||||
### 8. Ainda são necessários consumidores
|
||||
|
||||
`divert-to` exige um processo atrelado à porta do divert (`tools/pdivert`);
|
||||
sem listener o pacote é descartado, como o `divs_noport` do BSD, e o kernel
|
||||
imprime `pfk: divert port N: no socket bound`. `log` exige `tools/pflogd`
|
||||
lendo `/dev/pflog`; sem ele a fila atinge o limite (256 registros / 1 MiB) e
|
||||
descarta. Nenhum dos dois é mais stub, mas nenhum faz algo sem o consumidor
|
||||
rodar (ver [pf-guide.md](pf-guide.md)).
|
||||
|
||||
### 9. Filas: caminho verificado; a semântica de modelagem é do HFSC, não um bug
|
||||
|
||||
`15-queue.sh` prova que o caminho de filas funciona de ponta a ponta: a
|
||||
configuração carrega, a disciplina hfsc é anexada à interface, `pfctl -s
|
||||
queue -v` lista as duas classes com estatísticas, um fluxo de 2 MB pela fila
|
||||
completa, e o contador de pacotes da classe avança - o escalonador está mesmo
|
||||
no caminho de dados.
|
||||
|
||||
O que o lab não mostra é um *teto de taxa*, e isso é semântica do HFSC, não
|
||||
defeito do port: o `pf.conf` do OpenBSD 8.0 expõe apenas `bandwidth`, que mapeia
|
||||
para a curva **linkshare** do HFSC - garantia quando classes competem, não limite
|
||||
de um fluxo isolado. Não existe palavra-chave `minimum`/`maximum` nesta versão do
|
||||
pfctl (verificado na sua tabela de palavras-chave), logo não há como definir
|
||||
upperlimit pelo pf.conf. Um teste de contenção com duas classes saturadas seria o
|
||||
próximo passo se você quiser asserir sobre share; no enlace virtual de centenas de
|
||||
Mbit do lab, um único fluxo termina antes de acumular dívida de tempo virtual.
|
||||
|
||||
Bugs encontrados e corrigidos no caminho (detalhes em `docs/porting-notes.md`): a
|
||||
convenção de retorno de `ifqop_enq`, `ifq_q` vs `ifq_softc` (deref de NULL que
|
||||
matava a máquina no meio da transferência), o cookie de dequeue perdido, o
|
||||
handle da classe raiz do hfsc colidindo com qids ímpares do pf, o
|
||||
`DIOCGETQSTATS` falhando porque kernel e pfctl discordavam sobre
|
||||
`struct hfsc_class_stats` (ambos agora usam o `net/hfsc.h` vendorizado), o
|
||||
payload do pflog começando no cabeçalho de transporte, e o `splassert` do caminho
|
||||
de purge que transformava uma corrida benigna em `BUG()`.
|
||||
|
||||
## 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.
|
||||
|
||||
## Pipeline dos screencasts (2026-11-12)
|
||||
|
||||
### 10. A geração de vídeo do MiniMax não está habilitada nesta conta
|
||||
|
||||
Todos os modelos de vídeo do MiniMax (`T2V-01`, `T2V-01-Director`,
|
||||
`MiniMax-Hailuo-02`) respondem com o erro de API **2068 — "The current Token
|
||||
Plan tier does not support this model"**. A narração (TTS) e a arte do
|
||||
cartão de título funcionam normalmente; só os modelos de vídeo estão
|
||||
bloqueados. Por isso as transições entre fases são renderizadas localmente
|
||||
com ffmpeg (um crossfade sobre um cartão de capítulo) em vez de clipes
|
||||
gerados por IA. Mudar isso exige só subir o tier da conta — o ponto de
|
||||
extensão é `scripts/screencast/join.py`, que constrói os cartões.
|
||||
|
||||
### 11. A narração é uma trilha separada, não uma dublagem do vídeo
|
||||
|
||||
Cada fase é gravada **uma vez** e serve aos dois idiomas: a sessão de
|
||||
terminal é neutra em relação ao idioma, e as duas versões narradas diferem
|
||||
apenas na trilha de áudio e nas legendas queimadas. O gravador segura cada
|
||||
batida na tela pelo tempo que o segmento de narração mais longo (EN ou PT)
|
||||
precisa, então a voz e a ação no terminal ficam em sincronia nos dois.
|
||||
|
||||
### 12. O que os vídeos não mostram
|
||||
|
||||
Os vídeos são uma demonstração, não uma rodada de teste: a suíte de gates do
|
||||
lab (`scripts/vm-run-tests.sh`) é a autoridade para PASS/FAIL, e os logs
|
||||
dela ficam em `out/test-logs/`. Os screencasts mostram os mesmos comandos,
|
||||
mas um quadro de vídeo não é um veredito.
|
||||
|
||||
## Achados de capacidade (2026-11-12, a partir de `scripts/stress/run-stress.sh`)
|
||||
|
||||
### 13. O backlog da workqueue cresce com a taxa oferecida: acima de ~1 Gbit/s a VM dá OOM-panic
|
||||
|
||||
Esta é a consequência mais dura da §1 e ela é **reproduzível**, não teórica.
|
||||
O PF rouba cada skb para uma única workqueue ordenada e roda o engine em
|
||||
contexto de processo, então o número de pacotes em voo só é limitado pela
|
||||
memória que o backlog consome.
|
||||
|
||||
Medido no lab (guest Alpine, **1 GB** de RAM, 4 fluxos TCP por um ruleset
|
||||
stateful):
|
||||
|
||||
| Taxa oferecida (por fluxo × 4) | Resultado |
|
||||
|---|---|
|
||||
| 50 Mbit/s (200 Mbit/s no total) | estável |
|
||||
| 100 Mbit/s (400 Mbit/s no total) | estável |
|
||||
| 250 Mbit/s (**1 Gbit/s** no total) | **kernel panic: "System is deadlocked on memory"** |
|
||||
|
||||
O panic é um OOM sem processo matável; o slab naquele momento mostra
|
||||
`kmalloc-8k` ≈ 50 MB, `skbuff_head_cache` ≈ 18 MB e `files_cache` ≈ 40 MB —
|
||||
ou seja, o backlog comeu o 1 GB. A VM reinicia (watchdog de 120 s) e todas as
|
||||
conexões que passavam pelo firewall caem junto.
|
||||
|
||||
Consequências práticas:
|
||||
|
||||
- **Limite a taxa que você aponta para o PF** e dimensione a máquina para o
|
||||
backlog: a memória necessária cresce com a taxa oferecida, não com o
|
||||
número de fluxos concorrentes.
|
||||
- Por isso o teste de stress (`tests/vm/16-stress.sh`) roda as fases de
|
||||
tráfego a uma taxa **limitada** (padrão: 100 Mbit/s por fluxo = 400 Mbit/s
|
||||
no total) — o regime que este port suporta — e reporta o teto
|
||||
separadamente, em vez de dar OOM no firewall sob teste.
|
||||
- Os gates funcionais (01-15) não são afetados: eles movem megabytes, não gigabits
|
||||
por segundo.
|
||||
|
||||
O que resolveria isso é um fast path de verdade (avaliar `pf_test()` inline em
|
||||
softirq, como o OpenBSD faz) ou uma fila limitada com política de drop — as
|
||||
duas são mudanças de design fora do escopo deste port.
|
||||
|
||||
## 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`).
|
||||
@@ -0,0 +1,495 @@
|
||||
# PF no Linux — implementação do zero no Debian 13 (trixie)
|
||||
|
||||
Este documento é o caminho completo, do zero, para rodar o **PF-on-Linux**
|
||||
(port do PF do OpenBSD 8.0 como módulo de kernel out-of-tree) em uma máquina
|
||||
**Debian 13 (trixie)**: preparar o host, compilar o kernel 7.3.4, compilar o
|
||||
módulo `pf.ko` e o `pfctl`, subir o laboratório libvirt, rodar a suíte de 16
|
||||
gates e o **teste de stress**.
|
||||
|
||||
Cada comando aqui foi executado no Debian 13.7 (`trixie`) do laboratório e a
|
||||
saída real está indicada. Onde o número importa, ele é o número medido — não
|
||||
uma estimativa.
|
||||
|
||||
---
|
||||
|
||||
## 0. Antes de começar: o que precisa ficar claro
|
||||
|
||||
| Fato | Consequência prática |
|
||||
|---|---|
|
||||
| `pf.ko` é compilado contra a árvore do **Linux 7.3.4** e carrega o `vermagic` desse kernel | Ele **não** carrega no kernel do Debian 13 (6.12). Não tente `insmod pf.ko` no 6.12: o `vermagic` diverge e o `insmod` falha. |
|
||||
| O módulo registra hooks **netfilter** em `init_net` (IPv4 e IPv6, 5 pontos cada) | PF convive com `nftables`/`iptables`; ele não substitui o firewall do Debian. |
|
||||
| PF roda em **um namespace de rede só** (`init_net`) | Não há instância de PF por netns. |
|
||||
| O OpenBSD `pfctl` fala com o módulo pelo ioctl ABI de `/dev/pf` | O `pfctl` desta árvore é o **OpenBSD 8.0** compilado para Linux; não é o do Debian. |
|
||||
|
||||
Três papéis cabem na mesma máquina Debian 13 — e é assim que o laboratório
|
||||
foi validado:
|
||||
|
||||
| Papel | O que faz | Onde |
|
||||
|---|---|---|
|
||||
| **build host** | compila o kernel 7.3.4, o `pf.ko` e o userland | `~/lab/linux_kernel/pf_port` |
|
||||
| **hypervisor** | hospeda as 4 VMs de teste (libvirt/KVM) | mesmo host, `libvirtd` |
|
||||
| **host PF** (opcional) | roda o próprio PF no Debian 13, depois de bootar com o kernel 7.3.4 | mesmo host, com aviso no §9 |
|
||||
|
||||
---
|
||||
|
||||
## 1. Passo 1 — preparar o host
|
||||
|
||||
```sh
|
||||
git clone <url-do-repo> ~/lab/linux_kernel/pf_port # ou: cp -a /caminho/pf_port ~/lab/linux_kernel/
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
sudo ./scripts/debian13/prepare-host.sh
|
||||
```
|
||||
|
||||
O script é idempotente: instala os pacotes e imprime o estado do toolchain.
|
||||
Saída real no Debian 13.7:
|
||||
|
||||
```
|
||||
== toolchain
|
||||
gcc 14
|
||||
make GNU Make 4.4.1
|
||||
bison bison (GNU Bison) 3.8.2
|
||||
flex flex 2.6.4
|
||||
bc bc 1.07.1
|
||||
rsync rsync version 3.5.0 protocol version 32
|
||||
libvirt 11.3.0
|
||||
qemu QEMU emulator version 10.0.13 (Debian 1:10.0.13+ds-0+deb13u1)
|
||||
geniso genisoimage 1.1.11 (Linux)
|
||||
|
||||
PREPARE_HOST_OK
|
||||
```
|
||||
|
||||
**Sobre o compilador.** O Debian 13 traz `gcc-14` como padrão e **não tem
|
||||
`gcc-15` em trixie** (`apt-cache policy gcc-15` → nenhum candidato). O
|
||||
`docs/en/install.md` pede "gcc ≥ 15" porque o host de desenvolvimento
|
||||
original é Fedora. No Debian 13 o build é feito com **gcc 14.2.0** — o kernel
|
||||
7.3.4 e o `pf.ko` compilam sem patch (verificado, §4).
|
||||
|
||||
Se preferir separar os papéis, use `--build-only` ou `--lab-only`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Passo 2 — obter as fontes
|
||||
|
||||
### 2.1 Árvore do kernel 7.3.4
|
||||
|
||||
O repositório **não** traz o kernel: ele espera a árvore em
|
||||
`~/lab/linux_kernel/linux-7.3.4` (irmã do repositório). Do zero:
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel
|
||||
curl -fLO https://cdn.kernel.org/pub/linux/kernel/v7.x/linux-7.3.4.tar.xz
|
||||
curl -fLO https://cdn.kernel.org/pub/linux/kernel/v7.x/sha256sums.asc
|
||||
sha256sum -c --ignore-missing sha256sums.asc # confere só o tarball baixado
|
||||
tar xf linux-7.3.4.tar.xz
|
||||
```
|
||||
|
||||
O hash confere com o publicado pelo kernel.org:
|
||||
|
||||
```
|
||||
b11b6df8295e8e991ff040b71aaa4994a8b55caa23b6b092907f195b5840fd1f linux-7.3.4.tar.xz
|
||||
```
|
||||
|
||||
### 2.2 Fontes do OpenBSD 8.0 (o PF em si)
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
./scripts/fetch-sources.sh # baixa sys.tar.gz + src.tar.gz, confere sha256 (pins no VERSIONS)
|
||||
./scripts/vendorize.sh # extrai só os arquivos portados -> _vendor/upstream + IDS.txt
|
||||
```
|
||||
|
||||
Espere as linhas `OK sys.tar.gz` e `OK src.tar.gz`. O `fetch-sources.sh`
|
||||
tenta o mirror `openbsd.c3sl.ufpr.br` e cai para `cdn.openbsd.org`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Passo 3 — compilar o kernel 7.3.4
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
KERNELDIR=~/lab/linux_kernel/linux-7.3.4 ./scripts/build-kernel.sh
|
||||
```
|
||||
|
||||
O que o script faz, em ordem:
|
||||
|
||||
1. `scripts/kernel-config.sh` — parte de `make defconfig` e liga
|
||||
`VIRTIO_BLK/PCI/NET=y`, `EXT4_FS=y`, `NETFILTER=y`, `NET_SCHED=y`,
|
||||
`INET=y`, `IPV6=y`, `SERIAL_8250(+CONSOLE)=y` (é o que permite bootar a VM
|
||||
`pf0` direto no kernel, **sem initrd**) e roda `make olddefconfig`;
|
||||
2. `make -j$(nproc-2) bzImage modules_prepare` — compila o kernel e prepara a
|
||||
árvore para módulos externos;
|
||||
3. copia `vmlinux.symvers` → `Module.symvers` (o kbuild não cria o segundo) e
|
||||
garante `scripts/module.lds`;
|
||||
4. publica em `out/`: `linux-7.3.4-bzImage`, `System.map`, `.config`,
|
||||
`kernelversion`, `bzImage.sha256`.
|
||||
|
||||
Termina com:
|
||||
|
||||
```
|
||||
KERNEL_BUILD_OK 7.3.4
|
||||
```
|
||||
|
||||
Tempo de referência no host do lab (Debian 13, 12 threads): **~4 min** para o
|
||||
build do kernel em si (`bzImage` + `modules_prepare`) em uma árvore que já
|
||||
tinha objetos, e o script inteiro — configurar, compilar, publicar os
|
||||
artefatos — em menos de 3 minutos. Uma árvore vinda direto do tarball
|
||||
começa vazia; aí o passo `make` domina o tempo.
|
||||
|
||||
---
|
||||
|
||||
## 4. Passo 4 — compilar o módulo `pf.ko`
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
./scripts/build-module.sh # == make -C $KERNELDIR M=$PWD/module
|
||||
```
|
||||
|
||||
Saída: `MODULE_BUILD_OK` e o artefato `module/pf.ko`.
|
||||
|
||||
**Verifique o `vermagic`** — é ele que decide onde o módulo carrega:
|
||||
|
||||
```sh
|
||||
modinfo module/pf.ko | grep vermagic
|
||||
# vermagic: 7.3.4 SMP preempt mod_unload
|
||||
```
|
||||
|
||||
Esse é o motivo de o kernel e o módulo terem de sair **da mesma árvore**: um
|
||||
`pf.ko` compilado contra outra árvore 7.3.4 pode ter `vermagic` subtly
|
||||
diferente (`SMP preempt mod_unload modversions` + `CONFIG_*` do build) e o
|
||||
`insmod` recusa.
|
||||
|
||||
### 4.1 Verificação do ABI userspace ↔ kernel
|
||||
|
||||
O `pfctl` fala com o kernel por structs compartilhadas. O harness `abitest`
|
||||
compara o layout das duas pontas:
|
||||
|
||||
```sh
|
||||
make -C tools abi # compila abitest (userspace) e abitest-module (kernel),
|
||||
# dumpa as tabelas de tamanho/offset e faz o diff
|
||||
```
|
||||
|
||||
Sem saída de diff = ABI intacto.
|
||||
|
||||
---
|
||||
|
||||
## 5. Passo 5 — compilar o userland
|
||||
|
||||
```sh
|
||||
make -C tools # -> tools/out/{pfctl,pdivert,pflogd} + abitest
|
||||
```
|
||||
|
||||
O `pfctl` sai **estático** (`-static`), para poder ser copiado para as VMs
|
||||
Alpine sem dependências. Checagem offline (não precisa de `/dev/pf`):
|
||||
|
||||
```sh
|
||||
(cd tools && ./out/pfctl -nf tests/01_basic.conf) # parse-only: sem saída = ok
|
||||
make -C tools test # roda todos os .conf de teste
|
||||
make -C tools abi # tabelas de ABI userspace vs kernel
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.1 O que o build no Debian 13 produziu (verificado)
|
||||
|
||||
Tudo abaixo foi compilado e executado no Debian 13.7 com **gcc 14.2.0** — sem
|
||||
patch, sem backport:
|
||||
|
||||
```
|
||||
$ ./scripts/build-module.sh
|
||||
...
|
||||
MODULE_BUILD_OK
|
||||
$ modinfo module/pf.ko | grep vermagic
|
||||
vermagic: 7.3.4 SMP preempt mod_unload
|
||||
$ make -C tools test
|
||||
PASS tests/01_basic.conf (exit 0)
|
||||
PASS tests/02_translations.conf (exit 0)
|
||||
PASS tests/03_queues_scrub.conf (exit 0)
|
||||
PASS tests/broken.conf rejected (non-zero exit)
|
||||
$ make -C tools abi
|
||||
ABI OK: identical tables
|
||||
```
|
||||
|
||||
O `vermagic` impresso pelo build no Debian é idêntico ao que a VM do lab
|
||||
aceita. Verificado de ponta a ponta: o módulo compilado no Debian 13 foi
|
||||
copiado para a VM do lab e carregado lá —
|
||||
|
||||
```
|
||||
INSMOD_DEBIAN_MODULE_OK
|
||||
Status: Enabled
|
||||
crw------- 1 root root 10, 259 /dev/pf
|
||||
[ 119.057040] pfk: netfilter hooks registered (10, netisr wq data path)
|
||||
```
|
||||
|
||||
— desde que ele tenha sido compilado a partir da mesma árvore do kernel que
|
||||
a VM sobe.
|
||||
|
||||
---
|
||||
|
||||
## 6. Passo 6 — o laboratório libvirt no Debian 13
|
||||
|
||||
O lab são 4 VMs Alpine (`pf0` = o firewall sob teste, `cli`, `srv`, `gw2`),
|
||||
rede de gerência com DHCP e três bridges isolados `pf-lan`/`pf-wan`/`pf-wan2`.
|
||||
A topologia está em `lab/ips.env`.
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/pf_port
|
||||
./scripts/vm-create.sh --pf0-kernel=out/linux-7.3.4-bzImage
|
||||
```
|
||||
|
||||
Esse comando é idempotente: destrói e recria os domínios `pftest-*`, gera as
|
||||
seeds cloud-init, sincroniza a imagem base Alpine e sobe tudo. Sem
|
||||
`--pf0-kernel=`, a `pf0` sobe com o kernel da própria imagem Alpine — e aí o
|
||||
`pf.ko` **não** carrega (vermagic). **Sempre** passe `--pf0-kernel=` quando a
|
||||
intenção é testar PF.
|
||||
|
||||
Deploy dos artefatos para a VM:
|
||||
|
||||
```sh
|
||||
./scripts/vm-deploy.sh # laptop -> deb ($DEPLOY_DIR) -> pf0:/opt/pf/
|
||||
```
|
||||
|
||||
Verifique a VM:
|
||||
|
||||
```sh
|
||||
ssh pf0 'uname -r; lsmod | grep -w pf; ls -l /opt/pf/'
|
||||
```
|
||||
|
||||
Esperado: `7.3.4`, o módulo `pf` carregado e `pf.ko`/`pfctl`/`pdivert`/`pflogd`
|
||||
em `/opt/pf/`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Passo 7 — a suíte de 16 gates
|
||||
|
||||
```sh
|
||||
./scripts/vm-run-tests.sh # ou: make test
|
||||
```
|
||||
|
||||
O runner reinicia a `pf0` antes de cada gate (estado limpo), re-deploya o
|
||||
módulo e as ferramentas, e roda o gate a partir do build host. Saída esperada:
|
||||
|
||||
```
|
||||
PASS=16 FAIL=0
|
||||
```
|
||||
|
||||
Logs por gate em `out/test-logs/<gate>.sh.log`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Passo 8 — o teste de stress
|
||||
|
||||
O projeto não tinha gate de desempenho (o `docs/en/vm-lab.md` registrava
|
||||
explicitamente essa lacuna). O stress é um gate novo, `tests/vm/16-stress.sh`,
|
||||
que pergunta coisas diferentes das gates funcionais: *"o motor continua
|
||||
correto, limitado e sem vazamento enquanto tráfego, estados, regras e tabelas
|
||||
giram?"*.
|
||||
|
||||
```sh
|
||||
./scripts/stress/run-stress.sh # perfil padrão
|
||||
./scripts/stress/run-stress.sh --quick # perfil curto (smoke)
|
||||
./scripts/stress/run-stress.sh --seconds 30 --connections 2000 --reloads 500
|
||||
```
|
||||
|
||||
Opções: `--seconds`, `--parallel`, `--rate`, `--connections`, `--reloads`,
|
||||
`--rules`, `--table-entries`, `--max-overhead`. O runner reset da `pf0`, faz o
|
||||
deploy, roda o gate e grava o relatório em `out/stress/<timestamp>/report.md`.
|
||||
|
||||
> **As fases de tráfego rodam com taxa limitada** (`--rate`, padrão
|
||||
> 100 Mbit/s por fluxo = 400 Mbit/s no total). Não é conveniência: o PF
|
||||
> rouba cada skb para uma única workqueue ordenada e roda o engine em
|
||||
> contexto de processo, então o backlog — e a memória que ele consome —
|
||||
> cresce com a taxa oferecida. Na VM de 1 GB do lab, 400 Mbit/s é estável e
|
||||
> **~1 Gbit/s dá OOM-panic no kernel** ("System is deadlocked on memory").
|
||||
> Por isso o teste de stress trabalha no regime que o port suporta e reporta
|
||||
> o teto separadamente, em vez de matar o firewall sob teste. Detalhes em
|
||||
> [`caveats.md` §13](caveats.md).
|
||||
|
||||
### 8.1 O que cada fase mede
|
||||
|
||||
| Fase | O que faz | Como é julgado |
|
||||
|---|---|---|
|
||||
| 0 — baseline | throughput `cli -> srv` na taxa limitada com o **módulo fora do caminho** (`rmmod pf`) | precisa de > 0 Mbit/s (sem isso o resto não tem sentido) |
|
||||
| 1 — overhead | o mesmo tráfego com PF ligado e regras stateful | `%` de overhead = (baseline − com PF) / baseline, contra o limite (padrão 30%) — na taxa com teto isso significa "o PF sustenta a taxa oferecida" |
|
||||
| 2 — state churn | 300 conexões TCP concorrentes contra um listener dedicado no servidor | os estados **aparecem** na tabela (`pfctl -s states`) e **desaparecem** depois de `pfctl -sr` → sem vazamento |
|
||||
| 3 — rule churn | 200 recargas de um ruleset de 200 regras | zero falhas de carga, tempo de recarga medido **dentro** da VM (min/méd/máx), contagem de regras estável |
|
||||
| 4 — table churn | 2000 entradas em uma `pfr` table | entradas somem após o flush → sem vazamento de tabela |
|
||||
| 5 — integridade | 2 MB atravessando `nat-to` **enquanto** um stream satura o link | sha256 do arquivo recebido = sha256 da origem |
|
||||
| 6 — saúde | `dmesg`, contadores do PF, e um ping final | nenhum `BUG/WARNING/Oops`; contadores mexem; o firewall ainda roteia |
|
||||
|
||||
### 8.2 Como ler o relatório
|
||||
|
||||
Uma rodada real no lab (perfil completo, `out/stress/<timestamp>/report.md`):
|
||||
|
||||
```
|
||||
STRESS phase=baseline baseline_mbit=400 seconds=10 parallel=4 rate_per_stream=100M
|
||||
STRESS phase=overhead pf_mbit=400 overhead_pct=0 limit_pct=30 rate_per_stream=100M
|
||||
STRESS phase=state_churn connections=300 states_before=0 states_created=300 states_after_reset=0 established_on_srv=214 rules_loaded=3 pf_status=Enabled
|
||||
STRESS phase=rule_churn reloads=200 rules_per_load=200 reload_fails=0 reload_ms_avg=11 reload_ms_max=20 rules_final=202
|
||||
STRESS phase=table_churn entries_requested=2000 entries_added=2000 add_errors=0 entries_after_flush=0
|
||||
STRESS phase=integrity bytes=2000000 sha256_match=yes
|
||||
STRESS phase=health dmesg_anomalies=0 match=5855 state_entries=7
|
||||
```
|
||||
|
||||
Como ler: o PF sustenta os 400 Mbit/s limitados com **0% de overhead** contra
|
||||
o baseline sem módulo, acompanha **300/300** fluxos concorrentes como estados
|
||||
e esvazia a tabela de volta a 0, recarrega um ruleset de 202 regras **200
|
||||
vezes** sem falhar (11 ms de média, 20 ms o pior caso), esvazia **2000**
|
||||
entradas de tabela de volta a 0, move 2 MB por NAT byte a byte enquanto um
|
||||
stream corre e não deixa nenhum `BUG/WARNING/Oops` para trás.
|
||||
|
||||
O runner imprime `STRESS RESULT: PASS` ou `FAIL` e sai com o status do gate.
|
||||
|
||||
> **Nota de honestidade:** os números de throughput são de um lab virtualizado
|
||||
> (KVM, 2 vCPU por VM, rede `virtio` com bridge no host). Servem para
|
||||
> *comparar* baseline contra PF no mesmo ambiente, não como número de
|
||||
> produção. O overhead medido inclui a cópia de pacote e o caminho de software
|
||||
> do PF — é o preço do filter stateful no userspace-space do kernel.
|
||||
|
||||
---
|
||||
|
||||
## 9. Passo 9 (opcional) — rodar o PF no próprio Debian 13
|
||||
|
||||
Isto **não** é necessário para o laboratório, e tem um custo: o host do lab é
|
||||
também o hypervisor — reiniciar com outro kernel derruba as VMs.
|
||||
|
||||
```sh
|
||||
cd ~/lab/linux_kernel/linux-7.3.4
|
||||
sudo make modules_install # pf.ko -> /lib/modules/7.3.4/
|
||||
sudo cp arch/x86/boot/bzImage /boot/vmlinuz-7.3.4
|
||||
sudo update-initramfs -u -k 7.3.4 # ou: update-grub
|
||||
sudo reboot # ⚠ derruba as VMs do lab
|
||||
```
|
||||
|
||||
Depois do boot (com o 7.3.4 ativo):
|
||||
|
||||
```sh
|
||||
uname -r # 7.3.4
|
||||
sudo insmod /lib/modules/7.3.4/pf.ko # cria /dev/pf (0600) e registra os hooks
|
||||
ls -l /dev/pf
|
||||
sudo cp ~/lab/linux_kernel/pf_port/tools/out/pfctl /usr/local/sbin/
|
||||
sudo pfctl -e
|
||||
sudo pfctl -f /etc/pf.conf
|
||||
sudo pfctl -s info
|
||||
```
|
||||
|
||||
`/etc/pf.conf` mínimo (sintaxe OpenBSD 8.0):
|
||||
|
||||
```
|
||||
set skip on lo
|
||||
block return
|
||||
pass on egress
|
||||
```
|
||||
|
||||
Para deixar o PF ligado no boot, uma unit simples:
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/pf.service
|
||||
[Unit]
|
||||
Description=PF-on-Linux engine
|
||||
After=network-pre.target
|
||||
Before=multi-user.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
RemainAfterExit=yes
|
||||
ExecStart=/sbin/modprobe pf
|
||||
ExecStart=/usr/local/sbin/pfctl -e
|
||||
ExecStop=/usr/local/sbin/pfctl -d
|
||||
ExecStop=/sbin/modprobe -r pf
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
E o `pflogd` (escreve pcap `DLT_PFLOG`, layout OpenBSD `pflog(4)`):
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/pflogd.service
|
||||
[Unit]
|
||||
Description=PF log daemon
|
||||
After=pf.service
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/sbin/pflogd /var/log/pf/pflog.pcap
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
> `pflogd` lê `/dev/pflog` (criado pelo módulo, 0600). Este `pfctl` **não**
|
||||
> tem o modificador `-s pflog`: o log é ligado por regra, com a palavra-chave
|
||||
> do OpenBSD (`pass log on egress ...`, `block log ...`). O pcap em disco fica
|
||||
> onde você apontar o `pflogd`.
|
||||
|
||||
---
|
||||
|
||||
## 10. Checklist de verificação
|
||||
|
||||
```sh
|
||||
# 1. módulo carregado e device criado
|
||||
lsmod | grep -w pf && ls -l /dev/pf
|
||||
|
||||
# 2. PF habilitado
|
||||
pfctl -s info | head -2 # Status: Enabled
|
||||
|
||||
# 3. parser do OpenBSD 8.0 no binário do Debian
|
||||
pfctl -nf /etc/pf.conf
|
||||
|
||||
# 4. hooks registrados
|
||||
dmesg | grep pfk # "pfk: netfilter hooks registered (10, netisr wq data path)"
|
||||
|
||||
# 5. o firewall filtra de verdade
|
||||
pfctl -sr; pfctl -s states
|
||||
|
||||
# 6. suíte completa
|
||||
./scripts/vm-run-tests.sh # PASS=16 FAIL=0
|
||||
|
||||
# 7. stress
|
||||
./scripts/stress/run-stress.sh # STRESS RESULT: PASS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Troubleshooting
|
||||
|
||||
| Sintoma | Causa | Ação |
|
||||
|---|---|---|
|
||||
| `insmod: ERROR: could not insert 'pf.ko': Invalid module format` | `vermagic` diferente do kernel em execução | o kernel e o módulo precisam sair da **mesma** árvore; recompile os dois |
|
||||
| `insmod` falha no kernel do Debian (6.12) | o módulo é para 7.3.4 | bootar com o kernel 7.3.4 (§9) ou testar dentro da VM do lab |
|
||||
| `pfctl: Permission denied` | `/dev/pf` é 0600 root | rodar como root |
|
||||
| `pfctl: Device not configured` | módulo carregado mas `pfctl -e` não foi feito | `sudo pfctl -e` |
|
||||
| `virsh: cannot connect to qemu:///system` | libvirt parado | `sudo systemctl enable --now libvirtd` |
|
||||
| `Cannot find device 'eth2'` | nomes de interface mudam | resolver com `ip route get <ip> | grep -o 'dev [a-z0-9]*'` (o gate 15 faz isso) |
|
||||
| gate falha logo depois do deploy | `pf.ko` não copiado | o runner verifica `test -s /opt/pf/pf.ko`; ver `out/test-logs/<gate>.sh.log` |
|
||||
| stress: `baseline throughput unavailable` | `iperf3` não está no servidor | `srv 'pkill -x iperf3; iperf3 -s -D'` e conferir `netstat -lnt \| grep 5201` |
|
||||
| stress: `state churn` falha | o `bash` do guest não tem `/dev/tcp` | o gate usa `nc` como fallback; verificar `bash --version` na VM |
|
||||
| a VM reinicia durante o stress | a taxa oferecida esgotou a memória do guest (backlog da workqueue) | baixar o `--rate`; ver [caveats.md §13](caveats.md) — o teto medido no lab é ~1 Gbit/s em um guest de 1 GB |
|
||||
| `gcc-15` não encontrado | não existe no trixie | usar o gcc 14 padrão (§1) |
|
||||
|
||||
---
|
||||
|
||||
## 12. Limites conhecidos (leia antes de usar em produção)
|
||||
|
||||
- O port **não** é o PF do OpenBSD: há divergências documentadas em
|
||||
[`docs/pt-BR/caveats.md`](caveats.md) e na matriz
|
||||
[`docs/pt-BR/feature-matrix.md`](feature-matrix.md).
|
||||
- Não há `pfsync`/CARP, IPsec/pfkey, `ftp-proxy`, PF por netns nem os
|
||||
schedulers `cbq`/`wfq`/`red` (removidos no upstream antes do OpenBSD 8.0).
|
||||
- PF registra hooks netfilter em `init_net` — em um host que já use
|
||||
`nftables`, o tráfego passa pelos dois. O `bypass` do PF só vale para
|
||||
tráfego que entra pelo gancho do PF.
|
||||
- O IPv6, o OS fingerprinting, `set state-policy`/`allow-opts` e os syncookies
|
||||
compilam, mas **não** são cobertos por gate (lacuna conhecida, §5 do
|
||||
`docs/pt-BR/vm-lab.md`).
|
||||
|
||||
---
|
||||
|
||||
## 13. Referências
|
||||
|
||||
| Documento | Conteúdo |
|
||||
|---|---|
|
||||
| [`docs/pt-BR/install.md`](install.md) | receita de build genérica (sem o passo a passo do Debian) |
|
||||
| [`docs/pt-BR/vm-lab.md`](vm-lab.md) | o laboratório, topologia e gates |
|
||||
| [`docs/pt-BR/feature-matrix.md`](feature-matrix.md) | o que está verificado e o que não está |
|
||||
| [`docs/pt-BR/caveats.md`](caveats.md) | divergências conhecidas do OpenBSD 8.0 |
|
||||
| [`docs/pt-BR/pf-guide.md`](pf-guide.md) | regrasets do dia a dia e avisos |
|
||||
| English mirror | [`docs/en/debian13.md`](../en/debian13.md) |
|
||||
@@ -0,0 +1,83 @@
|
||||
# Matriz de features
|
||||
|
||||
Inglês: [docs/en/feature-matrix.md](../en/feature-matrix.md).
|
||||
|
||||
Vocabulário de status (idêntico nos dois idiomas):
|
||||
|
||||
- **VERIFIED-in-VM** — exercitado de ponta a ponta no lab libvirt (veja [vm-lab.md](vm-lab.md)); o gate que prova está nomeado.
|
||||
- **VERIFIED-offline** — provado por um teste de fixture/ABI, não por tráfego (ex.: `make -C tools test`).
|
||||
- **COMPILES-untested** — compilado dentro do `pf.ko`/`pfctl`; nenhum gate exercitou ainda.
|
||||
- **NOT-ENABLED** — o código existe mas a feature está desligada neste build (ex.: `af-to`, que depende dos caminhos `INET6`).
|
||||
- **OUT-OF-SCOPE** — fora de escopo por desenho (spec §3).
|
||||
|
||||
Atualizado em 2026-11-12; fonte da evidência por linha: `out/test-logs/`,
|
||||
`docs/porting-notes.md`, commits dos milestones e os screencasts
|
||||
([screencast.md](screencast.md)) para a prova visível.
|
||||
|
||||
A suíte está **16/16 verde** (`./scripts/vm-run-tests.sh`).
|
||||
|
||||
## Plano de controle e ferramentas
|
||||
|
||||
| Feature | Sintaxe upstream | Milestone | Status |
|
||||
|---|---|---|---|
|
||||
| Carga do módulo, `/dev/pf` (0600) | `insmod pf.ko` | M1 | VERIFIED-in-VM (gate `02-ativacao.sh`) |
|
||||
| Habilitar/desabilitar | `pfctl -e`, `pfctl -d` | M1 | VERIFIED-in-VM |
|
||||
| Carga de ruleset | `pfctl -f file` | M2 | VERIFIED-in-VM (todo gate carrega um ruleset real) |
|
||||
| Checagem só de parse | `pfctl -n -f file` | M1 | VERIFIED-offline (`make -C tools test`) |
|
||||
| Status/contadores | `pfctl -s info [-v]` | M1 | VERIFIED-in-VM |
|
||||
| Listagem de regras | `pfctl -s rules [-v]`, `pfctl -sr` | M2 | VERIFIED-in-VM (gates 02–06) |
|
||||
| Listagem de estados | `pfctl -s states [-v]`, `pfctl -ss` | M2 | VERIFIED-in-VM (gate `01-state.sh`) |
|
||||
| Listagem/operações de tabelas | `pfctl -s tables`, `-t t -T show/add/del/kill` | M2 | VERIFIED-in-VM (gate `03-tables.sh`, incluindo um `-T delete` ao vivo liberando o fluxo) |
|
||||
| Anchors | `pfctl -a anchor -f file`, `-s anchors` | M2 | VERIFIED-in-VM (gate `04-anchors.sh`) |
|
||||
| Listagem de filas | `pfctl -s queue -v` | M5 | VERIFIED-in-VM (gate `15-queue.sh`: as duas classes com estatísticas) |
|
||||
| Paridade da ABI ioctl | `make -C tools abi` (tabelas do abitest) | M1 | VERIFIED-offline (tabela do userland); o diff do lado do kernel é um passo de integração em aberto (`tools/UPSTREAM.md`) |
|
||||
|
||||
## Núcleo de filtragem
|
||||
|
||||
| Feature | Sintaxe upstream | Milestone | Status |
|
||||
|---|---|---|---|
|
||||
| `pass`/`match`, quick, on-interface/proto/addr/port | `pass in quick on wan proto tcp from 10/8 to port 80` | M2 | VERIFIED-in-VM (gate `01-state.sh`: ping de trânsito atravessando o firewall) |
|
||||
| `block drop` | `block drop in quick …` | M2 | VERIFIED-in-VM (gate `02-block.sh`: o ping morre e os contadores provam) |
|
||||
| `block return` / `return-rst` / `return-rst after quarter` | `block return-rst in quick proto tcp …` | M2 | VERIFIED-in-VM (gate `02-block.sh`: o `nc` do cliente recebe RST) |
|
||||
| `keep state` (icmp/tcp/udp), tabela de estados, purger | `… keep state` | M2 | VERIFIED-in-VM (gate `01-state.sh`; o estado aparece no `pfctl -ss`) |
|
||||
| `set state-policy`, `allow-opts`, etc. | opções `set …` | M2 | COMPILES-untested |
|
||||
| Syncookies (caminho de overflow de estados) | `set syncookies always` | M2 | COMPILES-untested |
|
||||
| Tabelas pfr (radix/hash) | `table <blk> persist { 1.2.3.4 }`, `-T add …` | M2 | VERIFIED-in-VM (gate `03-tables.sh`) |
|
||||
| Anchors + include + precedência de quick | `anchor "x"`, `load anchor …` | M2 | VERIFIED-in-VM (gate `04-anchors.sh`) |
|
||||
| IPv6 para tudo acima | mesma sintaxe, v6 | M2+ | COMPILES-untested — o engine é completo para v6 por construção, mas o caminho v6 não é exercitado por gate |
|
||||
| Tráfego não-IPv4/IPv6 (ARP…) | — | M2 | PFLINUX por construção: só os hooks netfilter IPv4/IPv6 — ARP nunca entra no caminho do PF (sem gate) |
|
||||
|
||||
## NAT / normalização (M3)
|
||||
|
||||
| Feature | Sintaxe upstream | Milestone | Status |
|
||||
|---|---|---|---|
|
||||
| `nat-to` (pools de portas, sticky-port, static-port) | `pass out … nat-to (eth1:0)` | M3 | **VERIFIED-in-VM** — gate `05-nat.sh`: o NAT de origem funciona de ponta a ponta (prova por tcpdump), a resposta é des-NATeada e re-encaminhada 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`). |
|
||||
| `rdr-to` | `pass in … to <fw> port 8080 rdr-to <srv> port 80 keep state` | M3 | **VERIFIED-in-VM** — gate `06-rdr.sh`: o cliente fala com o endereço do firewall, o pf reescreve o destino, re-encaminha o pacote, e a resposta é des-redirecionada. O gate também puxa 2 MB pelo redirect e confere a integridade byte a byte (guarda de regressão GSO/TSO). |
|
||||
| `binat-to` | `pass quick proto icmp from 10.0.2.20 to 10.0.1.10 binat-to 10.0.2.50 keep state` | M3 | **VERIFIED-in-VM** — gate `07-binat.sh`. O pfctl expande uma regra `binat-to` no par documentado (`pass out … nat-to <mapped> static-port` + `pass in … rdr-to <real>`), e as duas metades funcionam: o par vê o endereço mapeado, o original nunca vaza, e a resposta é traduzida de volta. |
|
||||
| Pools de NAT (`round-robin`, `source-hash`) | `nat-to { 10.0.2.1, 10.0.3.1 } round-robin` | M4 | **VERIFIED-in-VM** — gate `10-pools.sh`, e visível no screencast: o round-robin alterna o endereço de origem entre os membros (3 pacotes cada), o source-hash mantém uma origem em um membro só. |
|
||||
| Scrub/normalize: remontagem, `fragment drop-overlap`, `min-ttl`, `max-mss`, `df`/`no-df`, `random-id`, `set reassemble yes` | `match in all scrub (min-ttl 100 max-mss 500)` | M3 | **VERIFIED-in-VM** — gate `09-scrub.sh`: o `min-ttl` aumenta o TTL (egresso mostra 99 depois do decremento do forward) e o `max-mss` limita a opção MSS do SYN, ambos medidos no egresso do próprio firewall. Os caminhos de remontagem/overlap compilam e são alcançados, mas não têm gate. |
|
||||
| Fingerprint de OS nos estados | `pass … set os A` + `/etc/pf.os` | bonus | COMPILES-untested (`pf_osfp.c` compilado; ainda sem o pacote de fingerprints — a ausência de `/etc/pf.os` é tolerada) |
|
||||
|
||||
## Roteamento / divert / filas / logging
|
||||
|
||||
| Feature | Sintaxe upstream | Milestone | Status |
|
||||
|---|---|---|---|
|
||||
| `route-to` / `dup-to` / `reply-to` | `pass in … route-to { 10.0.3.2 } keep state`, `reply-to { gw }` | M4 | **VERIFIED-in-VM** — gates `08-routeto.sh` (o route-to sai pelo link do gateway, o dup-to copia mantendo o fluxo) e `13-replyto.sh` (a resposta de um fluxo é forçada para o link do gateway em vez do cliente). Divergência: o próximo salto forçado é instalado definindo `rt_gw4`/`rt_gw_family` na rota consultada (o Linux só faz ARP do gateway quando a rota declara um). `fail-to` **não é palavra-chave no OpenBSD 8.0** (removido upstream), logo está fora de escopo. |
|
||||
| `divert-to` / tag `divert` | `pass in … divert-to <host> port <n>` | M4 | **VERIFIED-in-VM** — gate `11-divert.sh`. O módulo registra uma família de sockets `AF_DIVERT` (`PF_DIVERT=32`) em runtime — sem patch no kernel. Uma regra `divert-to` entrega o pacote a essa família; sem listener o pacote é descartado (`divs_noport`, paridade com o BSD); com o `tools/pdivert` rodando o pacote vai para o userspace, é reescrito e reinjetado (verificado com mutação do payload + correção de checksum, ping com 0% de perda). |
|
||||
| Filas (`queue`, `queue on`, `pfctl -s queue -v`) | `queue rootq on eth2 bandwidth 10Mbit` + `queue leafq on eth2 bandwidth 2Mbit parent rootq default` | M5 | **VERIFIED-in-VM** — gate `15-queue.sh`: a configuração de filas carrega, a disciplina hfsc é anexada à interface, `pfctl -s queue -v` lista as duas classes com estatísticas, um fluxo de 2 MB pela fila completa, e o contador de pacotes da classe avança (o escalonador está no caminho de dados). Note que `bandwidth` é *linkshare* do HFSC — garantia sob contenção, não teto: o pf.conf do OpenBSD 8.0 não tem `minimum`/`maximum`, então um fluxo isolado não é limitado, nem no Linux nem no OpenBSD. |
|
||||
| HFSC | `queue on wan { hfsc … }` | M5 | **VERIFIED-in-VM** — o `pfsrc/hfsc.c` (código real do OpenBSD 8.0) está na lista de objetos do módulo e é a disciplina que o gate exercita. As classes usam o `net/hfsc.h` vendorizado (classe raiz `0x10000`, classe default `0x1000`) compartilhado com o `pfctl`, então a ABI de estatísticas bate nos dois lados. |
|
||||
| FQ-CoDel | `queue on wan { fq_codel … }` | M5 | COMPILES-untested — o `pfsrc/fq_codel.c` é compilado dentro do `pf.ko` e o `net/fq_codel.h` vendorizado é compartilhado com o `pfctl`, mas nenhum gate o exercita. |
|
||||
| Interface `pfq` | n/a (interfaces BSD `ifq`/`pfq`, não um qdisc `tc` do Linux) | M5 | **VERIFIED-in-VM** — o port mantém a forma do BSD: `compat/pfk_ifq.c` implementa as interfaces `ifq_ops`/`pfq_ops` e os back ends do OpenBSD se plugam nelas (`pfq` nunca foi um qdisc `tc` do Linux, nem nunca pretendeu ser). priq é a disciplina default. |
|
||||
| pflog (`log`, `log all`, `block log`) + pcap do `pflogd` (DLT_PFLOG) | `pass out quick log` + `pflogd /tmp/x.pcap` | M4 | **VERIFIED-in-VM** — gate `12-pflog.sh`: os pacotes logados são enfileirados pelo engine, lidos por `/dev/pflog` e escritos como pcap com linktype DLT_PFLOG (117); o dump contém os bytes reais do pacote. Divergência: um chardev em vez de uma interface if_pflog/bpf (o Linux não tem bpf sobre uma interface virtual dessas aqui); o layout do registro é byte a byte compatível com o `pflog(4)` do OpenBSD. O `if_pflog.c` continua fora da build. |
|
||||
|
||||
## Fora de escopo (explícito)
|
||||
|
||||
| Item | Motivo |
|
||||
|---|---|
|
||||
| Failover `pfsync` / CARP | fora de escopo (spec §3) |
|
||||
| IPsec / pfkey | fora de escopo |
|
||||
| `ftp-proxy` e daemons de userland | fora de escopo |
|
||||
| Instâncias PF por netns | port fiel = uma instância global no `init_net` |
|
||||
| Agendadores exclusivos do ALTQ clássico (cbq/wfq/red…) | removidos upstream antes do OpenBSD 8.0 — impossíveis de portar a partir da base |
|
||||
| Routing labels (`route-label`) | fora de escopo; a camada de ioctl rejeita regras com label |
|
||||
| `af-to` (tradução IPv4↔IPv6) | o código está sob `#ifdef INET6` e este build tem `INET6 0`; habilitá-lo é um milestone à parte, não uma feature faltando na base |
|
||||
@@ -0,0 +1,111 @@
|
||||
# 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`, `hfsc.c`/`fq_codel.c` (back ends de fila, no módulo), `divert_sock.c` (família AF_DIVERT), `pfk_pflog.c` (back end do pflog), `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 da sintaxe `queue`/`queue on` do OpenBSD 8.0
|
||||
e o kernel a implementa na forma do BSD: `compat/pfk_ifq.c` fornece as
|
||||
interfaces `ifq_ops`/`pfq_ops` e os back ends do OpenBSD (`pfsrc/hfsc.c`,
|
||||
`pfsrc/fq_codel.c`) se plugam nelas; **priq** é a disciplina default. O
|
||||
gate `15-queue.sh` prova a disciplina **hfsc** de ponta a ponta: a
|
||||
configuração de filas carrega, a disciplina é anexada à interface, o
|
||||
`pfctl -s queue -v` lista as duas classes com estatísticas, um fluxo de 2 MB
|
||||
pela fila completa e o contador de pacotes da classe avança. Os handles de
|
||||
classe e as structs de estatísticas vêm do próprio `net/hfsc.h` e
|
||||
`net/fq_codel.h` do OpenBSD, vendorizados para que kernel e `pfctl` não
|
||||
puedan divergir.
|
||||
- **Divert**: `divert-to`/tag `divert` produzem o veredito `PF_DIVERT` do PF e
|
||||
o módulo registra uma família de sockets `AF_DIVERT` (`PF_DIVERT=32`) em
|
||||
runtime — sem patch no kernel. Sem listener o pacote é descartado
|
||||
(`divs_noport`, paridade com o BSD); com o relay `pdivert` rodando o pacote
|
||||
vai para o userspace, é reescrito e reinjetado. Gate `11-divert.sh`.
|
||||
- **pflog**: o engine enfileira os pacotes logados, `pfsrc/pfk_pflog.c` os
|
||||
expõe por `/dev/pflog` e o `tools/pflogd` escreve um pcap DLT_PFLOG cujo
|
||||
layout de registro é byte a byte compatível com o `pflog(4)` do OpenBSD.
|
||||
Gate `12-pflog.sh`. A divergência em relação ao upstream é o transporte (um
|
||||
chardev em vez de uma interface `if_pflog`/bpf), não o formato.
|
||||
|
||||
## Milestones (status por feature em feature-matrix.md)
|
||||
|
||||
| Milestone | Escopo | Status |
|
||||
|---|---|---|
|
||||
| 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 do filtro: regras/estados/tabelas/âncoras, gates VM | **pronto** — gates 01–04 verdes |
|
||||
| M3 | NAT (`nat-to`/`rdr-to`/`binat-to`), scrub, pflog | **pronto** — gates 05/06/07/09 (incl. integridade de 2 MB via redirect) e pflog gate 12 |
|
||||
| M4 | route-to/dup-to/reply-to, pools, divert e2e | **pronto** — gates 08/10/13 e divert gate 11 |
|
||||
| M5 | filas: back ends ifq (hfsc/fq_codel) | **concluído (mecânico)** — gate 15: o hfsc é anexado, `pfctl -s queue -v` mostra as stats das classes, um fluxo de 2 MB pela fila é contado pela classe. `bandwidth` = linkshare do HFSC (garantia sob contenção, não teto) |
|
||||
| M6 | docs completas, patchset limpo, suíte verde, releases com tag | **concluído** — docs EN+PT-BR, suíte 16/16 verde, tag `v1.0.0` |
|
||||
|
||||
## 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).
|
||||
@@ -0,0 +1,119 @@
|
||||
# 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-12)
|
||||
|
||||
- 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 todas as ferramentas de userland: os alvos de
|
||||
`make -C tools` são `pfctl`, `pdivert`, `pflogd` e o verificador de ABI
|
||||
(`abitest`, `abi`, `test`, `clean`).
|
||||
- Depois do 2.5, todo o conjunto de features é usável e coberto pela suíte do
|
||||
lab — filtragem com estado, tabelas e anchors, NAT (`nat-to`/`rdr-to`/
|
||||
`binat-to` e pools), scrub, roteamento forçado (`route-to`/`dup-to`/
|
||||
`reply-to`), `divert`, `pflog` e as filas do OpenBSD 8.0 (HFSC). A
|
||||
[matriz de features](feature-matrix.md) diz qual gate prova o quê; leia
|
||||
[pf-guide.md](pf-guide.md) para conhecer as divergências antes de habilitar
|
||||
o PF num caminho que você precisa manter vivo.
|
||||
|
||||
## 6.1 Opcional: os screencasts narrados
|
||||
|
||||
```sh
|
||||
export MINIMAX_API_KEY=... # TTS do MiniMax para a narração
|
||||
./scripts/vm-create.sh # o lab precisa estar no ar
|
||||
./scripts/screencast/build-all.sh # -> out/screencast/{en,pt}/*.mp4
|
||||
```
|
||||
|
||||
O pipeline grava sessões shell reais contra o lab, gera a narração com uma
|
||||
voz feminina do MiniMax (inglês e português) e renderiza MP4 1080p30 com
|
||||
legendas queimadas e o diagrama de rede do lab. Detalhes:
|
||||
[screencast.md](screencast.md).
|
||||
|
||||
## 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) |
|
||||
@@ -0,0 +1,74 @@
|
||||
# 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: `scripts/apply-patches.sh`, `scripts/unpatch.sh` e
|
||||
> `patches/kernel/series` **estão na árvore**. O `series` é vazio por projeto,
|
||||
> então aplicá-lo é um no-op verificado (`PATCHES_APPLIED=0`). Quando um patch
|
||||
> real for necessário, o commit que o adiciona também atualiza o `series` e
|
||||
> 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. |
|
||||
@@ -0,0 +1,101 @@
|
||||
# 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 núcleo de filtragem
|
||||
(pass/block/quick/keep state/tabelas/anchors), a família de NAT, o scrub, o
|
||||
roteamento forçado, os pools, o `divert`, o `pflog` e as filas do OpenBSD
|
||||
8.0 têm todos **evidência em VM** — os 16 gates do lab estão verdes. O que
|
||||
*não* tem gate está listado explicitamente abaixo. 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 lab
|
||||
> *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. 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.
|
||||
|
||||
**Sem gate** (lacunas honestas): o caminho IPv6, o fingerprint de OS, as
|
||||
opções `set` acima, os syncookies e a disciplina FQ-CoDel. O `af-to` está
|
||||
compilado fora neste build (`INET6 0`).
|
||||
|
||||
## Notas por feature — o que cada sintaxe faz hoje
|
||||
|
||||
| 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>)`. O `binat-to` é expandido pelo pfctl num par `nat-to … static-port` + `rdr-to` (gate `07-binat`). |
|
||||
| `scrub (min-ttl, max-mss, df, random-id)`, `set reassemble` | — | **Verificado em lab** (gate `09-scrub.sh`): `min-ttl` e `max-mss` reescrevem de fato pacotes em trânsito. || `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`, `reply-to` | — | **Verificado em lab** (gates `08-routeto.sh`, `13-replyto.sh`): o gateway forçado é usado em vez do egress normal, `dup-to` copia mantendo o fluxo, e `reply-to` empurra as respostas de um fluxo para o enlace do gateway. `fail-to` não é palavra-chave no OpenBSD 8.0 (removido upstream). |
|
||||
| `queue` / `queue on` / `pfctl -s queue` | — | **Verificado em lab** (gate `15-queue.sh`): as filas carregam, o hfsc é anexado, `pfctl -s queue -v` mostra as estatísticas das classes e um fluxo de 2 MB pela fila é contado pela classe. `bandwidth` é *garantia sob contenção*, não teto - o pf.conf 8.0 não tem palavra-chave de upperlimit. |
|
||||
| `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).
|
||||
@@ -0,0 +1,123 @@
|
||||
# Screencasts / Vídeos da demonstração
|
||||
|
||||
> PT-BR: esta página · EN: [docs/en/screencast.md](../en/screencast.md)
|
||||
|
||||
Sete vídeos por idioma, com **narração de voz feminina** (MiniMax), **legendas
|
||||
queimadas**, **diagrama de rede do lab** e um **filme completo** com transições
|
||||
entre as fases. 1920×1080 @ 30fps, H.264/MP4 + AAC — prontos para subir no
|
||||
YouTube.
|
||||
|
||||
Cada vídeo é a gravação de uma **sessão shell real**: uma conexão SSH de
|
||||
verdade ao firewall Alpine, com os comandos digitados tecla a tecla e a saída
|
||||
do kernel chegando em tempo real. Nada é simulado.
|
||||
|
||||
## As fases
|
||||
|
||||
| # | Vídeo | O que mostra |
|
||||
|---|-------|--------------|
|
||||
| 0 | `00-ambiente.mp4` | O lab: 4 VMs Alpine sob libvirt, as quatro interfaces do firewall e o diagrama de rede completo |
|
||||
| 1 | `01-implementacao.mp4` | A implementação no kernel: fontes do OpenBSD 8.0 + camada de compatibilidade = `pf.ko` |
|
||||
| 2 | `02-ativacao.mp4` | `insmod pf.ko`, `/dev/pf`, `pfctl -e`, `pfctl -s info` |
|
||||
| 3 | `03-regras.mp4` | Regras básicas: tabela, anchor, `keep state`, `block drop` (o ping morre) |
|
||||
| 4 | `04-roteamento.mp4` | `route-to` e `reply-to`, com o diagrama mostrando o caminho real do pacote |
|
||||
| 5 | `05-balanceamento.mp4` | Pool `round-robin`, pool `source-hash` e `dup-to` |
|
||||
| 6 | `06-qos.mp4` | Filas `hfsc` do OpenBSD 8.0 e uma transferência de 2 MB pela classe |
|
||||
|
||||
Mais `pf-on-linux-full.mp4`: o filme completo, com as sete fases emendadas por
|
||||
transições (crossfade sobre um cartão de capítulo).
|
||||
|
||||
## Vozes MiniMax
|
||||
|
||||
| Idioma | Voz | Id |
|
||||
|--------|-----|-----|
|
||||
| Inglês (en_US) | Confident Woman | `English_ConfidentWoman` |
|
||||
| Português (pt_BR) | Confident Woman | `Portuguese_ConfidentWoman` |
|
||||
|
||||
O áudio é gerado pelo MiniMax TTS, **um arquivo por segmento** de fala. Como
|
||||
cada segmento corresponde a uma batida da sessão, a voz começa exatamente
|
||||
quando a ação correspondente aparece na tela.
|
||||
|
||||
## Como regravar
|
||||
|
||||
```sh
|
||||
# tudo: áudio -> sessões -> vídeos -> filme completo
|
||||
./scripts/screencast/build-all.sh
|
||||
|
||||
# uma fase só
|
||||
./scripts/screencast/build-all.sh 04-roteamento
|
||||
```
|
||||
|
||||
Etapas individuais:
|
||||
|
||||
```sh
|
||||
python3 scripts/screencast/make_audio.py --lang pt # áudio MiniMax
|
||||
python3 scripts/screencast/record.py --plan scripts/screencast/plans/04-roteamento.json \\
|
||||
--out out/screencast/caps/04-roteamento.cast --pace --ensure-pf
|
||||
python3 scripts/screencast/assemble.py --phase 04-roteamento --lang pt
|
||||
python3 scripts/screencast/join.py --lang pt
|
||||
```
|
||||
|
||||
### Como o pipeline funciona
|
||||
|
||||
```
|
||||
planos/*.json --record.py--> caps/*.cast --render_video.py--> vídeo mudo
|
||||
(comandos) (pty real) (asciicast) (pyte + PIL) |
|
||||
|
|
||||
narracao/*.json --make_audio.py--> vo/<fase>.<lang>/*.mp3 ----------+
|
||||
(MiniMax TTS) |
|
||||
assemble.py: mix + legendas
|
||||
|
|
||||
join.py: transições
|
||||
```
|
||||
|
||||
Pontos que importam:
|
||||
|
||||
- **Sessão real.** `record.py` abre um pty, faz SSH na VM e digita os comandos
|
||||
um caractere por vez (~34 c/s, com jitter). O `bash --noediting` evita que o
|
||||
editor de linha redesenhe o comando e o tty o repita.
|
||||
- **Pacing.** A gravação segura a tela enquanto a voz fala: cada batida dura no
|
||||
máximo o trecho de áudio que a acompanha (o maior entre EN e PT), para uma
|
||||
única captura servir as duas versões.
|
||||
- **Legendas.** O texto da narração é queimado no vídeo, na língua da trilha.
|
||||
- **Diagrama.** Nas fases 0, 4 e 5 o mapa do lab é desenhado sobre o terminal,
|
||||
e o caminho em discussão fica destacado (eth1/eth2/eth3).
|
||||
|
||||
Requisitos: `ffmpeg`, `python3` com `PIL` e `pyte`, a fonte DejaVu, a chave
|
||||
`MINIMAX_API_KEY` no ambiente, e o lab de VMs no ar.
|
||||
|
||||
## Onde ficam os arquivos
|
||||
|
||||
| Caminho | Conteúdo |
|
||||
|---------|----------|
|
||||
| `out/screencast/en/`, `out/screencast/pt/` | os vídeos finais |
|
||||
| `out/screencast/caps/` | as capturas asciicast das sessões |
|
||||
| `out/screencast/vo/` | o áudio gerado pelo MiniMax |
|
||||
| `scripts/screencast/plans/` | o roteiro de comandos de cada fase |
|
||||
| `scripts/screencast/narration/` | os textos da narração (EN e PT) |
|
||||
|
||||
## Texto de descrição (YouTube)
|
||||
|
||||
```
|
||||
PF on Linux - o motor do OpenBSD PF 8.0 dentro do kernel Linux
|
||||
|
||||
Port completo do Packet Filter do OpenBSD 8.0 para o kernel Linux 7.3.4,
|
||||
empacotado como módulo (pf.ko) e controlado pelo pfctl original do OpenBSD
|
||||
sobre a ABI de ioctls do /dev/pf.
|
||||
|
||||
O lab é real: 4 VMs Alpine sob libvirt, kernel compilado do fonte com o
|
||||
módulo, tráfego real entre cliente, firewall e servidor.
|
||||
|
||||
Fases:
|
||||
0. O ambiente de testes - as 4 VMs e o diagrama de rede
|
||||
1. Implementação no kernel - das fontes OpenBSD ao pf.ko
|
||||
2. Ativação - insmod, /dev/pf, pfctl -e, pfctl -s info
|
||||
3. Regras básicas - tabelas, anchors, keep state, block drop
|
||||
4. Roteamento - route-to e reply-to, com o caminho real no diagrama
|
||||
5. Balanceamento - pools round-robin, source-hash e dup-to
|
||||
6. QOS - filas hfsc do OpenBSD 8.0 no caminho de dados
|
||||
|
||||
Suíte automatizada: 15 gates, todos verdes.
|
||||
Código e documentação: https://git.labexposed.com/lgcosta/pf-linux-port
|
||||
|
||||
#linux #kernel #openbsd #pf #firewall #netfilter #screencast
|
||||
```
|
||||
@@ -0,0 +1,171 @@
|
||||
# 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`.
|
||||
|
||||
**Do pf0 para as outras VMs.** O firewall tem seu próprio par de chaves e os
|
||||
pares confiam nele, então uma sessão no pf0 pode pilotar o cliente e o
|
||||
servidor diretamente — é isso que os screencasts fazem
|
||||
(`ssh cli 'ping …'`):
|
||||
|
||||
```sh
|
||||
# uma vez por lab, a partir do hypervisor
|
||||
ssh pf0 'ssh-keygen -t ed25519 -N "" -C pf0 -f /root/.ssh/id_ed25519'
|
||||
# depois autorizar essa chave pública no cli, no srv e no gw2
|
||||
```
|
||||
|
||||
O `/root/.ssh/config` do pf0 mapeia os nomes curtos `cli`, `srv` e `gw2`
|
||||
para 10.0.1.10, 10.0.2.20 e 10.0.3.2, e o `/etc/hosts` traz o mesmo
|
||||
mapeamento.
|
||||
|
||||
## 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
|
||||
|
||||
Cada gate afirma **tráfego real e estado observável**, nunca apenas um código
|
||||
de saída: o pacote chega, é descartado ou é traduzido, e a prova é lida de
|
||||
volta nos contadores do próprio firewall, na tabela de estados, em capturas de
|
||||
pacote ou no par.
|
||||
|
||||
A lista completa está na §6 (16 gates, todos verdes). Cada gate é um script
|
||||
shell em `tests/vm/` que fala com as VMs através do deb com ssh aninhado,
|
||||
usando os helpers de `tests/vm/lib.sh` (`pf0`, `cli`, `srv`, `gw2`, `pfput`,
|
||||
`pfload`, `ok`, `bad`). O `scripts/vm-run-tests.sh` roda tudo em ordem e
|
||||
guarda `out/test-logs/<gate>.sh.log`.
|
||||
|
||||
O que **não** tem gate (lacunas honestas): o caminho IPv6, o fingerprint de
|
||||
OS, as opções `set` (`state-policy`, `allow-opts`) e os syncookies — o código
|
||||
compila dentro do `pf.ko`, mas nenhum gate os exercita. O FQ-CoDel compila e
|
||||
compartilha o header de estatísticas com o `pfctl`, mas só a disciplina
|
||||
**hfsc** é exercitada.
|
||||
|
||||
**Não existe gate numérico de performance**: a decisão de design (spec §7) é
|
||||
que *os gates funcionais são a régua* — um contrato de performance forçaria um
|
||||
shim reescrito, pouco fiel. O que existe é um **teste de stress**
|
||||
(`tests/vm/16-stress.sh`, disparado por `scripts/stress/run-stress.sh`) que
|
||||
afere **invariantes sob carga** — sem vazamento de estados/tabelas, sem falha
|
||||
de carga de regras, payload idêntico sob um stream saturando o link, sem
|
||||
`BUG/WARNING/Oops`, o firewall ainda roteando — e **reporta** a comparação de
|
||||
vazão (baseline sem o módulo vs. com PF ligado) como informação, sem meta
|
||||
numérica de pass/fail. O relatório e o log bruto ficam em
|
||||
`out/stress/<timestamp>/`.
|
||||
|
||||
## 6. Status atual da suíte (2026-11-12)
|
||||
|
||||
**16/16 gates verdes.** Uma rodada completa e limpa
|
||||
(`./scripts/vm-run-tests.sh`, ~13 min) recria e reinicia o `pftest-pf0` antes
|
||||
de cada gate, reimplanta o módulo e as ferramentas, e termina com
|
||||
`PASS=16 FAIL=0`. Os logs capturados ficam em
|
||||
`out/test-logs/<gate>.sh.log`.
|
||||
|
||||
| Gate | O que prova hoje |
|
||||
|---|---|
|
||||
| `01-state.sh` | `keep state` em um ping de trânsito; o estado aparece no `pfctl -ss` |
|
||||
| `02-block.sh` | `block drop` mata o ping; `block return-rst` devolve RST ao cliente |
|
||||
| `03-tables.sh` | uma tabela `pfr` bloqueia um host; um `-T delete` ao vivo libera o mesmo fluxo |
|
||||
| `04-anchors.sh` | a regra de um anchor é avaliada antes de um `block` posterior do ruleset principal |
|
||||
| `05-nat.sh` | NAT de origem: o pacote sai com o endereço do pool e a resposta é des-NATeada |
|
||||
| `06-rdr.sh` | redirect de porta de ponta a ponta, mais 2 MB passando com integridade byte a byte |
|
||||
| `07-binat.sh` | `binat-to`: o par vê o endereço mapeado e o original nunca vaza |
|
||||
| `08-routeto.sh` | `route-to` sai pelo link do gateway; `dup-to` copia e mantém o fluxo |
|
||||
| `09-scrub.sh` | `min-ttl` e `max-mss` medidos no egresso do próprio firewall |
|
||||
| `10-pools.sh` | seleção do pool de NAT (`round-robin`, `source-hash`) |
|
||||
| `11-divert.sh` | `divert-to` para o relay `pdivert`: o pacote vai para o userspace e volta |
|
||||
| `12-pflog.sh` | os pacotes logados chegam a `/dev/pflog` e viram um pcap DLT_PFLOG |
|
||||
| `13-replyto.sh` | `reply-to` força a resposta para o link do gateway |
|
||||
| `14-soak.sh` | reload de ruleset sob tráfego, ciclo de `rmmod`, checagem de vazamento |
|
||||
| `15-queue.sh` | filas hfsc: anexação, estatísticas da classe, um fluxo de 2 MB contado pela classe |
|
||||
| `16-stress.sh` | stress: vazão baseline vs. PF, churn de estados/regras/tabelas com verificação de vazamento, 2 MB por NAT sob stream saturante, saúde do dmesg (rodado por `scripts/stress/run-stress.sh`, que grava um relatório) |
|
||||
|
||||
Os screencasts ([screencast.md](screencast.md)) mostram boa parte desses
|
||||
gates sendo executados, com o diagrama de rede do lab desenhado sobre o
|
||||
terminal.
|
||||
|
||||
## 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
@@ -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 pfsrc/fq_codel.o pfsrc/hfsc.o compat/pfk_ifq.o | awk '!x[$$0]++ { print("./"$$0) }' > pf.mod
|
||||
+1
-1
@@ -20,7 +20,7 @@ pf-objs := pfsrc/pfk_mod.o pfsrc/pfk_hooks.o \
|
||||
# ported OpenBSD 8.0 engine
|
||||
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_ioctl.o pfsrc/pf.o pfsrc/divert_sock.o
|
||||
pfsrc/pf_ioctl.o pfsrc/pf.o pfsrc/divert_sock.o pfsrc/pfk_pflog.o pfsrc/fq_codel.o pfsrc/hfsc.o
|
||||
|
||||
# queueing framework (compat/pfk_ifq.c implements the ifq API with priq
|
||||
# semantics; the OpenBSD hfsc/fq_codel back ends land in milestone M5)
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/md5.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/md5.o: $(deps_compat/md5.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/pfk_if.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/pfk_if.o: $(deps_compat/pfk_if.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/pfk_ifq.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/pfk_ifq.o: $(deps_compat/pfk_ifq.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/pfk_ip4.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/pfk_ip4.o: $(deps_compat/pfk_ip4.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/pfk_ip6.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/pfk_ip6.o: $(deps_compat/pfk_ip6.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/pfk_kern.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/pfk_kern.o: $(deps_compat/pfk_kern.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/pfk_mbuf.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/pfk_mbuf.o: $(deps_compat/pfk_mbuf.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/pfk_pcb.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
/home/lgcosta/lab/linux_kernel/linux-7.3.4/include/net/inet6_hashtables.h \
|
||||
|
||||
compat/pfk_pcb.o: $(deps_compat/pfk_pcb.o)
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/pfk_rtable.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/pfk_rtable.o: $(deps_compat/pfk_rtable.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,9 @@ deps_compat/pfk_xmit.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
include/pfk_api.h \
|
||||
|
||||
compat/pfk_xmit.o: $(deps_compat/pfk_xmit.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/radix.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/radix.o: $(deps_compat/radix.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/sha2.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/sha2.o: $(deps_compat/sha2.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/siphash.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/siphash.o: $(deps_compat/siphash.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/subr_tree.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
compat/subr_tree.o: $(deps_compat/subr_tree.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_compat/toeplitz.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
/home/lgcosta/lab/linux_kernel/linux-7.3.4/include/crypto/hash.h \
|
||||
/home/lgcosta/lab/linux_kernel/linux-7.3.4/include/linux/crypto.h \
|
||||
|
||||
|
||||
+103
-27
@@ -217,10 +217,14 @@ pfk_pfq_enqueue(void *arg, struct mbuf *m)
|
||||
struct pfk_pfq *pfq = arg;
|
||||
|
||||
if (!pfq)
|
||||
return NULL;
|
||||
if (ifq_enqueue(&pfq->ifq, m) != 0)
|
||||
return NULL;
|
||||
return m;
|
||||
return m; /* caller keeps ownership */
|
||||
/*
|
||||
* ifq_enqueue takes ownership of m (the scheduler may drop it); we then
|
||||
* drain immediately, so nothing is returned for the caller to send.
|
||||
*/
|
||||
ifq_enqueue(&pfq->ifq, m);
|
||||
ifq_start(&pfq->ifq);
|
||||
return NULL;
|
||||
}
|
||||
|
||||
static struct mbuf *
|
||||
@@ -273,10 +277,11 @@ static const struct pfq_ops pfk_priq_pfq_ops = {
|
||||
* packets are still queued, but the traffic shaping curves are not yet
|
||||
* applied — recorded in the feature matrix as pending M5).
|
||||
*/
|
||||
const struct ifq_ops * const ifq_hfsc_ops = &pfk_priq_ifq_ops;
|
||||
const struct ifq_ops * const ifq_fqcodel_ops = &pfk_priq_ifq_ops;
|
||||
const struct pfq_ops * const pfq_hfsc_ops = &pfk_priq_pfq_ops;
|
||||
const struct pfq_ops * const pfq_fqcodel_ops = &pfk_priq_pfq_ops;
|
||||
/*
|
||||
* M5: the real scheduler back ends (pfsrc/hfsc.c, pfsrc/fq_codel.c) define
|
||||
* ifq_hfsc_ops/pfq_hfsc_ops/ifq_fqcodel_ops/pfq_fqcodel_ops themselves; the
|
||||
* priq shim above stays as the default for interfaces without a queue rule.
|
||||
*/
|
||||
|
||||
/* ---------------- framework ---------------- */
|
||||
void
|
||||
@@ -302,7 +307,36 @@ ifq_attach(struct ifqueue *ifq, const struct ifq_ops *ops, void *opsarg)
|
||||
if (!opsarg && ops->ifqop_alloc)
|
||||
opsarg = ops->ifqop_alloc(0, NULL);
|
||||
ifq->ifq_ops = ops;
|
||||
/*
|
||||
* The port's own helpers use ifq_softc; the staged OpenBSD schedulers
|
||||
* (hfsc/fq_codel) read ifq->ifq_q. Keep both in sync or the back ends
|
||||
* dereference a NULL scheduler state.
|
||||
*/
|
||||
ifq->ifq_softc = opsarg;
|
||||
ifq->ifq_q = opsarg;
|
||||
}
|
||||
|
||||
/*
|
||||
* Scheduler hand-off used by the ported back ends (hfsc/fq_codel) when they
|
||||
* need their per-interface state. PFLINUX: the port has no ifq mutex (the
|
||||
* data path is a single ordered work queue), so "enter" is a plain ownership
|
||||
* check and "leave" is a no-op - the pair exists to mirror OpenBSD's API.
|
||||
*/
|
||||
void *
|
||||
ifq_q_enter(struct ifqueue *ifq, const struct ifq_ops *ops)
|
||||
{
|
||||
if (ifq == NULL || ops == NULL || ifq->ifq_ops != ops)
|
||||
return NULL; /* another scheduler owns it */
|
||||
if (ifq->ifq_softc == NULL && ops->ifqop_alloc)
|
||||
ifq->ifq_softc = ops->ifqop_alloc(0, NULL);
|
||||
return ifq->ifq_softc;
|
||||
}
|
||||
|
||||
void
|
||||
ifq_q_leave(struct ifqueue *ifq, void *q)
|
||||
{
|
||||
(void)ifq;
|
||||
(void)q;
|
||||
}
|
||||
|
||||
void
|
||||
@@ -312,19 +346,35 @@ ifq_destroy(struct ifqueue *ifq)
|
||||
ifq->ifq_ops->ifqop_free(0, ifq->ifq_softc);
|
||||
ifq->ifq_ops = NULL;
|
||||
ifq->ifq_softc = NULL;
|
||||
ifq->ifq_q = NULL;
|
||||
}
|
||||
|
||||
/*
|
||||
* ifqop_enq returns the packet the scheduler decided to DROP (possibly the one
|
||||
* just offered), and NULL when the packet was accepted - it is NOT an error
|
||||
* code. Freeing the returned mbuf is this layer's job.
|
||||
*/
|
||||
int
|
||||
ifq_enqueue(struct ifqueue *ifq, struct mbuf *m)
|
||||
{
|
||||
if (!ifq->ifq_ops || !ifq->ifq_ops->ifqop_enq)
|
||||
struct mbuf *dm;
|
||||
|
||||
if (!ifq->ifq_ops || !ifq->ifq_ops->ifqop_enq) {
|
||||
m_freem(m);
|
||||
return EINVAL;
|
||||
}
|
||||
if (ifq->ifq_maxlen && ifq->ifq_len >= ifq->ifq_maxlen) {
|
||||
ifq->ifq_errors++;
|
||||
ifq->ifq_qdrops++;
|
||||
m_freem(m);
|
||||
return ENOBUFS;
|
||||
}
|
||||
return ifq->ifq_ops->ifqop_enq(ifq, m) ? 0 : ENOMEM;
|
||||
dm = ifq->ifq_ops->ifqop_enq(ifq, m);
|
||||
if (dm) {
|
||||
ifq->ifq_qdrops++;
|
||||
m_freem(dm);
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
|
||||
struct mbuf *
|
||||
@@ -336,14 +386,16 @@ ifq_deq_begin(struct ifqueue *ifq)
|
||||
if (!ifq->ifq_ops || !ifq->ifq_ops->ifqop_deq_begin)
|
||||
return NULL;
|
||||
m = ifq->ifq_ops->ifqop_deq_begin(ifq, &cookie);
|
||||
ifq->ifq_dequeue = cookie;
|
||||
return m;
|
||||
}
|
||||
|
||||
void
|
||||
ifq_deq_commit(struct ifqueue *ifq, struct mbuf *m)
|
||||
{
|
||||
void *cookie = NULL;
|
||||
void *cookie = ifq->ifq_dequeue;
|
||||
|
||||
ifq->ifq_dequeue = NULL;
|
||||
if (ifq->ifq_ops && ifq->ifq_ops->ifqop_deq_commit)
|
||||
ifq->ifq_ops->ifqop_deq_commit(ifq, m, cookie);
|
||||
}
|
||||
@@ -365,12 +417,52 @@ ifq_dequeue(struct ifqueue *ifq)
|
||||
return m;
|
||||
}
|
||||
|
||||
/*
|
||||
* Drain the queue as far as the scheduler allows and hand each packet to the
|
||||
* stack's output path. OpenBSD calls if_start from softint context; here it
|
||||
* runs either from the pf work queue (enqueue side) or from the scheduler's
|
||||
* deferred timeout (pacing side), which is what makes hfsc's bandwidth
|
||||
* limits take effect.
|
||||
*/
|
||||
void
|
||||
ifq_start(struct ifqueue *ifq)
|
||||
{
|
||||
struct mbuf *m;
|
||||
int n;
|
||||
|
||||
n = 0;
|
||||
ifq->ifq_oactive = 1;
|
||||
while ((m = ifq_dequeue(ifq)) != NULL) {
|
||||
n++;
|
||||
if (pfk_ifq_transmit(ifq, m))
|
||||
break; /* device busy: packet kept */
|
||||
}
|
||||
ifq->ifq_oactive = 0;
|
||||
}
|
||||
|
||||
/*
|
||||
* pf data-path entry: hand a packet to the interface's scheduler when one is
|
||||
* attached (a pf `queue' rule is configured). Returns 1 when the queue took
|
||||
* ownership of m, 0 when the caller must keep going (priq/no scheduler).
|
||||
*/
|
||||
int
|
||||
pf_kifq_input(struct pfk_ifnet *ifp, struct mbuf *m)
|
||||
{
|
||||
struct ifqueue *ifq;
|
||||
|
||||
if (ifp == NULL || m == NULL)
|
||||
return 0;
|
||||
if (ifp == NULL)
|
||||
return 0;
|
||||
ifq = &ifp->if_snd;
|
||||
if (ifq->ifq_ops == NULL || ifq->ifq_ops == ifq_priq_ops)
|
||||
return 0; /* no scheduler: fast path */
|
||||
if (ifq_enqueue(ifq, m) != 0)
|
||||
return 1; /* dropped by the queue: owned */
|
||||
ifq_start(ifq);
|
||||
return 1;
|
||||
}
|
||||
|
||||
unsigned int
|
||||
ifq_purge(struct ifqueue *ifq)
|
||||
{
|
||||
@@ -423,19 +515,3 @@ ifq_hdatalen(struct ifqueue *ifq)
|
||||
return 0;
|
||||
}
|
||||
|
||||
/* ---------------- scheduler back ends (milestone M5) ---------------- */
|
||||
/* The staged OpenBSD hfsc.c/fq_codel.c are not in the build yet; the priq
|
||||
* ops above are the active scheduler. These wrappers keep pf_ioctl's
|
||||
* initialisation calls valid until M5 replaces them with the ported
|
||||
* schedulers (docs/porting-notes.md). */
|
||||
void
|
||||
hfsc_initialize(void)
|
||||
{
|
||||
pr_info("pfk: hfsc back end pending M5 (priq active)\n");
|
||||
}
|
||||
|
||||
void
|
||||
fq_codel_initialize(void)
|
||||
{
|
||||
pr_info("pfk: fq_codel back end pending M5 (priq active)\n");
|
||||
}
|
||||
+17
-15
@@ -47,8 +47,21 @@ pfk_printk_compat(const char *fmt, ...)
|
||||
void
|
||||
splassert_fail(int expected, int actual, const char *func)
|
||||
{
|
||||
pr_err("splassert: %s: expected %d, got %d\n", func, expected, actual);
|
||||
BUG();
|
||||
/*
|
||||
* PFLINUX: OpenBSD's splassert() checks a per-CPU spl level, so
|
||||
* "assert unlocked" really means "this context did not take the lock".
|
||||
* The port replaced spl with rw-semas plus work queues, where
|
||||
* rw_status() is a global counter: an assert-unlocked in a work-queue
|
||||
* task fires whenever *another* CPU happens to hold the lock, which is
|
||||
* not a bug (the task never acquires pf_lock itself) and was turning a
|
||||
* harmless race into a kernel BUG() that wedged the module in
|
||||
* "Unloading". Report it once instead of killing the host; the
|
||||
* structural invariant the BSD assert protects - purge never runs while
|
||||
* holding pf_lock - is upheld by the call sites (pf_purge_* are only
|
||||
* reached from systqmp tasks and timer work).
|
||||
*/
|
||||
pr_warn_ratelimited("pfk: splassert: %s: expected %d, got %d\n",
|
||||
func, expected, actual);
|
||||
}
|
||||
|
||||
/* ---------------- addlog (OpenBSD kern.log) ---------------- */
|
||||
@@ -619,16 +632,5 @@ if_congested(void)
|
||||
}
|
||||
|
||||
|
||||
/* ---------------- pflog (netlink backend, milestone M4) ---------------- */
|
||||
/* 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);
|
||||
}
|
||||
/* pflog_packet() lives in pfsrc/pfk_pflog.c (the /dev/pflog backend). */
|
||||
|
||||
@@ -607,3 +607,14 @@ pfk_mbuf_exit(void)
|
||||
{
|
||||
kmem_cache_destroy(pfk_mbuf_cache);
|
||||
}
|
||||
|
||||
void
|
||||
ml_purge(struct mbuf_list *ml)
|
||||
{
|
||||
struct mbuf *m;
|
||||
|
||||
while ((m = ml_dequeue(ml)) != NULL)
|
||||
m_freem(m);
|
||||
ml->ml_first = ml->ml_last = NULL;
|
||||
ml->ml_len = 0;
|
||||
}
|
||||
@@ -6,6 +6,7 @@
|
||||
* ip6_route_output, tcp_v4_send_reset if needed).
|
||||
*/
|
||||
#include <pfk.h>
|
||||
#include <pfk_api.h>
|
||||
|
||||
static struct dst_entry *
|
||||
pfk_route4(__be32 daddr, __be32 saddr, int oif)
|
||||
@@ -23,6 +24,26 @@ pfk_route4(__be32 daddr, __be32 saddr, int oif)
|
||||
return &rt->dst;
|
||||
}
|
||||
|
||||
/*
|
||||
* Forced nexthop (route-to/dup-to/reply-to). Linux resolves the neighbour
|
||||
* from the *packet's* destination unless the route says it goes through a
|
||||
* gateway (ip_neigh_for_gw() only honours rt_gw4 when rt_gw_family is set),
|
||||
* which would ARP the final host on the gateway's link. Look the gateway up
|
||||
* as its own host route and mark it as the nexthop - the same pattern OVS
|
||||
* uses after its own FIB lookups.
|
||||
*/
|
||||
static struct dst_entry *
|
||||
pfk_route4_nh(__be32 gw, int oif)
|
||||
{
|
||||
struct rtable *rt = (struct rtable *)pfk_route4(gw, 0, oif);
|
||||
|
||||
if (rt == NULL)
|
||||
return NULL;
|
||||
rt->rt_gw_family = AF_INET;
|
||||
rt->rt_gw4 = gw;
|
||||
return &rt->dst;
|
||||
}
|
||||
|
||||
#if IS_ENABLED(CONFIG_IPV6)
|
||||
static struct dst_entry *
|
||||
pfk_route6(const struct in6_addr *daddr, const struct in6_addr *saddr, int oif)
|
||||
@@ -67,13 +88,16 @@ if_output_tso(struct pfk_ifnet *ifp, struct mbuf **mp, void *dst,
|
||||
}
|
||||
switch (sa->sa_family) {
|
||||
case AF_INET: {
|
||||
struct pf_ip *ip = mtod(m, struct pf_ip *);
|
||||
__be32 gw = 0;
|
||||
|
||||
/* if route was forced (route-to), dst holds gw sockaddr
|
||||
* stored in sin_addr by pf_route; normal case dst==final */
|
||||
gw = sintosa(dst)->sin_addr.s_addr;
|
||||
d = pfk_route4(gw, ip->ip_src.s_addr, ifp->if_index);
|
||||
/* PFLINUX: look the route up by destination only. Passing the
|
||||
* packet's source (a transit address, not local to us) makes
|
||||
* ip_route_output_key fail with ENETUNREACH; ip_output keeps
|
||||
* the header source untouched. */
|
||||
d = pfk_route4_nh(gw, ifp->if_index);
|
||||
if (!d) {
|
||||
ret = EHOSTUNREACH;
|
||||
goto drop;
|
||||
@@ -83,13 +107,11 @@ if_output_tso(struct pfk_ifnet *ifp, struct mbuf **mp, void *dst,
|
||||
}
|
||||
#if IS_ENABLED(CONFIG_IPV6)
|
||||
case AF_INET6: {
|
||||
struct pf_ip6_hdr *ip6 = mtod(m, struct pf_ip6_hdr *);
|
||||
const struct in6_addr *gw = &sin6tosa(dst)->sin6_addr;
|
||||
|
||||
if (!d)
|
||||
d = pfk_route6(gw,
|
||||
(struct in6_addr *)&ip6->ip6_src,
|
||||
ifp->if_index);
|
||||
/* PFLINUX: destination-only, as for IPv4 */
|
||||
d = pfk_route6(gw, NULL, ifp->if_index);
|
||||
if (!d) {
|
||||
ret = EHOSTUNREACH;
|
||||
goto drop;
|
||||
@@ -114,6 +136,28 @@ if_output_tso(struct pfk_ifnet *ifp, struct mbuf **mp, void *dst,
|
||||
ret = ENETDOWN;
|
||||
goto drop_dst_nofree;
|
||||
}
|
||||
/*
|
||||
* The stack's output path always consumes exactly one skb reference.
|
||||
* Take our own so the caller's references (the hook queue ref and the
|
||||
* mbuf wrapper ref) stay balanced - without this the work queue's
|
||||
* cleanup double-frees the skb and corrupts the slab.
|
||||
*/
|
||||
/*
|
||||
* pf_route() has already evaluated the OUT ruleset (it calls
|
||||
* pf_test(PF_OUT) itself, exactly like OpenBSD's ip_forward). Mark the
|
||||
* packet so our POST_ROUTING hook does not run the out ruleset a second
|
||||
* time - that re-match hits the state, re-enters pf_route and recurses
|
||||
* (OpenBSD stops this with PF_TAG_PROCESSED carried in the mbuf).
|
||||
*/
|
||||
skb->mark |= PFK_DONE_OUT;
|
||||
/*
|
||||
* The port stashes its mbuf pointer in skb->cb; the IP stack uses the
|
||||
* same bytes as its own control block (IPCB). Hand the packet to the
|
||||
* stack with a clean cb, otherwise ip_output() reads our pointer as
|
||||
* frag_max_size/flags and the packet is silently lost.
|
||||
*/
|
||||
memset(skb->cb, 0, sizeof(skb->cb));
|
||||
skb_get(skb);
|
||||
ret = skb_dst(skb)->output(&init_net, NULL, skb);
|
||||
/* output consumed skb (and wrapper); avoid double free */
|
||||
if (ret == 0) {
|
||||
@@ -226,3 +270,40 @@ pfk_if_output(struct pfk_ifnet *ifp, struct mbuf *m, void *dst,
|
||||
m_freem(mp);
|
||||
return err;
|
||||
}
|
||||
|
||||
/*
|
||||
* Transmit one queued packet. Called from ifq_start() - i.e. from the pf
|
||||
* work queue or from a scheduler's deferred timeout - and always consumes the
|
||||
* mbuf. Returns 0 (keep draining); a scheduler that wants to defer does so by
|
||||
* simply not returning a packet from ifqop_deq_begin().
|
||||
*/
|
||||
int
|
||||
pfk_ifq_transmit(struct ifqueue *ifq, struct mbuf *m)
|
||||
{
|
||||
struct sk_buff *skb = m_to_skb(m);
|
||||
struct dst_entry *d;
|
||||
|
||||
(void)ifq;
|
||||
if (skb == NULL) {
|
||||
m_freem(m);
|
||||
return 0;
|
||||
}
|
||||
d = skb_dst(skb);
|
||||
if (d == NULL || IS_ERR(d) || d->dev == NULL || !netif_running(d->dev)) {
|
||||
m_freem(m);
|
||||
return 0;
|
||||
}
|
||||
skb->dev = d->dev;
|
||||
skb_reset_network_header(skb);
|
||||
if (skb->protocol == 0)
|
||||
skb->protocol = htons(ip_hdr(skb)->protocol == IPPROTO_IPV6 ?
|
||||
ETH_P_IPV6 : ETH_P_IP);
|
||||
/* the stack owns skb->cb (IPCB) from here; pf already tested it */
|
||||
memset(skb->cb, 0, sizeof(skb->cb));
|
||||
skb->mark |= PFK_DONE_OUT;
|
||||
skb_get(skb); /* the output path consumes one reference */
|
||||
m->skb = NULL; /* the mbuf's reference moves to the stack */
|
||||
m_freem(m);
|
||||
d->output(&init_net, NULL, skb);
|
||||
return 0;
|
||||
}
|
||||
+35
-7
@@ -46,7 +46,34 @@
|
||||
#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().
|
||||
@@ -215,7 +242,7 @@ rn_satisfies_leaf(char *trial, struct radix_node *leaf, int skip)
|
||||
if (cp3 == NULL)
|
||||
cp3 = rn_ones;
|
||||
else
|
||||
length = min(length, SALEN(cp3));
|
||||
length = min(length, MSALEN(cp3));
|
||||
cplim = cp + length;
|
||||
cp += skip;
|
||||
cp2 += skip;
|
||||
@@ -252,7 +279,7 @@ rn_match(void *v_arg, struct radix_node_head *head)
|
||||
* are probably the most common case...
|
||||
*/
|
||||
if (t->rn_mask)
|
||||
vlen = SALEN(t->rn_mask);
|
||||
vlen = MSALEN(t->rn_mask);
|
||||
else
|
||||
vlen = SALEN(v);
|
||||
cp = v + off;
|
||||
@@ -367,7 +394,8 @@ rn_insert(void *v_arg, struct radix_node_head *head,
|
||||
caddr_t cp, cp2, cplim;
|
||||
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;
|
||||
cp2 = t->rn_key + off;
|
||||
cplim = v + vlen;
|
||||
@@ -440,7 +468,7 @@ rn_addmask(void *n_arg, int search, int skip)
|
||||
if (mlen <= skip)
|
||||
return (mask_rnhead->rnh_nodes);
|
||||
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);
|
||||
if (memcmp(addmask_key, tm->rn_key, mlen) != 0)
|
||||
tm = NULL;
|
||||
@@ -493,9 +521,9 @@ rn_lexobetter(void *m_arg, void *n_arg)
|
||||
* first. The netmasks were normalized before calling this function and
|
||||
* don't have unneeded trailing zeros.
|
||||
*/
|
||||
if (SALEN(mp) > SALEN(np))
|
||||
if (MSALEN(mp) > MSALEN(np))
|
||||
return 1;
|
||||
if (SALEN(mp) < SALEN(np))
|
||||
if (MSALEN(mp) < MSALEN(np))
|
||||
return 0;
|
||||
/*
|
||||
* Must return the first difference between the masks
|
||||
|
||||
@@ -27,6 +27,7 @@ struct ifqueue {
|
||||
struct mbuf_list *ifq_free; /* free list (unused in the port) */
|
||||
unsigned int ifq_len;
|
||||
unsigned int ifq_oactive;
|
||||
void *ifq_dequeue; /* cookie between deq_begin/commit */
|
||||
|
||||
/* statistics */
|
||||
u_int64_t ifq_packets;
|
||||
|
||||
@@ -164,13 +164,34 @@ struct { \
|
||||
/*
|
||||
* 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 type *lh_first; /* first element */ \
|
||||
}
|
||||
|
||||
#define LIST_HEAD_INITIALIZER(head) \
|
||||
{ NULL }
|
||||
#define LIST_HEAD_LINUX(name) \
|
||||
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) \
|
||||
struct { \
|
||||
|
||||
@@ -23,10 +23,14 @@ static inline bool refcnt_take_not0(struct refcnt *r)
|
||||
{
|
||||
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)
|
||||
{
|
||||
return (unsigned int)refcount_dec_and_test(&r->rc) ?
|
||||
refcnt_value(r) : refcnt_value(r) + 1;
|
||||
return (unsigned int)refcount_dec_and_test(&r->rc) ? 1 : 0;
|
||||
}
|
||||
static inline unsigned int refcnt_rele_wake(struct refcnt *r)
|
||||
{
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
/* $OpenBSD: fq_codel.h,v 1.4 2020/06/18 23:29:59 dlg Exp $ */
|
||||
|
||||
/*
|
||||
* Copyright (c) 2017 Mike Belopuhov
|
||||
*
|
||||
* Permission to use, copy, modify, and distribute this software for any
|
||||
* purpose with or without fee is hereby granted, provided that the above
|
||||
* copyright notice and this permission notice appear in all copies.
|
||||
*
|
||||
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
||||
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
||||
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
||||
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||||
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||||
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||||
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
*/
|
||||
|
||||
#ifndef _NET_FQ_CODEL_H_
|
||||
#define _NET_FQ_CODEL_H_
|
||||
|
||||
/* compatible with hfsc_pktcntr */
|
||||
struct fqcodel_pktcntr {
|
||||
uint64_t packets;
|
||||
uint64_t bytes;
|
||||
};
|
||||
|
||||
struct fqcodel_stats {
|
||||
struct fqcodel_pktcntr xmit_cnt;
|
||||
struct fqcodel_pktcntr drop_cnt;
|
||||
|
||||
uint32_t qlength;
|
||||
uint32_t qlimit;
|
||||
|
||||
uint32_t flows;
|
||||
uint32_t _unused; /* padding */
|
||||
|
||||
uint32_t target;
|
||||
uint32_t interval;
|
||||
|
||||
/* the values below are used to calculate standard deviation */
|
||||
uint64_t delaysum; /* sum of delays, us */
|
||||
uint64_t delaysumsq;/* sum of squared delays, us */
|
||||
};
|
||||
|
||||
#ifdef _KERNEL
|
||||
extern const struct ifq_ops * const ifq_fqcodel_ops;
|
||||
extern const struct pfq_ops * const pfq_fqcodel_ops;
|
||||
#endif /* _KERNEL */
|
||||
|
||||
#endif /* _NET_FQ_CODEL_H_ */
|
||||
@@ -0,0 +1,122 @@
|
||||
/* $OpenBSD: hfsc.h,v 1.15 2026/03/19 14:59:05 sthen Exp $ */
|
||||
|
||||
/*
|
||||
* Copyright (c) 2012-2013 Henning Brauer <henning@openbsd.org>
|
||||
* Copyright (c) 1997-1999 Carnegie Mellon University. All Rights Reserved.
|
||||
*
|
||||
* Permission to use, copy, modify, and distribute this software and
|
||||
* its documentation is hereby granted (including for commercial or
|
||||
* for-profit use), provided that both the copyright notice and this
|
||||
* permission notice appear in all copies of the software, derivative
|
||||
* works, or modified versions, and any portions thereof.
|
||||
*
|
||||
* THIS SOFTWARE IS EXPERIMENTAL AND IS KNOWN TO HAVE BUGS, SOME OF
|
||||
* WHICH MAY HAVE SERIOUS CONSEQUENCES. CARNEGIE MELLON PROVIDES THIS
|
||||
* SOFTWARE IN ITS ``AS IS'' CONDITION, AND ANY EXPRESS OR IMPLIED
|
||||
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
* DISCLAIMED. IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
|
||||
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||||
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
|
||||
* OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
|
||||
* BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
||||
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
|
||||
* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
|
||||
* DAMAGE.
|
||||
*
|
||||
* Carnegie Mellon encourages (but does not require) users of this
|
||||
* software to return any improvements or extensions that they make,
|
||||
* and to grant Carnegie Mellon the rights to redistribute these
|
||||
* changes without encumbrance.
|
||||
*/
|
||||
#ifndef _HFSC_H_
|
||||
#define _HFSC_H_
|
||||
|
||||
/* hfsc class flags */
|
||||
#define HFSC_DEFAULTCLASS 0x1000 /* default class */
|
||||
|
||||
struct hfsc_pktcntr {
|
||||
u_int64_t packets;
|
||||
u_int64_t bytes;
|
||||
};
|
||||
|
||||
#define PKTCNTR_INC(cntr, len) \
|
||||
do { (cntr)->packets++; (cntr)->bytes += len; } while (0)
|
||||
|
||||
struct hfsc_sc {
|
||||
u_int64_t m1; /* slope of the first segment in bits/sec */
|
||||
u_int64_t m2; /* slope of the second segment in bits/sec */
|
||||
u_int d; /* the x-projection of the first segment in msec */
|
||||
};
|
||||
|
||||
/* special class handles */
|
||||
#define HFSC_ROOT_CLASS 0x10000
|
||||
#define HFSC_DEFAULT_CLASSES 64
|
||||
#define HFSC_MAX_CLASSES 65535
|
||||
|
||||
/* service curve types */
|
||||
#define HFSC_REALTIMESC 1
|
||||
#define HFSC_LINKSHARINGSC 2
|
||||
#define HFSC_UPPERLIMITSC 4
|
||||
#define HFSC_DEFAULTSC (HFSC_REALTIMESC|HFSC_LINKSHARINGSC)
|
||||
|
||||
struct hfsc_class_stats {
|
||||
struct hfsc_pktcntr xmit_cnt;
|
||||
struct hfsc_pktcntr drop_cnt;
|
||||
|
||||
u_int qlength;
|
||||
u_int qlimit;
|
||||
u_int period;
|
||||
|
||||
u_int class_id;
|
||||
u_int32_t class_handle;
|
||||
struct hfsc_sc rsc;
|
||||
struct hfsc_sc fsc;
|
||||
struct hfsc_sc usc; /* upper limit service curve */
|
||||
|
||||
u_int64_t total; /* total work in bytes */
|
||||
u_int64_t cumul; /* cumulative work in bytes
|
||||
done by real-time criteria */
|
||||
u_int64_t d; /* deadline */
|
||||
u_int64_t e; /* eligible time */
|
||||
u_int64_t vt; /* virtual time */
|
||||
u_int64_t f; /* fit time for upper-limit */
|
||||
|
||||
/* info helpful for debugging */
|
||||
u_int64_t initvt; /* init virtual time */
|
||||
u_int64_t vtoff; /* cl_vt_ipoff */
|
||||
u_int64_t cvtmax; /* cl_maxvt */
|
||||
u_int64_t myf; /* cl_myf */
|
||||
u_int64_t cfmin; /* cl_mincf */
|
||||
u_int64_t cvtmin; /* cl_mincvt */
|
||||
u_int64_t myfadj; /* cl_myfadj */
|
||||
u_int64_t vtadj; /* cl_vtadj */
|
||||
u_int64_t cur_time;
|
||||
u_int32_t machclk_freq;
|
||||
|
||||
u_int vtperiod; /* vt period sequence no */
|
||||
u_int parentperiod; /* parent's vt period seqno */
|
||||
int nactive; /* number of active children */
|
||||
|
||||
/* red and rio related info */
|
||||
int qtype;
|
||||
/* struct redstats red[3]; */
|
||||
};
|
||||
|
||||
#ifdef _KERNEL
|
||||
struct ifnet;
|
||||
struct ifqueue;
|
||||
struct pf_queuespec;
|
||||
struct hfsc_if;
|
||||
|
||||
extern const struct ifq_ops * const ifq_hfsc_ops;
|
||||
extern const struct pfq_ops * const pfq_hfsc_ops;
|
||||
|
||||
#define HFSC_ENABLED(ifq) ((ifq)->ifq_ops == ifq_hfsc_ops)
|
||||
#define HFSC_DEFAULT_QLIMIT 50
|
||||
|
||||
void hfsc_initialize(void);
|
||||
|
||||
#endif /* _KERNEL */
|
||||
#endif /* _HFSC_H_ */
|
||||
@@ -1203,4 +1203,60 @@ int pf_anchor_stack_pop(struct pf_ruleset **, struct pf_rule **,
|
||||
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)
|
||||
|
||||
|
||||
/*
|
||||
* Scheduler back-end ABI: the very headers OpenBSD ships (net/hfsc.h,
|
||||
* net/fq_codel.h), vendored into the port so that pfctl and pf.ko agree on the
|
||||
* stats layouts and on the class-handle/service-curve constants. (Hand-rolled
|
||||
* approximations of these structs made DIOCGETQSTATS fail with EINVAL, because
|
||||
* pfctl's sizeof(struct hfsc_class_stats) did not match the kernel's.)
|
||||
*/
|
||||
#ifndef nsecuptime
|
||||
#define nsecuptime() getnsecuptime()
|
||||
#endif
|
||||
|
||||
#include <net/hfsc.h>
|
||||
#include <net/fq_codel.h>
|
||||
|
||||
/* OpenBSD's global nanoseconds-per-clocktick (HFSC_CLK_PER_TICK). The port
|
||||
* has no clock_rate machinery, so derive it from the kernel's HZ. */
|
||||
#ifndef tick_nsec
|
||||
#define tick_nsec (1000000000LL / HZ)
|
||||
#endif
|
||||
|
||||
/* ifq scheduler hand-off (see pfsrc/ifq.c): enter returns the scheduler's
|
||||
* queue state when it owns the interface queue, NULL otherwise. */
|
||||
void *ifq_q_enter(struct ifqueue *, const struct ifq_ops *);
|
||||
void ifq_q_leave(struct ifqueue *, void *);
|
||||
int pfk_ifq_transmit(struct ifqueue *, struct mbuf *);
|
||||
int pf_kifq_input(struct pfk_ifnet *, struct mbuf *);
|
||||
|
||||
|
||||
/*
|
||||
* PFLINUX notes on the scheduler back ends:
|
||||
*
|
||||
* - splnet()/splx(): OpenBSD raises the software interrupt level around
|
||||
* class-table surgery. This port runs the whole data path in one ordered
|
||||
* work queue and guards the queue with ifq_mtx, so these are no-ops; they
|
||||
* are kept as markers of the critical regions.
|
||||
* - KERNEL_ASSERT_LOCKED(): the schedulers are only reached from ifq/pf paths
|
||||
* that already hold the queue mutex; asserted structurally, not by spl.
|
||||
* - HFSC_ENABLED(), PKTCNTR_INC(), the class-handle constants and the stats
|
||||
* layouts all come from the vendored net/hfsc.h / net/fq_codel.h above, so
|
||||
* kernel and pfctl cannot drift apart.
|
||||
*/
|
||||
#define splnet() 0
|
||||
#define splx(s) ((void)(s))
|
||||
#define KERNEL_ASSERT_LOCKED() do { } while (0)
|
||||
|
||||
#endif /* _PFK_H */
|
||||
|
||||
@@ -7,7 +7,19 @@
|
||||
long pfk_ioctl(struct file *f, unsigned int cmd, unsigned long addr);
|
||||
int pfk_enable(int on);
|
||||
void pfk_status(struct pf_status *s);
|
||||
#define PFK_SKIP_PF 0x00000004u /* skb->mark: reinjected, bypass pf */
|
||||
#define PFK_DONE_IN 0x00000001u /* skb->mark bit: PF_IN pass completed */
|
||||
#define PFK_DONE_OUT 0x00000002u /* skb->mark bit: PF_OUT pass completed */
|
||||
|
||||
int pfk_hooks_register(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
|
||||
@@ -74,6 +74,79 @@ ml_dequeue(struct mbuf_list *ml)
|
||||
return m;
|
||||
}
|
||||
|
||||
|
||||
/* BSD <net/if_var.h> mbuf_list helpers (net/if_var.h ml_*) */
|
||||
static inline void
|
||||
ml_init(struct mbuf_list *ml)
|
||||
{
|
||||
ml->ml_first = ml->ml_last = NULL;
|
||||
ml->ml_len = 0;
|
||||
}
|
||||
|
||||
static inline void
|
||||
ml_enqueue(struct mbuf_list *ml, struct mbuf *m)
|
||||
{
|
||||
m->m_next = NULL;
|
||||
if (ml->ml_last == NULL)
|
||||
ml->ml_first = m;
|
||||
else
|
||||
ml->ml_last->m_next = m;
|
||||
ml->ml_last = m;
|
||||
ml->ml_len++;
|
||||
}
|
||||
|
||||
static inline struct mbuf *
|
||||
ml_dequeue_tail(struct mbuf_list *ml)
|
||||
{
|
||||
struct mbuf *m, *prev = NULL;
|
||||
|
||||
if (ml->ml_first == NULL)
|
||||
return NULL;
|
||||
for (m = ml->ml_first; m->m_next; m = m->m_next)
|
||||
prev = m;
|
||||
if (prev == NULL) /* single element */
|
||||
ml->ml_first = NULL;
|
||||
else
|
||||
prev->m_next = NULL;
|
||||
ml->ml_last = prev;
|
||||
ml->ml_len--;
|
||||
m->m_next = NULL;
|
||||
return m;
|
||||
}
|
||||
|
||||
/* append every packet in m2 to m1 (m2 becomes empty) */
|
||||
static inline void
|
||||
ml_enlist(struct mbuf_list *m1, struct mbuf_list *m2)
|
||||
{
|
||||
if (m2->ml_first == NULL)
|
||||
return;
|
||||
if (m1->ml_last == NULL)
|
||||
m1->ml_first = m2->ml_first;
|
||||
else
|
||||
m1->ml_last->m_next = m2->ml_first;
|
||||
m1->ml_last = m2->ml_last;
|
||||
m1->ml_len += m2->ml_len;
|
||||
m2->ml_first = m2->ml_last = NULL;
|
||||
m2->ml_len = 0;
|
||||
}
|
||||
|
||||
static inline unsigned int
|
||||
ml_len(const struct mbuf_list *ml)
|
||||
{
|
||||
return (unsigned int)ml->ml_len;
|
||||
}
|
||||
|
||||
static inline int
|
||||
ml_empty(const struct mbuf_list *ml)
|
||||
{
|
||||
return ml->ml_first == NULL;
|
||||
}
|
||||
|
||||
void ml_purge(struct mbuf_list *ml); /* compat/pfk_mbuf.c (needs m_freem) */
|
||||
|
||||
#define MBUF_LIST_FIRST(_ml) ((_ml)->ml_first)
|
||||
#define MBUF_LIST_INITIALIZER() { NULL, NULL, 0 }
|
||||
|
||||
/* egress interface (default-route dev), maintained on fib/net events */
|
||||
struct pfk_ifnet *pfk_egress_if(void);
|
||||
void pfk_egress_refresh(void);
|
||||
|
||||
@@ -73,7 +73,7 @@ struct pkthdr {
|
||||
u_int32_t ph_flowid;
|
||||
u_int ph_ifidx;
|
||||
u_int ph_rtableid;
|
||||
struct pfk_timeval ph_timestamp;
|
||||
int64_t ph_timestamp; /* OpenBSD 8.0: nanoseconds */
|
||||
struct pfk_ifnet *ifp;
|
||||
struct pfk_ifnet *rcvif;
|
||||
u_short ph; /* tso segs: unused, kept as pad */
|
||||
|
||||
@@ -1828,6 +1828,9 @@ deps_pfsrc/divert_sock.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
include/pfk_api.h \
|
||||
|
||||
pfsrc/divert_sock.o: $(deps_pfsrc/divert_sock.o)
|
||||
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
@@ -1828,6 +1828,8 @@ deps_pfsrc/pf.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
pfsrc/pf.o: $(deps_pfsrc/pf.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pf_if.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
pfsrc/pf_if.o: $(deps_pfsrc/pf_if.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pf_ioctl.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
pfsrc/pf_ioctl.o: $(deps_pfsrc/pf_ioctl.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pf_lb.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
pfsrc/pf_lb.o: $(deps_pfsrc/pf_lb.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pf_norm.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
pfsrc/pf_norm.o: $(deps_pfsrc/pf_norm.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pf_osfp.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
pfsrc/pf_osfp.o: $(deps_pfsrc/pf_osfp.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pf_ruleset.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
pfsrc/pf_ruleset.o: $(deps_pfsrc/pf_ruleset.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pf_syncookies.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
pfsrc/pf_syncookies.o: $(deps_pfsrc/pf_syncookies.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pf_table.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
|
||||
pfsrc/pf_table.o: $(deps_pfsrc/pf_table.o)
|
||||
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pfk_hooks.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
include/pfk_api.h \
|
||||
|
||||
pfsrc/pfk_hooks.o: $(deps_pfsrc/pfk_hooks.o)
|
||||
|
||||
@@ -1828,6 +1828,8 @@ deps_pfsrc/pfk_mod.o := \
|
||||
include/compat/sys/rwlock.h \
|
||||
include/compat/sys/mutex.h \
|
||||
include/compat/sys/pclock.h \
|
||||
include/net/hfsc.h \
|
||||
include/net/fq_codel.h \
|
||||
include/pfk_api.h \
|
||||
|
||||
pfsrc/pfk_mod.o: $(deps_pfsrc/pfk_mod.o)
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
+522
-17
@@ -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()
|
||||
* find the AF_DIVERT pcb bound to `divert_port`, queue the packet to it and
|
||||
* consume the mbuf; when NO divert socket is attached, OpenBSD drops the
|
||||
* packet (m_freem) — that is exactly the observable behaviour implemented
|
||||
* here until the pfdiv socket layer is instantiated for Linux (milestone
|
||||
* M6); a rate-limited kernel log records the event so drops are never
|
||||
* silent.
|
||||
* Implements OpenBSD's divert(4) as a runtime-registered protocol family
|
||||
* inside the PF module: PF_DIVERT = 32 (BSD value; the unused legacy
|
||||
* PF_IUCV slot on Linux, and NPROTO = AF_MAX = 45 admits it),
|
||||
* IPPROTO_DIVERT = 254. No core patch is required — families are
|
||||
* registered with sock_register() at module init.
|
||||
*
|
||||
* The upstream BSD socket layer is staged in pfsrc/ip_divert.c and becomes
|
||||
* the real back end in M6; these wrappers keep the same call signature
|
||||
* (struct mbuf *, int dir, u_int16_t divert_port).
|
||||
* Userspace ABI (see docs/en/divert-wireformat.md):
|
||||
* fd = socket(PF_DIVERT, SOCK_RAW, IPPROTO_DIVERT);
|
||||
* 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 <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
|
||||
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",
|
||||
ntohs(divert_port));
|
||||
struct sk_buff *skb;
|
||||
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);
|
||||
if (skb)
|
||||
pfk_divert_queue(skb, dir, type, divert_port);
|
||||
}
|
||||
|
||||
void
|
||||
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",
|
||||
ntohs(divert_port));
|
||||
m_freem(m);
|
||||
divert_packet(m, dir, divert_port);
|
||||
}
|
||||
|
||||
/* ---------------- 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);
|
||||
}
|
||||
@@ -332,7 +332,9 @@ control_law(struct codel *cd, struct codel_params *cp, int64_t rts)
|
||||
unsigned int idx;
|
||||
|
||||
KASSERT(cd->drops > 0);
|
||||
idx = min(cd->drops - 1, nitems(codel_intervals) - 1);
|
||||
/* PFLINUX: Linux' min() type-checks its arguments; nitems() is size_t */
|
||||
idx = min_t(unsigned int, cd->drops - 1,
|
||||
(unsigned int)(nitems(codel_intervals) - 1));
|
||||
cd->next = rts + cp->intervals[idx];
|
||||
}
|
||||
|
||||
|
||||
+12
-3
@@ -335,9 +335,9 @@ hfsc_class_purge(struct hfsc_class *cl, struct mbuf_list *ml)
|
||||
}
|
||||
|
||||
static inline u_int
|
||||
hfsc_more_slots(u_int current)
|
||||
hfsc_more_slots(u_int cur) /* PFLINUX: 'current' is a kernel macro */
|
||||
{
|
||||
u_int want = current * 2;
|
||||
u_int want = cur * 2;
|
||||
|
||||
return (want > HFSC_MAX_CLASSES ? HFSC_MAX_CLASSES : want);
|
||||
}
|
||||
@@ -481,7 +481,16 @@ hfsc_pf_qstats(struct pf_queuespec *q, void *ubuf, int *nbytes)
|
||||
if (hif == NULL)
|
||||
return (EBADF);
|
||||
|
||||
if ((cl = hfsc_clh2cph(hif, q->qid)) == NULL) {
|
||||
/*
|
||||
* A root queue's class is created with handle HFSC_ROOT_CLASS | qid
|
||||
* (see hfsc_pf_addqueue), so looking the queue up by its plain pf qid
|
||||
* only finds non-root classes: fall back to the root handle, otherwise
|
||||
* "pfctl -s queue" fails with EINVAL on the first (root) queue.
|
||||
*/
|
||||
if ((cl = hfsc_clh2cph(hif, q->qid)) == NULL &&
|
||||
(q->flags & PFQS_ROOTCLASS))
|
||||
cl = hfsc_clh2cph(hif, HFSC_ROOT_CLASS | q->qid);
|
||||
if (cl == NULL) {
|
||||
ifq_q_leave(&ifp->if_snd, hif);
|
||||
return (EINVAL);
|
||||
}
|
||||
|
||||
+9
-13
@@ -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
|
||||
&& !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 &&
|
||||
pf_insert_src_node(&ctx.sns[PF_SN_NONE], r, PF_SN_NONE,
|
||||
pd->af, pd->src, NULL, NULL) != 0) {
|
||||
@@ -8286,7 +8283,6 @@ pf_test(sa_family_t af, int fwdir, struct pfk_ifnet *ifp, struct mbuf **m0)
|
||||
|
||||
if (!pf_status.running)
|
||||
return (PF_PASS);
|
||||
|
||||
#if NCARP > 0
|
||||
if (ifp->if_type == IFT_CARP) {
|
||||
struct pfk_ifnet *ifp0;
|
||||
@@ -8642,18 +8638,18 @@ done:
|
||||
if (pd.destchg && pd.dir == PF_OUT)
|
||||
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 &&
|
||||
(r->divert.type == PF_DIVERT_TO ||
|
||||
r->divert.type == PF_DIVERT_REPLY)) {
|
||||
struct pf_divert *divert;
|
||||
|
||||
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;
|
||||
}
|
||||
divert_packet(pd.m, pd.dir, r->divert.port);
|
||||
pd.m = NULL;
|
||||
}
|
||||
|
||||
if (action == PF_PASS && r->divert.type == PF_DIVERT_PACKET)
|
||||
|
||||
@@ -90,6 +90,17 @@ pfi_kif_alloc(const char *kif_name, int mflags)
|
||||
kif->pfik_flags |= 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);
|
||||
}
|
||||
|
||||
@@ -662,6 +662,11 @@ pf_create_queues(void)
|
||||
}
|
||||
|
||||
qif->disc = qif->pfqops->pfq_alloc(ifp);
|
||||
if (qif->disc == NULL) {
|
||||
error = ENOBUFS;
|
||||
free(qif, M_PF, sizeof(*qif));
|
||||
goto error;
|
||||
}
|
||||
|
||||
qif->next = list;
|
||||
list = qif;
|
||||
@@ -2266,40 +2271,33 @@ pfioctl(dev_t dev, u_long cmd, caddr_t addr, int flags, struct proc *p)
|
||||
sizeof(pr->anchor) ||
|
||||
strnlen(pr->anchor_call, sizeof(pr->anchor_call)) >=
|
||||
sizeof(pr->anchor_call)) {
|
||||
error = ENAMETOOLONG; pr_info("pfkE: addrule1\n");
|
||||
error = ENAMETOOLONG;
|
||||
goto fail;
|
||||
}
|
||||
|
||||
rule = pool_get(&pf_rule_pl, PR_WAITOK|PR_LIMITFAIL|PR_ZERO);
|
||||
if (rule == NULL) {
|
||||
error = ENOMEM; pr_info("pfkE: addrule-pool\n");
|
||||
error = ENOMEM;
|
||||
goto fail;
|
||||
}
|
||||
|
||||
if ((error = pf_rule_copyin(&pr->rule, rule))) {
|
||||
pr_info("pfkE: addrule copyin=%d\n", error);
|
||||
pf_rule_free(rule);
|
||||
rule = NULL;
|
||||
goto fail;
|
||||
}
|
||||
|
||||
if (pr->rule.return_icmp >> 8 > ICMP_MAXTYPE) {
|
||||
pr_info("pfkE: addrule icmp %x\n", pr->rule.return_icmp);
|
||||
error = EINVAL;
|
||||
pf_rule_free(rule);
|
||||
rule = NULL;
|
||||
goto fail;
|
||||
}
|
||||
if ((error = pf_rule_checkaf(rule))) {
|
||||
pr_info("pfkE: addrule checkaf=%d\n", error);
|
||||
pf_rule_free(rule);
|
||||
rule = NULL;
|
||||
goto fail;
|
||||
}
|
||||
if (rule->src.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;
|
||||
pf_rule_free(rule);
|
||||
rule = NULL;
|
||||
|
||||
@@ -2098,6 +2098,7 @@ pfr_commit_ktable(struct pfr_ktable *kt, time_t tzero)
|
||||
struct pfr_ktable *shadow = kt->pfrkt_shadow;
|
||||
int nflags;
|
||||
|
||||
|
||||
if (shadow->pfrkt_cnt == NO_ADDRESSES) {
|
||||
if (!(kt->pfrkt_flags & PFR_TFLAG_ACTIVE))
|
||||
pfr_clstats_ktable(kt, tzero, 1);
|
||||
|
||||
+155
-4
@@ -22,6 +22,8 @@
|
||||
#include <net/pfvar_priv.h>
|
||||
|
||||
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;
|
||||
|
||||
/* PFLINUX: netisr work item — carries ownership of one sk_buff */
|
||||
@@ -33,8 +35,6 @@ struct pfk_pkt {
|
||||
int dir;
|
||||
};
|
||||
|
||||
#define PFK_DONE_IN 0x50460010u /* skb->mark bit: PF_IN pass completed */
|
||||
#define PFK_DONE_OUT 0x50460020u /* skb->mark bit: PF_OUT pass completed */
|
||||
|
||||
static void
|
||||
pfk_pkt_reinject(struct pfk_pkt *pk)
|
||||
@@ -69,14 +69,119 @@ pfk_pkt_reinject(struct pfk_pkt *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);
|
||||
/* the stack owns skb->cb (IPCB) from here - see pfk_xmit.c */
|
||||
memset(skb->cb, 0, sizeof(skb->cb));
|
||||
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
|
||||
pfk_pkt_work(struct work_struct *w)
|
||||
{
|
||||
struct pfk_pkt *pk = container_of(w, struct pfk_pkt, work);
|
||||
struct mbuf *m, *m0;
|
||||
struct sk_buff *orig;
|
||||
__be32 orig_dst = 0, orig_src = 0;
|
||||
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);
|
||||
if (!m) {
|
||||
pfk_pkt_reinject(pk); /* like "pf not consulted" */
|
||||
@@ -91,10 +196,43 @@ pfk_pkt_work(struct work_struct *w)
|
||||
* and packet walk run concurrently from here on — documented. */
|
||||
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) {
|
||||
/*
|
||||
* Queueing: when a pf `queue' rule attached a scheduler to the
|
||||
* egress interface, hand the packet to it instead of sending it
|
||||
* straight out - this is what makes bandwidth limits real.
|
||||
*/
|
||||
if (action == PF_PASS && pk->dir == PF_OUT &&
|
||||
pskb_may_pull(pk->skb, sizeof(struct iphdr)) &&
|
||||
skb_dst(pk->skb) && !IS_ERR(skb_dst(pk->skb)) &&
|
||||
pf_kifq_input(skb_dst(pk->skb)->dev ?
|
||||
pfk_ifp_bydev(skb_dst(pk->skb)->dev) : NULL, m)) {
|
||||
orig = pk->skb;
|
||||
pk->skb = NULL; /* the queue owns the packet */
|
||||
kfree_skb(orig);
|
||||
kfree(pk);
|
||||
return;
|
||||
}
|
||||
/* same buffer, possibly rewritten in place: our wrapper
|
||||
* held one extra skb reference — release it */
|
||||
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) {
|
||||
pfk_pkt_reinject(pk);
|
||||
return;
|
||||
@@ -135,15 +273,27 @@ pfk_enqueue_verdict(int af, struct sk_buff *skb,
|
||||
|
||||
switch (st->hook) {
|
||||
case NF_INET_PRE_ROUTING:
|
||||
/* OpenBSD evaluates the IN ruleset in ip_input(); every
|
||||
* arriving packet passes it. */
|
||||
dir = PF_IN;
|
||||
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_POST_ROUTING:
|
||||
dir = PF_OUT;
|
||||
break;
|
||||
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))
|
||||
return NF_ACCEPT;
|
||||
|
||||
@@ -155,7 +305,8 @@ pfk_enqueue_verdict(int af, struct sk_buff *skb,
|
||||
if (dir == PF_IN)
|
||||
ifp = pfk_ifp_bydev(st->in ? st->in : skb->dev);
|
||||
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)
|
||||
return NF_ACCEPT;
|
||||
|
||||
|
||||
+17
-4
@@ -54,9 +54,6 @@ pfk_ioctl_io(struct file *filp, unsigned int cmd, unsigned long arg)
|
||||
p.p_ucred = &cred;
|
||||
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);
|
||||
if (!kdata)
|
||||
return -ENOMEM;
|
||||
@@ -96,6 +93,10 @@ static struct miscdevice pfk_dev = {
|
||||
|
||||
extern void pf_status_init(void);
|
||||
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
|
||||
pfk_pfi_event(int added, struct pfk_ifnet *ifp)
|
||||
@@ -134,15 +135,25 @@ static int __init pfk_init(void)
|
||||
pfattach(0);
|
||||
pfk_if_set_event_cb(pfk_pfi_event);
|
||||
pfk_if_iterate(pfk_pfi_attach_one);
|
||||
err = pfk_hooks_register();
|
||||
err = pfk_pflog_register();
|
||||
if (err)
|
||||
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);
|
||||
if (err)
|
||||
goto err_hooks;
|
||||
pr_info("pfk: PF-on-Linux engine loaded (OpenBSD 8.0 base)\n");
|
||||
return 0;
|
||||
err_hooks:
|
||||
pfk_divert_sock_unregister();
|
||||
err_divert:
|
||||
pfk_pflog_unregister();
|
||||
err_pflog:
|
||||
pfk_hooks_unregister();
|
||||
err_if:
|
||||
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
|
||||
* workqueues non-empty forever (observed rmmod hang). */
|
||||
misc_deregister(&pfk_dev);
|
||||
pfk_divert_sock_unregister();
|
||||
pfk_pflog_unregister();
|
||||
pfk_net_lock();
|
||||
pf_status.running = 0;
|
||||
pfk_net_unlock();
|
||||
|
||||
@@ -0,0 +1,310 @@
|
||||
/*
|
||||
* 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;
|
||||
int off;
|
||||
|
||||
if (skb == NULL)
|
||||
return 0;
|
||||
/*
|
||||
* BSD logs from the network header; pf may already have advanced the
|
||||
* mbuf/skb data pointer to the transport header while parsing, so
|
||||
* anchor explicitly at the IP header instead of at skb->data.
|
||||
*/
|
||||
off = skb_network_offset(skb);
|
||||
if (off < 0)
|
||||
off = 0;
|
||||
if (off > skb->len)
|
||||
return 0;
|
||||
n = min_t(size_t, want, skb->len - off);
|
||||
if (skb_copy_bits(skb, off, 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);
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 2.8 MiB |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Loaded 100 of 165 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user