Screencasts v2: real shell sessions, MiniMax narration (EN/PT), lab diagram

O problema da primeira serie era a sensacao de 'quadro a quadro': a captura era a saida de um script despejada em blocos. Agora cada video e uma sessao shell de verdade. - record.py: abre um pty, faz SSH no firewall e digita os comandos tecla a tecla (~34 c/s, com jitter). O tty remoto ecoa, o kernel responde ao vivo; a captura e asciicast v2 com timestamps. 'bash --noediting' evita que o editor de linha redesenhe o comando e o tty o repita (a linha aparecia duplicada). - record.py --pace: segura a tela enquanto a voz fala - cada batida dura o trecho de audio que a acompanha, de modo que uma unica captura serve as duas versoes de idioma. - record.py --ensure-pf: garante pf.ko carregado antes de gravar. Sem isso uma fase que roda 'rmmod' (ativacao) pode derrubar o /dev/pf de outra gravacao concorrentes - foi exatamente o que quebrou a fase de roteamento na primeira tentativa. - make_audio.py: geracao da narracao pelo MiniMax TTS, uma voz feminina por idioma (English_ConfidentWoman / Portuguese_ConfidentWoman), um arquivo por segmento. A API devolve o audio em hexadecimal, nao base64. - render_video.py: reproduz a captura por um emulador de terminal e escreve os frames direto no ffmpeg como RGB bruto (um PNG por frame era uma ordem de grandeza mais lento). Desenha o diagrama de rede do lab por cima do terminal nas fases de roteamento e balanceamento, destacando o caminho em discussao, e queima a legenda da narracao. - assemble.py: mixa os segmentos de audio na linha do tempo. - join.py: emenda as fases com crossfade sobre um cartao de capitulo e sincroniza o audio na mesma linha do tempo. - build-all.sh: roda o pipeline inteiro. Arte de fundo e audio vem do MiniMax; a geracao de video do MiniMax nao esta habilitada nesta conta (erro 2068 em todos os modelos), entao as transicoes sao renderizadas localmente com ffmpeg. 16 videos: 7 fases + filme completo, em ingles e portugues, com legenda queimada.
Screencasts: seis videos silenciosos 1080p30 da demonstracao
2026-11-12 10:57:29 -03:00 · 2026-11-12 08:41:41 -03:00 · 2026-11-12 03:10:46 -03:00 · 2026-11-12 01:42:51 -03:00 · 2026-11-12 01:40:49 -03:00 · 2026-11-12 01:15:26 -03:00
136 changed files with 8759 additions and 221 deletions
@@ -1,6 +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
@@ -11,7 +21,9 @@ out/
 modules.order
 Module.symvers
 tools/out/
-!out/demo-pf-linux.cast
 lab/seeds/
 *.pcap
 *.log
+
+__pycache__/
+*.pyc
@@ -1,5 +1,72 @@
 # Changelog

+## Unreleased
+
+- **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
@@ -7,9 +7,9 @@ real OpenBSD `pfctl` over the `/dev/pf` ioctl ABI. (A second module for the
 `pfq` qdisc arrives with M5.)

 **Status:** the filter core, stateful filtering, tables, anchors, NAT
-(`nat-to`/`rdr-to`), `divert` and `pflog` are **verified in a real libvirt
-lab** (9/9 gates green).  The remaining features (binat-to, route-to/dup-to,
-scrub e2e, ALTQ/pfq, af-to) are still pending — honest per-feature status:
+(`nat-to`/`rdr-to`/`binat-to`), forced routing (`route-to`/`dup-to`), `divert`
+and `pflog` are **verified in a real libvirt lab** (14/14 gates green).  The
+remaining features (queue attachment/pacing, af-to) are still pending — honest per-feature status:
 [`docs/en/feature-matrix.md`](docs/en/feature-matrix.md).
 Demo (asciinema): [`docs/en/demo.md`](docs/en/demo.md).
 Design: [`docs/superpowers/specs/2026-11-11-pf-linux-port-design.md`](docs/superpowers/specs/2026-11-11-pf-linux-port-design.md)
@@ -22,10 +22,10 @@ Design: [`docs/superpowers/specs/2026-11-11-pf-linux-port-design.md`](docs/super
 | M0 | repo, scripts, kernel build, VM boots the custom kernel | done |
 | M1 | compat layer, `pf.ko` loads, `/dev/pf`, `pfctl -f` / `-s info` | done |
 | M2 | filter core: rules/states/tables/anchors, VM gates 01–04 | **done** — gates 01/02/03/04 green |
-| M3 | NAT (`nat-to`/`rdr-to`/`binat-to`), scrub e2e | **partial** — `nat-to` (gate 05) and `rdr-to` incl. 2 MB integrity (gate 06) verified; `binat-to` and scrub e2e pending |
-| M4 | route-to/dup-to/fail-to, divert e2e, pflog | **partial** — divert e2e (gate 11) and pflog (gate 12) verified; route-to/dup-to pending |
-| M5 | queues: HFSC/FQ-CoDel back ends + `pfq` qdisc | pending |
-| M6 | docs complete, patchset tidy, full suite green, tagged release | in progress (docs done, suite 7/7 green) |
+| 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, 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, 11/11 suite green, tagged (v0.5.0) |

 ## What you get (planned)

@@ -35,16 +35,32 @@ Design: [`docs/superpowers/specs/2026-11-11-pf-linux-port-design.md`](docs/super
 | 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 |
+| 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` (pools rr/hash-source/hash-state, `fail-to`), `reply-to`, `dup-to` |
-| Logging | `pflogd` via `/dev/pflog` (DLT_PFLOG pcap, OpenBSD record layout) |
+| 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).

+## 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/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). Short version
@@ -70,40 +70,70 @@ exactly when the host is out of atomic memory.
  conntrack — as designed (spec §4.2).
 - Output (`LOCAL_OUT` at `NF_IP_PRI_CONNTRACK+1`): PF sees locally generated
  traffic **after** conntrack has already committed the entry.
- Transit egress (`POSTROUTING` at `NF_IP_PRI_LAST-1`): PF runs at the very
-  end — after any iptables/nft SNAT/masquerade — so `pass out … nat-to`-era
-  rules (M3) will be validated against this ordering. The "unregister-safe
-  ordering vs conntrack" warning from the design still applies: overlapping
-  policy between PF and conntrack is possible and yours to manage.
+- 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; the soak is still pending
+### 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`. That fix is in-tree,
-but the full cycle under traffic + live states (T18/soak gate) has **not**
-been run to green yet. For now treat unload as admin-safe, automation-
-unproven.
+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 / rendering issues open today
+## Behavioral notes verified today

-### 7. `pfctl -s states` visibility anomaly (M2 gate work)
+### 7. `pfctl -s states` lists real states, including translations

-In the most recent captured run (gate 01): transit ping **passed** under
-`keep state`, but no icmp state was listed afterwards. Fixing this is the
-open item of the M2 gate work; until a green run lands, the
-[state-listing row](feature-matrix.md) is the honest status. Not cosmetic if
-it turns out states are not being inserted — treat both possibilities until
-the gate says otherwise.
+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. Silent-but-warned stubs
+### 8. Consumers still required for two features

-`divert` verdicts drop with a rate-limited warning; `log` rules log nothing
-with a one-time warning. Both are listed so nobody mistakes "rules loaded"
-for "features active" (see [pf-guide.md](pf-guide.md)).
+`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)

@@ -50,17 +50,17 @@ As of 2026-11-11; source of per-row evidence: `out/test-logs/`,
 |---|---|---|---|
 | `nat-to` (port pools, sticky-port, static-port) | `pass out … nat-to (eth1:0)` | M3 | **VERIFIED in lab** — source NAT works end to end: the packet leaves with the pool address (tcpdump proof), the reply is de-NATed and re-routed to the client, and the state shows both tuples (`10.0.2.1:59335 (10.0.1.10:4380) -> 10.0.2.20:8`). Gate: `tests/vm/05-nat.sh`. |
 | `rdr-to` | `pass in … to <fw> port 8080 rdr-to <srv> port 80 keep state` | M3 | **VERIFIED in lab** — port redirect works end to end (gate `06-rdr.sh`): the client talks to the firewall's address, pf rewrites the destination, re-routes the packet, and the reply is un-redirected. The gate also pulls 2 MB through the redirect and checks byte-for-byte integrity (GSO/TSO regression guard). |
-| `binat-to` | `binat-to <net>` (no direction) | M3 | PENDING-M3 — parser accepts the 8.0 form (`binat-to` is a rule option, not a standalone rule); VM gate not written yet. |
-| Scrub/normalize: reassembly, `fragment drop-overlap`, `min-ttl`, `max-mss`, `df`/`no-df`, `random-id`, `set reassemble yes` | `match on all scrub (max-mss 1380 …)` | M3 | COMPILES-untested (`pf_norm.c` compiled into pf.ko and reached from `pf_test`; scapy gate 08 pending) |
+| `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 lab** — 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. |
+| 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 lab** — 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 yet gated. |
 | OS fingerprinting in states | `pass … set os A` + `/etc/pf.os` | bonus | COMPILES-untested (`pf_osfp.c` compiled; no fingerprint packaging yet — missing `/etc/pf.os` is tolerated) |

 ## Routing / divert / queues / logging

 | Feature | Upstream syntax | Milestone | Status |
 |---|---|---|---|
-| `route-to` pools (`rr`, `round-robin`, `source-hash`, `hash`), `reply-to`, `dup-to`, `fail-to` | `pass out route-to (GW 10.0.3.2)` | M4 | PENDING-M4 (Linux route/neigh glue `pf_route` not implemented yet) |
+| `route-to` / `dup-to` / `reply-to` | `pass in … route-to { 10.0.3.2 } keep state`, `reply-to { gw }` | M4 | **VERIFIED in lab** — 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>` | VERIFIED in lab | **Works end-to-end.** The module registers an `AF_DIVERT` socket family (`PF_DIVERT=32`) at runtime — no kernel-tree patch. A `divert-to` rule hands the packet to that family; with no listener the packet is dropped (`divs_noport`, BSD parity); with `tools/pdivert` running the packet is delivered to userspace, rewritten and reinjected (verified with a payload mutation + checksum fix, ping 0% loss). |
-| Queues, default scheduler (priq) | `queue root on wan`, `pfctl -s queue -v` | M5 | COMPILES-untested — `compat/pfk_ifq.c` implements the ifq API with **priq fallback semantics**; `queue` rules parse and load, but packets are not actually shunted through a classful qdisc until M5 |
+| 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 lab** — 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 | COMPILES-untested — **priq fallback until M5**; `pfsrc/hfsc.c` staged (real OpenBSD 8.0 code) but **not in the module object list** |
 | FQ-CoDel | `queue on wan { fq_codel … }` | M5 | COMPILES-untested — same as HFSC: staged, not built |
 | `pfq` qdisc (`tc qdisc … root pfq`) | n/a (Linux glue) | M5 | PENDING-M5 (does not exist in the tree yet) |
@@ -89,11 +89,11 @@ rebuilt.
 |---|---|---|
 | M0 | repo, scripts, kernel build, VM boots custom kernel | done |
 | M1 | compat layer, `pf.ko` loads, `/dev/pf`, `pfctl -f`/`-s info` | done |
-| M2 | filter core: rules/states/tables/anchors VM gates | **in progress** — data path implemented, gates 01–04 not all green yet |
-| M3 | NAT (nat/rdr/binat), scrub e2e, pflog | pending |
-| M4 | route-to/dup-to/fail-to, divert e2e | pending |
-| M5 | queues: ifq back ends (hfsc/fq_codel) + `pfq` qdisc | pending |
-| M6 | docs complete, patchset tidy, full suite green, tagged releases | in progress (this doc set) |
+| 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) | **partial** — back ends compiled into `pf.ko`; queue attachment/pacing pending |
+| M6 | docs complete, patchset tidy, full suite green, tagged releases | in progress — docs EN+PT-BR complete, 14/14 suite green, tagged |

 ## Next reads

@@ -20,11 +20,11 @@ used.
 `patches/kernel/` therefore contains no `000N-*.patch` today, and applying
 the (empty) set is a no-op.

-> Honest note: install.md and the design mention `scripts/apply-patches.sh`,
-> `scripts/unpatch.sh` and `patches/kernel/series`. Those helpers are **not
-> in the tree yet**; until they land, "apply the patch set" is by definition
-> nothing to do. When a real patch is needed, the first commit that adds it
-> MUST also add the two scripts and the `series` file (see rules below).
+> 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)

@@ -60,11 +60,10 @@ treat them as load-and-pray until the matrix moves them.

 | Syntax | Until | What happens today |
 |---|---|---|
-| `nat-to`, `rdr-to` (`binat-to` pending) | — | **Verified in the lab** (gates `05-nat`, `06-rdr`, the latter pulls 2 MB through a redirect and compares it byte for byte). `nat-to (egress)` expands the OpenBSD interface *group*; on a multi-NIC host prefer the explicit `nat-to (<iface>)` form. |
-| `scrub (…)`, `set reassemble` | M3 | `pf_norm.c` runs inside `pf_test` (compiled) — crafted-fragment behavior is untested; treat results as unvalidated. |
-| `divert-to`, `divert` tag | — | **Verified in the lab** (gate `11-divert`): the packet is delivered to an `AF_DIVERT` socket (`PF_DIVERT=32`) served by `tools/pdivert`; with no listener it is dropped, exactly like BSD's `divs_noport`. |
-| `route-to`, `dup-to`, `fail-to`, `reply-to` | M4 | Not implemented as Linux routing glue yet; rules may load but the behavior is undefined — avoid. |
-| `queue` / `queue on` / `pfctl -s queue` | M5 | Parse and load. Queuing falls back to the priq-shaped compat `ifq` layer; **no bandwidth enforcement happens until the `pfq` qdisc lands**. |
+| `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. |
@@ -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
+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
+```
@@ -939,3 +939,94 @@ 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.
@@ -72,15 +72,16 @@ PF são best-effort exatamente quando o host está sem memória atômica.
  e do conntrack — como projetado (spec §4.2).
 - Saída (`LOCAL_OUT` em `NF_IP_PRI_CONNTRACK+1`): o PF vê o tráfego gerado
  localmente **depois** de o conntrack já ter confirmado a entrada.
- Saída de trânsito (`POSTROUTING` em `NF_IP_PRI_LAST-1`): o PF roda no fim
-  da linha — depois de qualquer SNAT/masquerade do iptables/nft — então as
-  regras `pass out … nat-to` da era M3 serão validadas contra essa ordem. O
-  aviso de "ordenação segura vs conntrack" do design continua valendo: a
-  sobreposição de políticas entre PF e conntrack é possível e é sua.
+- 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; o soak ainda está pendente
+### 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 —
@@ -90,22 +91,51 @@ A correção está na árvore, mas o ciclo completo sob tráfego + estados vivos
 (gate de soak T18) **ainda não** rodou verde. Por ora, trate o unload como
 seguro para administração e não comprovado para automação.

-## Problemas de comportamento/renderização abertos hoje
+## Notas de comportamento verificadas hoje

-### 7. Anomalia de visibilidade do `pfctl -s states` (trabalho do gate M2)
+### 7. `pfctl -s states` lista estados reais, incluindo traduções

-Na rodada capturada mais recente (gate 01): o ping de trânsito **passou** com
-`keep state`, mas nenhum estado icmp foi listado depois. Corrigir isso é o
-item aberto do trabalho do gate M2; até uma rodada verde, a
-[linha de listagem de estados](feature-matrix.md) é o status honesto. Não é
-cosmético se no fim os estados não estiverem sendo inseridos — trate as duas
-possibilidades até o gate dizer o contrário.
+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. Stubs silenciosos-mas-avisados
+### 8. Ainda são necessários consumidores

-Vereditos `divert` descartam com aviso rate-limited; regras de `log` não
-logam nada e avisam uma única vez. Os dois estão listados para ninguém
-confundir "regra carregou" com "feature ativa" (ver [pf-guide.md](pf-guide.md)).
+`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)

@@ -50,17 +50,17 @@ Estado em 2026-11-11; evidência por linha: `out/test-logs/`,
 |---|---|---|---|
 | `nat-to` (pools de portas, sticky-port, static-port) | `pass out … nat-to (eth1:0)` | M3 | **VERIFICADO em lab** — NAT de origem funciona ponta a ponta: o pacote sai com o endereço do pool (prova via tcpdump), a resposta é des-NATeada e roteada de novo para o cliente, e o estado mostra as duas tuplas (`10.0.2.1:59335 (10.0.1.10:4380) -> 10.0.2.20:8`). Gate: `tests/vm/05-nat.sh`. |
 | `rdr-to` | `pass in … to <fw> port 8080 rdr-to <srv> port 80 keep state` | M3 | **VERIFICADO em lab** — o redirect de portas funciona ponta a ponta (gate `06-rdr.sh`): o cliente fala com o endereço do firewall, o pf reescreve o destino, re-rotea o pacote e a resposta é des-redirectuada. O gate também baixa 2 MB pelo redirect e confere a integridade byte a byte (guarda de regressão GSO/TSO). |
-| `binat-to` | `binat-to <rede>` (sem direção) | M3 | PENDING-M3 — o parser aceita a forma 8.0 (`binat-to` é opção de regra, não regra própria); gate em VM ainda não escrito. |
-| Scrub/normalize: remontagem, `fragment drop-overlap`, `min-ttl`, `max-mss`, `df`/`no-df`, `random-id`, `set reassemble yes` | `match on all scrub (max-mss 1380 …)` | M3 | COMPILES-untested (`pf_norm.c` compilado no pf.ko e alcançado pelo `pf_test`; gate scapy 08 pendente) |
+| `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 | **VERIFICADO em lab** — gate `07-binat.sh`. O pfctl expande uma regra `binat-to` no par documentado (`pass out … nat-to <mapeado> static-port` + `pass in … rdr-to <real>`), e as duas metades funcionam: o peer vê o endereço mapeado, o original não vaza, e a resposta é traduzida de volta. |
+| Scrub/normalização: remonteagem, `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 | **VERIFICADO em lab** — gate `09-scrub.sh`: `min-ttl` eleva o TTL (o egress mostra 99 após o decremento do encaminhamento) e `max-mss` limita o MSS de um SYN, ambos medidos no egress do próprio firewall. Os caminhos de remonteagem/overlap estão compilados e alcançados, mas ainda sem gate. |
 | Fingerprint de SO em estados | `pass … set os A` + `/etc/pf.os` | bônus | COMPILES-untested (`pf_osfp.c` compilado; sem empacotamento de fingerprints ainda — ausência de `/etc/pf.os` é tolerada) |

 ## Roteamento / divert / filas / logging

 | Feature | Sintaxe de upstream | Milestone | Status |
 |---|---|---|---|
-| Pools de `route-to` (`rr`, `round-robin`, `source-hash`, `hash`), `reply-to`, `dup-to`, `fail-to` | `pass out route-to (GW 10.0.3.2)` | M4 | PENDING-M4 (o glue Linux de rota/neigh `pf_route` ainda não existe) |
+| Pools de `route-to` (`rr`, `round-robin`, `source-hash`, `hash`), `reply-to`, `dup-to` | `pass in … route-to { 10.0.3.2, 10.0.2.2 } round-robin keep state` | M4 | **`round-robin` e `source-hash` VERIFICADOS em lab** (gate `10-pools.sh`): com dois gateways em dois enlaces, o round-robin usa ambos e o source-hash fixa todo fluxo de uma origem em um único enlace. `dup-to` verificado no gate 08; `reply-to` ainda sem gate. `fail-to` **não existe no OpenBSD 8.0** (removido upstream), então está fora de escopo. |
 | `divert-to` / tag `divert` | `pass in … divert-to <host> port <n>` | VERIFICADO em lab | **Funciona ponta a ponta.** O módulo registra em runtime a família de sockets `AF_DIVERT` (`PF_DIVERT=32`) — sem patch no kernel. A regra `divert-to` entrega o pacote a essa família; sem listener o pacote é descartado (`divs_noport`, paridade BSD); com `tools/pdivert` rodando o pacote vai ao userspace, é reescrito e reinjetado (verificado com mutação de payload + correção de checksum, ping 0% loss). |
-| Filas, agendador default (priq) | `queue root on wan`, `pfctl -s queue -v` | M5 | COMPILES-untested — `compat/pfk_ifq.c` implementa a API ifq com **semântica de fallback priq**; regras `queue` fazem parse e carregam, mas pacotes ainda não são desviados por um qdisc classful até o M5 |
+| Filas (`queue`, `queue on`, `pfctl -s queue -v`) | `queue rootq on eth2 bandwidth 10Mbit` + `queue leafq on eth2 bandwidth 2Mbit parent rootq default` | M5 | **VERIFICADO em lab** — 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 | COMPILES-untested — **fallback priq até o M5**; `pfsrc/hfsc.c` staged (código real do OpenBSD 8.0) mas **fora da lista de objetos** do módulo |
 | FQ-CoDel | `queue on wan { fq_codel … }` | M5 | COMPILES-untested — igual ao HFSC: staged, não compilado |
 | Qdisc `pfq` (`tc qdisc … root pfq`) | n/a (glue Linux) | M5 | PENDING-M5 (ainda não existe na árvore) |
@@ -91,11 +91,11 @@ tamanho embutido na codificação `_IOR/_IOW` OpenBSD e despacha para o
 |---|---|---|
 | M0 | repo, scripts, build do kernel, VM liga com kernel próprio | concluído |
 | M1 | camada de compat, `pf.ko` carrega, `/dev/pf`, `pfctl -f`/`-s info` | concluído |
-| M2 | núcleo de filtragem: gates VM de regras/estados/tabelas/anchors | **em andamento** — caminho de dados implementado, gates 01–04 ainda não todos verdes |
-| M3 | NAT (nat/rdr/binat), scrub e2e, pflog | pendente |
-| M4 | route-to/dup-to/fail-to, divert e2e | pendente |
-| M5 | filas: back ends ifq (hfsc/fq_codel) + qdisc `pfq` | pendente |
-| M6 | docs bilíngues completas, patchset arrumado, suíte inteira verde, tags de release | em andamento (este conjunto de docs) |
+| 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) | **parcial** — back ends compilados no `pf.ko`; anexação/ritmo pendentes |
+| M6 | docs completas, patchset limpo, suíte verde, releases com tag | em andamento — docs EN+PT-BR completas, suíte 14/14 verde, com tag |

 ## Próximas leituras

@@ -20,12 +20,11 @@ userland forem usados.
 Portanto, `patches/kernel/` não contém nenhum `000N-*.patch` hoje, e aplicar
 o conjunto (vazio) é um no-op.

-> Nota honesta: o install.md e o design mencionam `scripts/apply-patches.sh`,
-> `scripts/unpatch.sh` e `patches/kernel/series`. Esses helpers **ainda não
-> estão na árvore**; até entrarem, "aplicar o conjunto de patches" é, por
-> definição, nada a fazer. Quando um patch real for necessário, o primeiro
-> commit que o adicionar DEVE também adicionar os dois scripts e o arquivo
-> `series` (ver as regras abaixo).
+> 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)

@@ -63,11 +63,10 @@ matriz mudar.

 | Sintaxe | Até | O que acontece hoje |
 |---|---|---|
-| `nat-to`, `rdr-to` | — | **Verificado em lab** (gates `05-nat`, `06-rdr`; este último baixa 2 MB por um redirect e compara byte a byte). `nat-to (egress)` expande o *grupo* de interfaces do OpenBSD; num host multi-NIC prefira a forma explícita `nat-to (<iface>)`. `binat-to` ainda sem gate. |
-| `scrub (…)`, `set reassemble` | M3 | O `pf_norm.c` roda dentro do `pf_test` (compilado) — o comportamento com fragmentos forjados não foi testado; trate o resultado como não validado. |
-| `divert-to`, tag `divert` | — | **Verificado em lab** (gate `11-divert`): o pacote é entregue a um socket `AF_DIVERT` (`PF_DIVERT=32`) atendido pelo `tools/pdivert`; sem listener é descartado, exatamente como o `divs_noport` do BSD. |
-| `route-to`, `dup-to`, `fail-to`, `reply-to` | M4 | Ainda não implementados como glue de roteamento Linux; as regras podem carregar, mas o comportamento é indefinido — evite. |
-| `queue` / `queue on` / `pfctl -s queue` | M5 | Faz parse e carrega. A fila cai no fallback priq da camada `ifq` de compat; **nenhuma limitação de banda acontece até o qdisc `pfq` chegar**. |
+| `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. |
@@ -0,0 +1,123 @@
+# Screencasts / Videos da demonstracao
+
+> PT-BR: esta pagina · EN: [docs/en/screencast.md](../en/screencast.md)
+
+Sete videos por idioma, com **narracao de 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` |
+
+O audio e gerado 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
+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
+```
@@ -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 pfsrc/pfk_pflog.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
@@ -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/pfk_pflog.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 \

@@ -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");
-}
@@ -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) ---------------- */
@@ -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;
+}
@@ -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;
@@ -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_ */
@@ -1212,5 +1212,51 @@ struct pfk_pflog_stat {
 };
 #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 */

@@ -8,6 +8,8 @@ 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);
@@ -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,8 @@ 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)
@@ -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)
@@ -1828,6 +1828,8 @@ deps_pfsrc/pfk_pflog.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_pflog.o: $(deps_pfsrc/pfk_pflog.o)
@@ -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];
 }

@@ -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);
 	}
@@ -8283,11 +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 (m0 && *m0 && (*m0)->m_pkthdr.len >= 20 &&
-	    ((*m0)->m_data[9] == IPPROTO_ICMP))
-		pr_info_ratelimited("pfk: T1 enter dir=%d ifp=%px kif=%px\n",
-		    fwdir, ifp, ifp ? ifp->if_pf_kif : NULL);
-
 #if NCARP > 0
 	if (ifp->if_type == IFT_CARP) {
 		struct pfk_ifnet *ifp0;
@@ -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;
@@ -35,8 +35,6 @@ struct pfk_pkt {
 	int			dir;
 };

-#define PFK_DONE_IN	0x00000001u	/* skb->mark bit: PF_IN pass completed */
-#define PFK_DONE_OUT	0x00000002u	/* skb->mark bit: PF_OUT pass completed */

 static void
 pfk_pkt_reinject(struct pfk_pkt *pk)
@@ -104,6 +102,8 @@ pfk_reroute(struct sk_buff *skb)
 	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);
 }

@@ -204,6 +204,22 @@ pfk_pkt_work(struct work_struct *w)


 	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);
@@ -115,11 +115,22 @@ 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;
-	n = min_t(size_t, want, skb->len);
-	if (skb_copy_bits(skb, 0, buf, n))
+	/*
+	 * 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;
 }
@@ -1,77 +1,84 @@
-{"version": 2, "width": 80, "height": 24, "timestamp": 1794445553, "env": {"SHELL": null, "TERM": "dumb"}}
-[1.622488, "o", "\u001b[1m===============================================================\u001b[0m\r\n"]
-[1.623391, "o", "\u001b[1m PF on Linux - the OpenBSD PF 8.0 engine inside the Linux kernel\u001b[0m\r\n\u001b[1m===============================================================\u001b[0m\r\n\r\nLab: 3 Alpine VMs under libvirt.\r\n  pftest-pf0 = firewall (kernel 7.3.4 built from source + pf.ko)\r\n  pftest-cli = client 10.0.1.10     pftest-srv = server 10.0.2.20\r\n\r\n\u001b[1m--- 1. our kernel, the OpenBSD engine as a module ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# uname -r\u001b[0m\r\n"]
-[1.885894, "o", "7.3.4\r\n"]
-[2.289113, "o", "\u001b[1;36mpftest-pf0# lsmod | grep '^pf ' || echo 'pf: not loaded yet'\u001b[0m\r\n"]
-[2.565982, "o", "pf                    552960  0\r\n"]
-[2.968407, "o", "\u001b[1;36mpftest-pf0# insmod /opt/pf/pf.ko && dmesg | tail -3\u001b[0m\r\n"]
-[3.226044, "o", "insmod: ERROR: could not insert module /opt/pf/pf.ko: File exists\r\n"]
-[3.629164, "o", "\r\n"]
-[3.629206, "o", "\u001b[1m--- 2. pfctl talks to the module over the OpenBSD ioctl ABI ---\u001b[0m\r\n"]
-[3.629219, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -s info | head -4\u001b[0m\r\n"]
-[3.906215, "o", "Status: Disabled for 0 days 00:03:33             Debug: err\r\n\r\nState Table                          Total             Rate\r\n  current entries                        0               \r\n"]
-[4.310059, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -e && /opt/pf/pfctl -s info | head -1\u001b[0m\r\n"]
-[4.574117, "o", "Status: Enabled                                  Debug: err\r\npf enabled\r\n"]
-[4.977439, "o", "\r\n\u001b[1m--- 3. a real pf.conf: tables, stateful rules, an explicit drop ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# cat /tmp/demo-pf.conf\u001b[0m\r\n"]
-[5.245993, "o", "# PF-on-Linux demo ruleset (pf.conf syntax, real OpenBSD pfctl)\r\nset block-policy return\r\ntable <trusted> { 10.0.1.0/24 }\r\n\r\n# transit traffic: stateful, table-driven\r\npass in quick on ingress proto icmp from <trusted> keep state\r\npass out quick on egress proto icmp keep state\r\n\r\n# deny a specific destination\r\nblock drop in quick proto icmp to 10.0.9.99\r\n\r\n# everything else\r\npass in quick\r\npass out quick\r\n"]
-[5.649022, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'rules loaded'\u001b[0m\r\n"]
-[5.926196, "o", "rules loaded\r\n"]
-[6.33004, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -sr\u001b[0m\r\n"]
-[6.614075, "o", "pass in quick on ingress proto icmp from <trusted> to any\r\npass out quick on egress proto icmp all\r\nblock drop in quick inet proto icmp from any to 10.0.9.99\r\npass in quick all flags S/SA\r\npass out quick all flags S/SA\r\n"]
-[7.017049, "o", "\r\n\u001b[1m--- 4. transit traffic is allowed and stateful ---\u001b[0m\r\n\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -3\u001b[0m\r\n"]
-[8.256385, "o", "--- 10.0.2.20 ping statistics ---\r\n2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.343/0.381/0.419 ms\r\n"]
-[8.659624, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -ss | grep -E 'icmp' | head -4\u001b[0m\r\n"]
-[8.94608, "o", "all icmp 10.0.2.20:8 <- 10.0.1.10:4987       0:0\r\nall icmp 10.0.1.10:4987 -> 10.0.2.20:8       0:0\r\n"]
-[9.348967, "o", "\r\n"]
-[9.349022, "o", "\u001b[1m--- 5. tables are live objects ---\u001b[0m\r\n"]
-[9.349263, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -t trusted -T show\u001b[0m\r\n"]
-[9.618085, "o", "   10.0.1.0/24\r\n"]
-[10.022258, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -s Tables\u001b[0m\r\n"]
-[10.309891, "o", "trusted\r\n"]
-[10.712978, "o", "\r\n\u001b[1m--- 6. the drop rule actually drops ---\u001b[0m\r\n"]
-[10.713088, "o", "\u001b[1;36mpftest-pf0# cat > /tmp/demo-block.conf <<EOF\r\nblock drop in quick proto icmp to 10.0.2.20\r\npass in quick\r\npass out quick\r\nEOF\u001b[0m\r\n"]
-[11.397835, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-block.conf && echo 'block rules loaded'\u001b[0m\r\n"]
-[11.650256, "o", "block rules loaded\r\n"]
-[12.05359, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -3\u001b[0m\r\n"]
-[15.280329, "o", "\r\n--- 10.0.2.20 ping statistics ---\r\n2 packets transmitted, 0 packets received, 100% packet loss\r\n"]
-[15.683815, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -sr -vv | head -6\u001b[0m\r\n"]
-[15.98217, "o", "@0 block drop in quick inet proto icmp from any to 10.0.2.20\r\n  [ Evaluations: 3         Packets: 2         Bytes: 168         States: 0     ]\r\n  [ Inserted: uid 0 pid 1877 State Creations: 0     ]\r\n@1 pass in quick all flags S/SA\r\n  [ Evaluations: 1         Packets: 28        Bytes: 9296        States: 1     ]\r\n  [ Inserted: uid 0 pid 1877 State Creations: 1     ]\r\n"]
-[16.384573, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'back to the stateful ruleset'\u001b[0m\r\n"]
-[16.670067, "o", "back to the stateful ruleset\r\n"]
-[17.0729, "o", "\r\n\u001b[1m--- 7. NAT: the source is translated on the way out, restored on the way back ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# cat > /tmp/demo-nat.conf <<EOF\r\npass out quick on egress from 10.0.1.0/24 to any nat-to (eth2)\r\npass in quick on ingress proto icmp keep state\r\npass out quick on egress proto icmp keep state\r\nEOF\u001b[0m\r\n"]
-[17.740601, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-nat.conf && echo 'nat rules loaded'\u001b[0m\r\n"]
-[18.018113, "o", "nat rules loaded\r\n"]
-[18.42114, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -3\u001b[0m\r\n"]
-[19.636475, "o", "--- 10.0.2.20 ping statistics ---\r\n2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.325/0.362/0.400 ms\r\n"]
-[20.038543, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -ss | grep -E 'icmp' | head -4\u001b[0m\r\n"]
-[20.310123, "o", "all icmp 10.0.2.20:8 <- 10.0.1.10:4999       0:0\r\nall icmp 10.0.2.1:7697 (10.0.1.10:4999) -> 10.0.2.20:8       0:0\r\n"]
-[20.712246, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'back to the stateful ruleset'\u001b[0m\r\n"]
-[20.990114, "o", "back to the stateful ruleset\r\n"]
-[21.392794, "o", "\r\n"]
-[21.393027, "o", "\u001b[1m--- 8. pflog: logged packets reach userspace (/dev/pflog) ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# cat > /tmp/demo-log.conf <<EOF\r\npass in quick log proto icmp from 10.0.1.10 keep state\r\npass out quick\r\nEOF\u001b[0m\r\n"]
-[22.057041, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-log.conf && echo 'log rule loaded'\u001b[0m\r\n"]
-[22.329918, "o", "log rule loaded\r\n"]
-[22.732644, "o", "\u001b[1;36mpftest-pf0# chmod +x /tmp/pflogd; rm -f /tmp/pflog.pcap; (setsid /tmp/pflogd -c 2 /tmp/pflog.pcap >/tmp/pflogd.log 2>&1 </dev/null &); sleep 1; echo 'pflogd collecting 2 records'\u001b[0m\r\n"]
-[23.981016, "o", "pflogd collecting 2 records\r\n"]
-[24.384736, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -2\u001b[0m\r\n"]
-[25.612472, "o", "2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.356/0.429/0.502 ms\r\n"]
-[28.017578, "o", "\u001b[1;36mpftest-pf0# cat /tmp/pflogd.log; ls -l /tmp/pflog.pcap; echo 'pcap header (magic d4c3b2a1, linktype 0x75=DLT_PFLOG):'; od -An -tx1 -N24 /tmp/pflog.pcap\u001b[0m\r\n"]
-[28.277996, "o", "pflogd: 2 records\r\n-rw-------    1 root     root           352 Nov 12 01:06 /tmp/pflog.pcap\r\npcap header (magic d4c3b2a1, linktype 0x75=DLT_PFLOG):\r\n d4 c3 b2 a1 02 00 04 00 00 00 00 00 00 00 00 00\r\n ff ff 00 00 75 00 00 00\r\n"]
-[28.681267, "o", "\u001b[1;36mpftest-pf0# pkill pflogd 2>/dev/null; /opt/pf/pfctl -f /tmp/demo-pf.conf >/dev/null\u001b[0m\r\n"]
-[29.352889, "o", "\r\n\u001b[1m--- 9. divert-to: the packet goes to userspace and comes back ---\u001b[0m\r\n"]
-[29.35314, "o", "\u001b[1;36mpftest-pf0# cat /tmp/demo-divert.conf\u001b[0m\r\n"]
-[29.625878, "o", "pass in quick proto icmp from 10.0.1.10 to 10.0.1.1 divert-to \"10.0.1.1\" port 10000 keep state\r\npass out quick\r\n"]
-[30.028664, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-divert.conf && echo 'divert rule loaded'\u001b[0m\r\n"]
-[30.317998, "o", "divert rule loaded\r\n"]
-[30.719927, "o", "\u001b[1;36mpftest-pf0# chmod +x /tmp/pdivert; (setsid /tmp/pdivert -p 10000 -f >/tmp/pdivert.log 2>&1 </dev/null &); sleep 1; pgrep pdivert\u001b[0m\r\n"]
-[31.941535, "o", "1956\r\n"]
-[32.344, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.1.1 | tail -3\u001b[0m\r\n"]
-[33.584192, "o", "--- 10.0.1.1 ping statistics ---\r\n2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.228/0.242/0.257 ms\r\n"]
-[33.987279, "o", "\u001b[1;36mpftest-pf0# head -3 /tmp/pdivert.log\u001b[0m\r\n"]
-[34.261872, "o", "pdivert: listening on divert port 10000\r\npdivert: got 84 bytes 10.0.1.10 -> 10.0.1.1\r\npdivert: got 84 bytes 10.0.1.10 -> 10.0.1.1\r\n"]
-[34.664226, "o", "  (pdivert flipped the last payload byte and fixed the ICMP checksum)\r\n\r\n"]
-[34.664382, "o", "\u001b[1m--- 10. shutdown ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# pkill pdivert; /opt/pf/pfctl -f /dev/null; /opt/pf/pfctl -d; echo 'pf disabled'\u001b[0m\r\n"]
-[34.938113, "o", "pf disabled\r\npf disabled\r\n"]
-[35.340577, "o", "\u001b[1;36mpftest-pf0# lsmod | grep '^pf '\u001b[0m\r\n"]
-[35.617928, "o", "pf                    552960  0\r\n"]
-[36.021187, "o", "\r\n\u001b[1mdemo over - port, gates and docs:\u001b[0m\r\n\u001b[1m  https://git.labexposed.com/lgcosta/pf-linux-port\u001b[0m\r\n\r\n"]
+{"version": 2, "width": 80, "height": 24, "timestamp": 1794449787, "env": {"SHELL": null, "TERM": "dumb"}}
+[1.414508, "o", "\u001b[1m===============================================================\u001b[0m\r\n\u001b[1m PF on Linux - the OpenBSD PF 8.0 engine inside the Linux kernel\u001b[0m\r\n\u001b[1m===============================================================\u001b[0m\r\n\r\nLab: 3 Alpine VMs under libvirt.\r\n  pftest-pf0 = firewall (kernel 7.3.4 built from source + pf.ko)\r\n  pftest-cli = client 10.0.1.10     pftest-srv = server 10.0.2.20\r\n\r\n\u001b[1m--- 1. our kernel, the OpenBSD engine as a module ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# uname -r\u001b[0m\r\n"]
+[1.655866, "o", "7.3.4\r\n"]
+[2.058621, "o", "\u001b[1;36mpftest-pf0# lsmod | grep '^pf ' || echo 'pf: not loaded yet'\u001b[0m\r\n"]
+[2.276696, "o", "pf: not loaded yet\r\n"]
+[2.680328, "o", "\u001b[1;36mpftest-pf0# insmod /opt/pf/pf.ko && dmesg | tail -3\u001b[0m\r\n"]
+[2.917691, "o", "[  146.252272] NET: Registered PF_IUCV protocol family\r\n[  146.252362] pfk: netfilter hooks registered (10, netisr wq data path)\r\n[  146.252423] pfk: PF-on-Linux engine loaded (OpenBSD 8.0 base)\r\n"]
+[3.320802, "o", "\r\n\u001b[1m--- 2. pfctl talks to the module over the OpenBSD ioctl ABI ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# /opt/pf/pfctl -s info | head -4\u001b[0m\r\n"]
+[3.598837, "o", "Status: Disabled for 0 days 00:02:26             Debug: err\r\n\r\nState Table                          Total             Rate\r\n  current entries                        0               \r\n"]
+[4.00249, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -e && /opt/pf/pfctl -s info | head -1\u001b[0m\r\n"]
+[4.274878, "o", "Status: Enabled                                  Debug: err\r\npf enabled\r\n"]
+[4.678074, "o", "\r\n\u001b[1m--- 3. a real pf.conf: tables, stateful rules, an explicit drop ---\u001b[0m\r\n"]
+[4.678128, "o", "\u001b[1;36mpftest-pf0# cat /tmp/demo-pf.conf\u001b[0m\r\n"]
+[4.954849, "o", "# PF-on-Linux demo ruleset (pf.conf syntax, real OpenBSD pfctl)\r\nset block-policy return\r\ntable <trusted> { 10.0.1.0/24 }\r\n\r\n# transit traffic: stateful, table-driven\r\npass in quick on ingress proto icmp from <trusted> keep state\r\npass out quick on egress proto icmp keep state\r\n\r\n# deny a specific destination\r\nblock drop in quick proto icmp to 10.0.9.99\r\n\r\n# everything else\r\npass in quick\r\npass out quick\r\n"]
+[5.358199, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'rules loaded'\u001b[0m\r\n"]
+[5.630704, "o", "rules loaded\r\n"]
+[6.034552, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -sr\u001b[0m\r\n"]
+[6.322794, "o", "pass in quick on ingress proto icmp from <trusted> to any\r\npass out quick on egress proto icmp all\r\nblock drop in quick inet proto icmp from any to 10.0.9.99\r\npass in quick all flags S/SA\r\npass out quick all flags S/SA\r\n"]
+[6.725786, "o", "\r\n"]
+[6.72584, "o", "\u001b[1m--- 4. transit traffic is allowed and stateful ---\u001b[0m\r\n\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -3\u001b[0m\r\n"]
+[7.977099, "o", "--- 10.0.2.20 ping statistics ---\r\n2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.339/0.351/0.363 ms\r\n"]
+[8.379918, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -ss | grep -E 'icmp' | head -4\u001b[0m\r\n"]
+[8.634572, "o", "all icmp 10.0.2.20:8 <- 10.0.1.10:5449       0:0\r\nall icmp 10.0.1.10:5449 -> 10.0.2.20:8       0:0\r\n"]
+[9.036709, "o", "\r\n\u001b[1m--- 5. tables are live objects ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# /opt/pf/pfctl -t trusted -T show\u001b[0m\r\n"]
+[9.298627, "o", "   10.0.1.0/24\r\n"]
+[9.701487, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -s Tables\u001b[0m\r\n"]
+[9.974937, "o", "trusted\r\n"]
+[10.378208, "o", "\r\n\u001b[1m--- 6. the drop rule actually drops ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# cat > /tmp/demo-block.conf <<EOF\r\nblock drop in quick proto icmp to 10.0.2.20\r\npass in quick\r\npass out quick\r\nEOF\u001b[0m\r\n"]
+[11.033956, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-block.conf && echo 'block rules loaded'\u001b[0m\r\n"]
+[11.310724, "o", "block rules loaded\r\n"]
+[11.714107, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -3\u001b[0m\r\n"]
+[14.969152, "o", "\r\n--- 10.0.2.20 ping statistics ---\r\n2 packets transmitted, 0 packets received, 100% packet loss\r\n"]
+[15.372543, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -sr -vv | head -6\u001b[0m\r\n"]
+[15.66699, "o", "@0 block drop in quick inet proto icmp from any to 10.0.2.20\r\n  [ Evaluations: 6         Packets: 2         Bytes: 168         States: 0     ]\r\n  [ Inserted: uid 0 pid 1687 State Creations: 0     ]\r\n@1 pass in quick all flags S/SA\r\n  [ Evaluations: 1         Packets: 28        Bytes: 9296        States: 1     ]\r\n  [ Inserted: uid 0 pid 1687 State Creations: 1     ]\r\n"]
+[16.07016, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'back to the stateful ruleset'\u001b[0m\r\n"]
+[16.338781, "o", "back to the stateful ruleset\r\n"]
+[16.742479, "o", "\r\n\u001b[1m--- 7. NAT: the source is translated on the way out, restored on the way back ---\u001b[0m\r\n"]
+[16.742537, "o", "\u001b[1;36mpftest-pf0# cat > /tmp/demo-nat.conf <<EOF\r\npass out quick on egress from 10.0.1.0/24 to any nat-to (eth2)\r\npass in quick on ingress proto icmp keep state\r\npass out quick on egress proto icmp keep state\r\nEOF\u001b[0m\r\n"]
+[17.422636, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-nat.conf && echo 'nat rules loaded'\u001b[0m\r\n"]
+[17.686794, "o", "nat rules loaded\r\n"]
+[18.090339, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -3\u001b[0m\r\n"]
+[19.341141, "o", "--- 10.0.2.20 ping statistics ---\r\n2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.276/0.317/0.359 ms\r\n"]
+[19.744749, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -ss | grep -E 'icmp' | head -4\u001b[0m\r\n"]
+[20.010971, "o", "all icmp 10.0.2.20:8 <- 10.0.1.10:5461       0:0\r\nall icmp 10.0.2.1:43040 (10.0.1.10:5461) -> 10.0.2.20:8       0:0\r\n"]
+[20.414328, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf && echo 'back to the stateful ruleset'\u001b[0m\r\n"]
+[20.690817, "o", "back to the stateful ruleset\r\n"]
+[21.094035, "o", "\r\n\u001b[1m--- 8. pflog: logged packets reach userspace (/dev/pflog) ---\u001b[0m\r\n"]
+[21.094088, "o", "\u001b[1;36mpftest-pf0# cat > /tmp/demo-log.conf <<EOF\r\npass in quick log proto icmp from 10.0.1.10 keep state\r\npass out quick\r\nEOF\u001b[0m\r\n"]
+[21.762242, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-log.conf && echo 'log rule loaded'\u001b[0m\r\n"]
+[22.034943, "o", "log rule loaded\r\n"]
+[22.438523, "o", "\u001b[1;36mpftest-pf0# chmod +x /tmp/pflogd; rm -f /tmp/pflog.pcap; (setsid /tmp/pflogd -c 2 /tmp/pflog.pcap >/tmp/pflogd.log 2>&1 </dev/null &); sleep 1; echo 'pflogd collecting 2 records'\u001b[0m\r\n"]
+[23.681454, "o", "pflogd collecting 2 records\r\n"]
+[24.084864, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.2.20 | tail -2\u001b[0m\r\n"]
+[25.333003, "o", "2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.352/0.364/0.376 ms\r\n"]
+[27.737616, "o", "\u001b[1;36mpftest-pf0# cat /tmp/pflogd.log; ls -l /tmp/pflog.pcap; echo 'pcap header (magic d4c3b2a1, linktype 0x75=DLT_PFLOG):'; od -An -tx1 -N24 /tmp/pflog.pcap\u001b[0m\r\n"]
+[28.026778, "o", "pflogd: 2 records\r\n-rw-------    1 root     root           324 Nov 12 02:16 /tmp/pflog.pcap\r\npcap header (magic d4c3b2a1, linktype 0x75=DLT_PFLOG):\r\n d4 c3 b2 a1 02 00 04 00 00 00 00 00 00 00 00 00\r\n ff ff 00 00 75 00 00 00\r\n"]
+[28.430241, "o", "\u001b[1;36mpftest-pf0# pkill pflogd 2>/dev/null; /opt/pf/pfctl -f /tmp/demo-pf.conf >/dev/null\u001b[0m\r\n"]
+[29.114632, "o", "\r\n\u001b[1m--- 9. route-to: force the next hop away from the normal path ---\u001b[0m\r\n"]
+[29.114687, "o", "\u001b[1;36mpftest-pf0# cat > /tmp/demo-route.conf <<EOF\r\npass in quick proto icmp from 10.0.1.10 to 10.0.2.20 route-to { 10.0.3.2 } keep state\r\npass out quick\r\nEOF\u001b[0m\r\n"]
+[29.778259, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-route.conf && echo 'route-to rule loaded'\u001b[0m\r\n"]
+[30.050898, "o", "route-to rule loaded\r\n"]
+[30.45427, "o", "\u001b[1;36mpftest-pf0# (tcpdump -ni eth3 -c 2 -e icmp > /tmp/route.td 2>&1 &); (tcpdump -ni eth2 -c 2 -e icmp > /tmp/norm.td 2>&1 &); sleep 1\u001b[0m\r\n"]
+[32.089063, "o", "\u001b[1;36mpftest-cli# ping -c1 -W2 10.0.2.20 | tail -2\u001b[0m\r\n"]
+[34.31667, "o", "--- 10.0.2.20 ping statistics ---\r\n1 packets transmitted, 0 packets received, 100% packet loss\r\n"]
+[36.72139, "o", "\u001b[1;36mpftest-pf0# echo 'forced egress (eth3, toward the gateway):'; grep -v '^tcpdump\\|^listening\\|^$' /tmp/route.td | head -2; echo 'normal egress (eth2):'; grep -c 'echo request' /tmp/norm.td\u001b[0m\r\n"]
+[37.006878, "o", "forced egress (eth3, toward the gateway):\r\n02:16:59.958272 52:54:00:aa:00:04 > 52:54:00:dd:00:02, ethertype IPv4 (0x0800), length 98: 10.0.1.10 > 10.0.2.20: ICMP echo request, id 5473, seq 0, length 64\r\nnormal egress (eth2):\r\n0\r\n"]
+[37.410476, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-pf.conf >/dev/null\u001b[0m\r\n"]
+[38.094888, "o", "\r\n\u001b[1m--- 10. divert-to: the packet goes to userspace and comes back ---\u001b[0m\r\n"]
+[38.095122, "o", "\u001b[1;36mpftest-pf0# cat /tmp/demo-divert.conf\u001b[0m\r\n"]
+[38.35866, "o", "pass in quick proto icmp from 10.0.1.10 to 10.0.1.1 divert-to \"10.0.1.1\" port 10000 keep state\r\npass out quick\r\n"]
+[38.763007, "o", "\u001b[1;36mpftest-pf0# /opt/pf/pfctl -f /tmp/demo-divert.conf && echo 'divert rule loaded'\u001b[0m\r\n"]
+[39.022814, "o", "divert rule loaded\r\n"]
+[39.42606, "o", "\u001b[1;36mpftest-pf0# chmod +x /tmp/pdivert; (setsid /tmp/pdivert -p 10000 -f >/tmp/pdivert.log 2>&1 </dev/null &); sleep 1; pgrep pdivert\u001b[0m\r\n"]
+[40.654519, "o", "1794\r\n"]
+[41.056785, "o", "\u001b[1;36mpftest-cli# ping -c2 -W2 10.0.1.1 | tail -3\u001b[0m\r\n"]
+[42.284778, "o", "--- 10.0.1.1 ping statistics ---\r\n2 packets transmitted, 2 packets received, 0% packet loss\r\nround-trip min/avg/max = 0.177/0.224/0.271 ms\r\n"]
+[42.691426, "o", "\u001b[1;36mpftest-pf0# head -3 /tmp/pdivert.log\u001b[0m\r\n"]
+[42.942601, "o", "pdivert: listening on divert port 10000\r\npdivert: got 84 bytes 10.0.1.10 -> 10.0.1.1\r\npdivert: got 84 bytes 10.0.1.10 -> 10.0.1.1\r\n"]
+[43.344696, "o", "  (pdivert flipped the last payload byte and fixed the ICMP checksum)\r\n\r\n\u001b[1m--- 11. shutdown ---\u001b[0m\r\n\u001b[1;36mpftest-pf0# pkill pdivert; /opt/pf/pfctl -f /dev/null; /opt/pf/pfctl -d; echo 'pf disabled'\u001b[0m\r\n"]
+[43.626606, "o", "pf disabled\r\npf disabled\r\n"]
+[44.028882, "o", "\u001b[1;36mpftest-pf0# lsmod | grep '^pf '\u001b[0m\r\n"]
+[44.286597, "o", "pf                    552960  0\r\n"]
+[44.688511, "o", "\r\n\u001b[1mdemo over - port, gates and docs:\u001b[0m\r\n\u001b[1m  https://git.labexposed.com/lgcosta/pf-linux-port\u001b[0m\r\n"]
+[44.688631, "o", "\r\n"]
@@ -151,7 +151,20 @@ p0 "cat /tmp/pflogd.log; ls -l /tmp/pflog.pcap; echo 'pcap header (magic d4c3b2a
 p0 "pkill pflogd 2>/dev/null; /opt/pf/pfctl -f /tmp/demo-pf.conf >/dev/null"
 echo

-bold "--- 9. divert-to: the packet goes to userspace and comes back ---"
+bold "--- 9. route-to: force the next hop away from the normal path ---"
+p0 "cat > /tmp/demo-route.conf <<EOF
+pass in quick proto icmp from $CLI_IP to $SRV_IP route-to { 10.0.3.2 } keep state
+pass out quick
+EOF"
+p0 "/opt/pf/pfctl -f /tmp/demo-route.conf && echo 'route-to rule loaded'"
+p0 "(tcpdump -ni eth3 -c 2 -e icmp > /tmp/route.td 2>&1 &); (tcpdump -ni eth2 -c 2 -e icmp > /tmp/norm.td 2>&1 &); sleep 1"
+vmc "ping -c1 -W2 $SRV_IP | tail -2"
+sleep 2
+p0 "echo 'forced egress (eth3, toward the gateway):'; grep -v '^tcpdump\|^listening\|^$' /tmp/route.td | head -2; echo 'normal egress (eth2):'; grep -c 'echo request' /tmp/norm.td"
+p0 "/opt/pf/pfctl -f /tmp/demo-pf.conf >/dev/null"
+echo
+
+bold "--- 10. divert-to: the packet goes to userspace and comes back ---"
 p0 "cat /tmp/demo-divert.conf"
 p0 "/opt/pf/pfctl -f /tmp/demo-divert.conf && echo 'divert rule loaded'"
 p0 "chmod +x /tmp/pdivert; (setsid /tmp/pdivert -p 10000 -f >/tmp/pdivert.log 2>&1 </dev/null &); sleep 1; pgrep pdivert"
@@ -160,7 +173,7 @@ p0 "head -3 /tmp/pdivert.log"
 echo "  (pdivert flipped the last payload byte and fixed the ICMP checksum)"
 echo

-bold "--- 10. shutdown ---"
+bold "--- 11. shutdown ---"
 p0 "pkill pdivert; /opt/pf/pfctl -f /dev/null; /opt/pf/pfctl -d; echo 'pf disabled'"
 p0 "lsmod | grep '^pf '"
 echo
@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+Assemble the final MP4s: silent video track + MiniMax narration + subtitles.
+
+Each narration segment was recorded as its own audio file, generated by
+MiniMax with a female voice for the language of the track.  The segments are
+placed at the moment their beat starts on screen, so the voice, the caption
+and the terminal action always agree.
+
+    ./scripts/screencast/assemble.py --phase 04-roteamento --lang en
+"""
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+REPO = os.path.dirname(os.path.dirname(HERE))
+CAPS = os.path.join(REPO, "out", "screencast", "caps")
+VO = os.path.join(REPO, "out", "screencast", "vo")
+OUT = os.path.join(REPO, "out", "screencast")
+ART = os.path.join(OUT, "art")
+
+# which phases draw the lab diagram over the terminal
+DIAGRAM_PHASES = {"00-ambiente", "04-roteamento", "05-balanceamento"}
+# phases that show the module/host instead of the firewall VM
+HOST_PHASES = {"01-implementacao"}
+
+PHASE_ORDER = ["00-ambiente", "01-implementacao", "02-ativacao", "03-regras",
+               "04-roteamento", "05-balanceamento", "06-qos"]
+
+
+def run(cmd):
+    subprocess.run(cmd, check=True)
+
+
+def probe(path):
+    out = subprocess.run(["ffprobe", "-v", "error", "-show_entries",
+                          "format=duration", "-of", "csv=p=0", path],
+                         capture_output=True, text=True).stdout.strip()
+    return float(out or 0)
+
+
+def audio_duration(path):
+    return probe(path)
+
+
+def make_video(phase, lang):
+    """Render the silent video (terminal + diagram + burned-in subtitles)."""
+    cast = os.path.join(CAPS, f"{phase}.cast")
+    nar = os.path.join(HERE, "narration", f"{phase}.{lang}.json")
+    if not os.path.exists(cast):
+        raise SystemExit(f"[assemble] missing capture: {cast}")
+    art = None
+    if os.path.isdir(ART):
+        imgs = sorted(f for f in os.listdir(ART) if f.endswith((".jpg", ".png")))
+        if imgs:
+            art = os.path.join(ART, imgs[0])
+    outdir = os.path.join(OUT, lang)
+    os.makedirs(outdir, exist_ok=True)
+    silent = os.path.join(outdir, f"{phase}.silent.mp4")
+    index = PHASE_ORDER.index(phase) + 1
+    cmd = [sys.executable, os.path.join(HERE, "render_video.py"),
+           "--cast", cast, "--narration", nar, "--out", silent,
+           "--lang", lang, "--phase-no", str(index),
+           "--phase-total", str(len(PHASE_ORDER))]
+    if phase in DIAGRAM_PHASES:
+        cmd.append("--diagram")
+    if art:
+        cmd += ["--art", art]
+    run(cmd)
+    return silent
+
+
+def mux_audio(phase, lang, silent):
+    """Lay every narration segment on the timeline and add it to the video."""
+    meta = json.load(open(os.path.join(CAPS, f"{phase}.json")))
+    beats = {b["id"]: b for b in meta["beats"]}
+    nar = json.load(open(os.path.join(HERE, "narration", f"{phase}.{lang}.json")))
+    vodir = os.path.join(VO, f"{phase}.{lang}")
+
+    segments = []
+    for i, seg in enumerate(nar["segments"]):
+        beat = beats.get(seg["beat"])
+        audio = os.path.join(vodir, f"{i:02d}-{seg['beat']}.mp3")
+        if beat is None or not os.path.exists(audio):
+            sys.stderr.write(f"[assemble] missing audio: {audio}\n")
+            continue
+        segments.append((beat["start"], audio))
+
+    tmp = os.path.join(OUT, "_tmp")
+    os.makedirs(tmp, exist_ok=True)
+    if not segments:
+        out = os.path.join(tmp, f"{phase}.{lang}.m4v")
+        run(["ffmpeg", "-y", "-loglevel", "error", "-i", silent,
+             "-c:v", "copy", "-an", out])
+        return out
+
+    vdur = probe(silent)
+    inputs = []
+    filters = []
+    # input 0 is the video; the narration files are inputs 1..N
+    for k, (start, audio) in enumerate(segments):
+        inputs += ["-i", audio]
+        delay = int(start * 1000)
+        # pad so every segment reaches the end of the video, then the mix is
+        # trimmed to the video length
+        filters.append(f"[{k + 1}:a]adelay={delay}|{delay},apad[aud{k}]")
+    mix_in = "".join(f"[aud{k}]" for k in range(len(segments)))
+    filters.append(f"{mix_in}amix=inputs={len(segments)}:normalize=0,"
+                   f"atrim=0:{vdur:.3f},asetpts=N/SR/TB[mixed]")
+    cmd = ["ffmpeg", "-y", "-loglevel", "error", "-i", silent] + inputs + \
+          ["-filter_complex", ";".join(filters),
+           "-map", "0:v", "-map", "[mixed]", "-c:v", "copy", "-c:a", "aac",
+           "-b:a", "160k", "-ar", "44100", "-ac", "2",
+           os.path.join(tmp, f"{phase}.{lang}.m4v")]
+    run(cmd)
+    return os.path.join(tmp, f"{phase}.{lang}.m4v")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--phase", required=True)
+    ap.add_argument("--lang", required=True, choices=["en", "pt"])
+    ap.add_argument("--keep-silent", action="store_true")
+    args = ap.parse_args()
+
+    phase, lang = args.phase, args.lang
+    silent = make_video(phase, lang)
+    muxed = mux_audio(phase, lang, silent)
+
+    outdir = os.path.join(OUT, lang)
+    os.makedirs(outdir, exist_ok=True)
+    final = os.path.join(outdir, f"{phase}.mp4")
+    run(["ffmpeg", "-y", "-loglevel", "error", "-i", muxed,
+         "-c", "copy", "-movflags", "+faststart", final])
+    if not args.keep_silent:
+        os.remove(silent)
+    os.remove(muxed)
+
+    dur = probe(final)
+    size = os.path.getsize(final) / 1e6
+    print(f"[assemble] {final}  {dur:.1f}s  {size:.1f}MB")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Build every screencast: capture -> narration -> video -> full movie.
+#
+#   ./scripts/screencast/build-all.sh            # everything
+#   ./scripts/screencast/build-all.sh 04-roteamento
+set -uo pipefail
+cd "$(dirname "$0")/../.."
+REPO=$(pwd)
+
+PHASES=("$@")
+[ ${#PHASES[@]} -eq 0 ] && PHASES=(00-ambiente 01-implementacao 02-ativacao 03-regras \
+	04-roteamento 05-balanceamento 06-qos)
+
+echo "== narration audio =="
+for lang in en pt; do
+	python3 scripts/screencast/make_audio.py --lang "$lang" | tail -1
+done
+
+echo "== sessions =="
+for p in "${PHASES[@]}"; do
+	# the activation phase shows the module being loaded, so it is the one
+	# that must not have it preloaded
+	extra=""
+	[ "$p" = "02-ativacao" ] || extra="--ensure-pf"
+	python3 scripts/screencast/record.py --plan "scripts/screencast/plans/$p.json" \
+		--out "out/screencast/caps/$p.cast" --pace $extra
+done
+
+echo "== videos =="
+for lang in en pt; do
+	for p in "${PHASES[@]}"; do
+		python3 scripts/screencast/assemble.py --phase "$p" --lang "$lang" || echo "FALHOU: $p $lang"
+	done
+done
+
+echo "== full movie =="
+for lang in en pt; do
+	python3 scripts/screencast/join.py --lang "$lang" || echo "FALHOU: join $lang"
+done
+
+echo
+echo "== resultado =="
+for f in out/screencast/en/*.mp4 out/screencast/pt/*.mp4; do
+	[ -e "$f" ] || continue
+	d=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$f")
+	a=$(ffprobe -v error -select_streams a -show_entries stream=codec_name -of csv=p=0 "$f")
+	printf '%-52s %6.1fs  audio=%s\n' "$f" "$d" "${a:-none}"
+done
@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""
+Join the phases into one continuous video per language, with transitions.
+
+Each phase fades into a short "chapter" card that names it, and the card
+fades into the next phase - one continuous stream, no hard cuts, so the
+viewer always knows where they are.
+
+    ./scripts/screencast/join.py --lang en
+"""
+import argparse
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+REPO = os.path.dirname(os.path.dirname(HERE))
+OUT = os.path.join(REPO, "out", "screencast")
+ART = os.path.join(OUT, "art")
+
+PHASE_ORDER = ["00-ambiente", "01-implementacao", "02-ativacao", "03-regras",
+               "04-roteamento", "05-balanceamento", "06-qos"]
+
+TITLES = {
+    "00-ambiente": ("The lab environment", "O ambiente de testes",
+                    "Four Alpine VMs under libvirt", "Quatro VMs Alpine sob libvirt"),
+    "01-implementacao": ("Implementation in the kernel", "Implementacao no kernel",
+                         "OpenBSD 8.0 sources + a Linux compatibility layer",
+                         "Fontes do OpenBSD 8.0 + camada de compatibilidade Linux"),
+    "02-ativacao": ("Activation", "Ativacao",
+                    "insmod pf.ko, then pfctl over the OpenBSD ioctl ABI",
+                    "insmod pf.ko e o pfctl pela ABI de ioctls do OpenBSD"),
+    "03-regras": ("Basic rules", "Regras basicas",
+                  "Tables, anchors, keep state, block drop",
+                  "Tabelas, anchors, keep state, block drop"),
+    "04-roteamento": ("Routing", "Roteamento",
+                      "route-to and reply-to", "route-to e reply-to"),
+    "05-balanceamento": ("Load balancing", "Balanceamento",
+                         "Pools round-robin, source-hash, dup-to",
+                         "Pools round-robin, source-hash, dup-to"),
+    "06-qos": ("Quality of service", "Qualidade de servico",
+               "hfsc queues in the data path", "Filas hfsc no caminho de dados"),
+}
+
+
+def run(cmd):
+    subprocess.run(cmd, check=True)
+
+
+def probe(path):
+    out = subprocess.run(["ffprobe", "-v", "error", "-show_entries",
+                          "format=duration", "-of", "csv=p=0", path],
+                         capture_output=True, text=True).stdout.strip()
+    return float(out or 0)
+
+
+def chapter_card(phase, lang, out_path, seconds=1.8):
+    """A short card naming the phase; it is the pivot of the crossfade."""
+    title = TITLES[phase][0 if lang == "en" else 1]
+    sub = TITLES[phase][2 if lang == "en" else 3]
+    num = PHASE_ORDER.index(phase) + 1
+    art = None
+    if os.path.isdir(ART):
+        imgs = sorted(f for f in os.listdir(ART) if f.endswith((".jpg", ".png")))
+        if imgs:
+            art = os.path.join(ART, imgs[0])
+
+    script = os.path.join(OUT, "_chapter.py")
+    with open(script, "w") as f:
+        f.write(f"""
+import os, sys
+from PIL import Image, ImageDraw, ImageFont
+W, H = 1920, 1080
+BG = (12, 16, 22); ACCENT = (88, 168, 255); FG = (240, 246, 252); MUTED = (140, 150, 165)
+mono = "/usr/share/fonts/dejavu-sans-mono-fonts/DejaVuSansMono.ttf"
+sans = "/usr/share/fonts/dejavu-sans-fonts/DejaVuSans.ttf"
+sansb = "/usr/share/fonts/dejavu-sans-fonts/DejaVuSans-Bold.ttf"
+art = {art!r}
+img = Image.new("RGB", (W, H), BG)
+if art and os.path.exists(art):
+    img = Image.blend(img, Image.open(art).resize((W, H)).convert("RGB"), 0.5)
+d = ImageDraw.Draw(img, "RGBA")
+d.rectangle([0, 0, W, 8], fill=ACCENT)
+d.text((140, 430), {title!r}, font=ImageFont.truetype(sansb, 62), fill=FG)
+d.text((140, 520), {sub!r}, font=ImageFont.truetype(sans, 30), fill=MUTED)
+d.text((140, 586), "PHASE %d OF %d" % ({num}, {len(PHASE_ORDER)}),
+       font=ImageFont.truetype(mono, 24), fill=ACCENT)
+d.text((140, 640), "PF on Linux - OpenBSD PF 8.0 no kernel Linux",
+       font=ImageFont.truetype(mono, 24), fill=MUTED)
+img.save(sys.argv[1])
+""")
+    png = out_path + ".png"
+    run([sys.executable, script, png])
+    have = subprocess.run(["ffmpeg", "-hide_banner", "-encoders"],
+                          capture_output=True, text=True).stdout
+    venc = (["-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-profile:v", "high"]
+            if "libx264" in have else
+            ["-c:v", "libopenh264", "-b:v", "6M", "-profile:v", "high"])
+    run(["ffmpeg", "-y", "-loglevel", "error", "-loop", "1", "-i", png,
+         "-t", str(seconds), "-r", "30"] + venc + ["-pix_fmt", "yuv420p", out_path])
+    os.remove(png)
+    os.remove(script)
+    return out_path
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--lang", required=True, choices=["en", "pt"])
+    ap.add_argument("--out")
+    ap.add_argument("--fade", type=float, default=0.7)
+    args = ap.parse_args()
+
+    lang = args.lang
+    tmp = os.path.join(OUT, "_tmp")
+    os.makedirs(tmp, exist_ok=True)
+
+    segs = []          # (path, duration)
+    for phase in PHASE_ORDER:
+        src = os.path.join(OUT, lang, f"{phase}.mp4")
+        if not os.path.exists(src):
+            sys.stderr.write(f"[join] missing {src}, skipping\n")
+            continue
+        segs.append((src, probe(src)))
+        card = chapter_card(phase, lang, os.path.join(tmp, f"card-{phase}.mp4"))
+        segs.append((card, probe(card)))
+
+    if not segs:
+        raise SystemExit("[join] nothing to join")
+
+    inputs = []
+    for path, _ in segs:
+        inputs += ["-i", path]
+
+    # sequential xfade: each segment fades into the next
+    filters = []
+    prev = "0:v"
+    offset = segs[0][1] - args.fade
+    for i in range(1, len(segs)):
+        filters.append(f"[{prev}][{i}:v]xfade=transition=fade:"
+                       f"duration={args.fade}:offset={offset:.3f}[v{i}]")
+        prev = f"v{i}"
+        offset += segs[i][1] - args.fade
+
+    # The audio has to follow the same timeline: with xfade the segments
+    # overlap by the fade duration, so each one starts `fade` earlier than
+    # the plain sum would suggest.
+    audio_at = []
+    acc = 0.0
+    for i, (_, dur) in enumerate(segs):
+        audio_at.append(max(0.0, acc - args.fade * i))
+        acc += dur
+
+    # Only the phase videos carry narration; the chapter cards are silent.
+    # Their input indices are the even ones in `inputs`.
+    phase_idx = [i for i in range(len(segs)) if i % 2 == 0]
+    afilters = []
+    labels = []
+    for k, i in enumerate(phase_idx):
+        ms = int(audio_at[i] * 1000)
+        afilters.append(f"[{i}:a]adelay={ms}|{ms}[a{k}]")
+        labels.append(f"[a{k}]")
+    afilters.append("".join(labels) +
+                    f"amix=inputs={len(phase_idx)}:normalize=0,"
+                    f"atrim=0:{audio_at[-1] + segs[-1][1]:.3f},"
+                    f"asetpts=N/SR/TB[amix]")
+    filters += afilters
+    amap = "[amix]"
+
+    out = args.out or os.path.join(OUT, lang, "pf-on-linux-full.mp4")
+    have = subprocess.run(["ffmpeg", "-hide_banner", "-encoders"],
+                          capture_output=True, text=True).stdout
+    if "libx264" in have:
+        venc = ["-c:v", "libx264", "-preset", "veryfast", "-crf", "20",
+                "-profile:v", "high", "-level", "4.0"]
+    elif "libopenh264" in have:
+        venc = ["-c:v", "libopenh264", "-b:v", "6M", "-profile:v", "high"]
+    else:
+        venc = ["-c:v", "libvpx-vp9", "-b:v", "0", "-crf", "30", "-row-mt", "1",
+                "-cpu-used", "4"]
+    # the phases already carry their narration; the cards are silent
+    run(["ffmpeg", "-y", "-loglevel", "error"] + inputs +
+        ["-filter_complex", ";".join(filters), "-map", f"[{prev}]",
+         "-map", amap] + venc +
+        ["-pix_fmt", "yuv420p", "-movflags", "+faststart", out])
+    print(f"[join] {out}  {probe(out):.1f}s")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Generate the narration audio for every screencast phase with MiniMax TTS.
+
+Female voices, one per language:
+    en -> English_ConfidentWoman
+    pt -> Portuguese_ConfidentWoman
+
+Each *segment* of a narration script becomes its own audio file, so the
+renderer can start the voice exactly when the matching beat appears on
+screen and burn the same sentence as a subtitle.
+
+    ./scripts/screencast/make_audio.py --lang en
+    ./scripts/screencast/make_audio.py --lang pt --phase 04-roteamento
+"""
+import argparse
+import base64
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+NARR = os.path.join(HERE, "narration")
+VO_DIR = os.path.join(HERE, "..", "..", "out", "screencast", "vo")
+
+VOICES = {
+    "en": {"voice_id": "English_ConfidentWoman", "language_boost": "English"},
+    "pt": {"voice_id": "Portuguese_ConfidentWoman", "language_boost": "Portuguese"},
+}
+
+# MiniMax occasionally stumbles on the punctuation of long sentences; keeping
+# the text plain (no dashes, no slashes) makes the prosody predictable.
+MODEL = "speech-02-hd"
+API = "https://api.minimax.io/v1/t2a_v2"
+
+
+def decode_audio(payload):
+    """MiniMax returns the audio as a hex string (it starts with the ASCII
+    bytes of the ID3 header, 49443304).  Older/other endpoints use base64,
+    so both are handled."""
+    if len(payload) > 8 and all(c in "0123456789abcdefABCDEF" for c in payload[:64]):
+        return bytes.fromhex(payload)
+    data = payload.replace("-", "+").replace("_", "/")
+    data += "=" * (-len(data) % 4)
+    return base64.b64decode(data, validate=False)
+
+
+def tts(text, voice, lang, out_path, retries=3):
+    body = {
+        "model": MODEL,
+        "text": text,
+        "stream": False,
+        "voice_setting": {
+            "voice_id": voice["voice_id"],
+            "speed": 0.97, "vol": 1.0, "pitch": 0, "emotion": "neutral",
+        },
+        "audio_setting": {"sample_rate": 44100, "bitrate": 128000,
+                          "format": "mp3", "channel": 1},
+        "language_boost": voice["language_boost"],
+    }
+    key = os.environ.get("MINIMAX_API_KEY")
+    if not key:
+        raise SystemExit("MINIMAX_API_KEY is not set")
+    for attempt in range(retries):
+        req = urllib.request.Request(
+            API, data=json.dumps(body).encode(),
+            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=120) as r:
+                data = json.loads(r.read())
+            if data.get("base_resp", {}).get("status_code") != 0:
+                raise RuntimeError(str(data.get("base_resp")))
+            audio = data.get("data", {}).get("audio")
+            if not audio:
+                raise RuntimeError("no audio in response")
+            with open(out_path, "wb") as f:
+                f.write(decode_audio(audio))
+            return True
+        except Exception as exc:                     # noqa: BLE001
+            sys.stderr.write(f"[tts] attempt {attempt + 1} failed: {exc}\n")
+            time.sleep(2 + attempt * 3)
+    return False
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--lang", required=True, choices=["en", "pt"])
+    ap.add_argument("--phase", help="only this phase")
+    ap.add_argument("--force", action="store_true")
+    args = ap.parse_args()
+
+    voice = VOICES[args.lang]
+    files = sorted(f for f in os.listdir(NARR) if f.endswith(f".{args.lang}.json"))
+    if args.phase:
+        files = [f for f in files if f.startswith(args.phase + ".")]
+
+    total = 0
+    for fn in files:
+        phase = fn.split(".")[0]
+        script = json.load(open(os.path.join(NARR, fn)))
+        outdir = os.path.abspath(os.path.join(VO_DIR, f"{phase}.{args.lang}"))
+        os.makedirs(outdir, exist_ok=True)
+        for i, seg in enumerate(script["segments"]):
+            out = os.path.join(outdir, f"{i:02d}-{seg['beat']}.mp3")
+            if os.path.exists(out) and not args.force:
+                print(f"skip {phase}.{args.lang} seg{i} ({seg['beat']})")
+                total += 1
+                continue
+            ok = tts(seg["text"], voice, args.lang, out)
+            size = os.path.getsize(out) if os.path.exists(out) else 0
+            print(f"{'ok ' if ok else 'FAIL'} {phase}.{args.lang} seg{i} "
+                  f"({seg['beat']}) {size} bytes")
+            total += 1
+    print(f"[audio] {total} segments processed for lang={args.lang}")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""
+Write the narration scripts for every screencast phase, in English and in
+Brazilian Portuguese.
+
+Each segment belongs to one *beat* of the recorded session (see
+scripts/screencast/plans/*.json).  The renderer places the segment's audio at
+the moment that beat starts on screen, and burns the same text as a subtitle,
+so the voice, the caption and the terminal action always agree.
+
+A segment may also carry:
+  highlight      - nodes of the lab diagram to light up while it is spoken
+  diagram_caption - one-line caption shown inside the diagram panel
+"""
+import json
+import os
+
+OUT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "narration")
+os.makedirs(OUT, exist_ok=True)
+
+EN_VOICE = "English_ConfidentWoman"
+PT_VOICE = "Portuguese_ConfidentWoman"
+
+PHASES = {}
+
+# ------------------------------------------------------------------ 00 ----
+PHASES["00-ambiente"] = {
+    "en": {
+        "title": "The lab environment",
+        "subtitle": "Four Alpine VMs under libvirt, running a kernel built from source",
+        "segments": [
+            {"beat": "b1", "text": "Welcome to the PF on Linux demonstration. Before we look at the firewall itself, let me show you the environment where everything runs. These are four virtual machines managed by libvirt, all of them Alpine Linux, and the machine you are looking at is the firewall: a kernel we compiled from source, version seven point three point four, with our port of the OpenBSD packet filter built in as a module."},
+            {"beat": "b2", "text": "The firewall has four interfaces. The management interface on the virtual network the hypervisor uses to reach us. Then three transit networks: ten point zero point one, where the client lives; ten point zero point two, where the server lives; and ten point zero point three, a second gateway we use to demonstrate routing decisions.", "highlight": ["cli", "pf0", "srv", "gw2"], "diagram_caption": "three transit networks, four interfaces"},
+            {"beat": "b3", "text": "The OpenBSD tools are installed on this machine exactly as they ship: the original pfctl, a pflog daemon and our divert tool. The module is not loaded yet, which is where we will start.", "highlight": ["pf0"], "diagram_caption": "pfctl, pflogd and pdivert, straight from OpenBSD"},
+            {"beat": "b4", "text": "And from the firewall we can reach the other machines directly. The client is on ten point zero point one point ten, the server on ten point zero point two point twenty, and the second gateway on ten point zero point three point two. Every command in this demonstration is real traffic crossing real interfaces.", "highlight": ["cli", "pf0", "srv", "gw2"], "diagram_caption": "cli, srv and gw2 reachable from pf0"},
+        ],
+    },
+    "pt": {
+        "title": "O ambiente de testes",
+        "subtitle": "Quatro VMs Alpine sob libvirt, rodando um kernel compilado do fonte",
+        "segments": [
+            {"beat": "b1", "text": "Bem-vindo à demonstração do PF on Linux. Antes de falar do firewall em si, deixa eu mostrar o ambiente onde tudo acontece. São quatro máquinas virtuais administradas pelo libvirt, todas com Alpine Linux, e a máquina que você está vendo é o firewall: um kernel que compilamos do fonte, versão sete ponto três ponto quatro, com o nosso port do packet filter do OpenBSD compilado dentro como módulo."},
+            {"beat": "b2", "text": "O firewall tem quatro interfaces. A interface de gerência, na rede virtual que o hypervisor usa para falar com a gente. E depois três redes de trânsito: dez ponto zero ponto um, onde mora o cliente; dez ponto zero ponto dois, onde mora o servidor; e dez ponto zero ponto três, um segundo gateway que vamos usar para demonstrar decisões de roteamento.", "highlight": ["cli", "pf0", "srv", "gw2"], "diagram_caption": "três redes de transito, quatro interfaces"},
+            {"beat": "b3", "text": "As ferramentas do OpenBSD estão instaladas nesta máquina exatamente como são distribuídas: o pfctl original, um daemon de pflog e a nossa ferramenta de divert. O módulo ainda não está carregado, e é por aí que a gente começa.", "highlight": ["pf0"], "diagram_caption": "pfctl, pflogd e pdivert originais do OpenBSD"},
+            {"beat": "b4", "text": "E do firewall a gente alcança as outras máquinas diretamente. O cliente está em dez ponto zero ponto um ponto dez, o servidor em dez ponto zero ponto dois ponto vinte, e o segundo gateway em dez ponto zero ponto três ponto dois. Todo comando desta demonstração é tráfego real cruzando interfaces reais.", "highlight": ["cli", "pf0", "srv", "gw2"], "diagram_caption": "cli, srv e gw2 alcançáveis a partir do pf0"},
+        ],
+    },
+}
+
+# ------------------------------------------------------------------ 01 ----
+PHASES["01-implementacao"] = {
+    "en": {
+        "title": "Implementation in the kernel",
+        "subtitle": "OpenBSD 8.0 sources plus a Linux compatibility layer equals pf.ko",
+        "segments": [
+            {"beat": "b1", "text": "This is the heart of the work. We did not rewrite the firewall. We took the OpenBSD eight point zero sources, nearly twenty seven thousand lines of C, and we kept them almost intact. On top of that we wrote a compatibility layer, about seven thousand lines, that translates the BSD kernel interfaces into Linux ones."},
+            {"beat": "b2", "text": "The result is a normal Linux kernel module. Here modinfo shows us the license, the description and the vermagic, which tells us exactly which kernel this object was compiled against."},
+            {"beat": "b3", "text": "The vermagic line matters: it is the kernel version, the compiler flags and the module signature. Load the wrong one and the kernel refuses it. Everything you will see in the next minutes is running inside that module."},
+            {"beat": "b4", "text": "This file is what we load into the firewall. A single artifact, built out of tree, carrying the entire OpenBSD packet filter."},
+        ],
+    },
+    "pt": {
+        "title": "Implementação no kernel",
+        "subtitle": "Fontes do OpenBSD 8.0 mais uma camada de compatibilidade Linux resultam em pf.ko",
+        "segments": [
+            {"beat": "b1", "text": "Aqui está o coração do trabalho. A gente não reescreveu o firewall. Pegamos as fontes do OpenBSD oito ponto zero, quase vinte e sete mil linhas de C, e mantivemos praticamente intactas. Em cima disso escrevemos uma camada de compatibilidade, cerca de sete mil linhas, que traduz as interfaces de kernel do BSD para as do Linux."},
+            {"beat": "b2", "text": "O resultado é um módulo de kernel Linux comum. Aqui o modinfo mostra a licença, a descrição e o vermagic, que nos diz exatamente com qual kernel este objeto foi compilado."},
+            {"beat": "b3", "text": "A linha do vermagic importa: é a versão do kernel, as flags do compilador e a assinatura do módulo. Carregar o arquivo errado e o kernel recusa. Tudo que você vai ver nos próximos minutos roda dentro desse módulo."},
+            {"beat": "b4", "text": "Este é o arquivo que carregamos no firewall. Um único artefato, compilado fora da árvore do kernel, carregando o packet filter inteiro do OpenBSD."},
+        ],
+    },
+}
+
+# ------------------------------------------------------------------ 02 ----
+PHASES["02-ativacao"] = {
+    "en": {
+        "title": "Activation",
+        "subtitle": "insmod pf.ko, then pfctl talks to it over the OpenBSD ioctl ABI",
+        "segments": [
+            {"beat": "b1", "text": "First we make sure nothing is loaded, so the activation is honest. No module, no firewall."},
+            {"beat": "b2", "text": "Now we insert it. The kernel accepts the module and the log shows our initialization message. This is the OpenBSD engine running inside Linux."},
+            {"beat": "b3", "text": "The device appears, owned by root with mode six hundred, exactly like the BSD original, and the module shows up in the list of loaded modules."},
+            {"beat": "b4", "text": "pfctl is the original OpenBSD tool. We enable the firewall and ask for its status. The ioctl interface, the statistics table, the rule counters, all of it is the OpenBSD ABI, unchanged."},
+            {"beat": "b5", "text": "The ruleset is still empty, and that is exactly right: with no rules, pf blocks everything and returns. The engine is armed and waiting for instructions."},
+        ],
+    },
+    "pt": {
+        "title": "Ativação",
+        "subtitle": "insmod pf.ko e o pfctl conversa com ele pela ABI de ioctls do OpenBSD",
+        "segments": [
+            {"beat": "b1", "text": "Primeiro a gente garante que não tem nada carregado, para a ativação ser honesta. Sem módulo, sem firewall."},
+            {"beat": "b2", "text": "Agora inserimos. O kernel aceita o módulo e o log mostra a nossa mensagem de inicialização. Este é o motor do OpenBSD rodando dentro do Linux."},
+            {"beat": "b3", "text": "O dispositivo aparece, do root, com modo seiscentos, exatamente como no BSD original, e o módulo aparece na lista de módulos carregados."},
+            {"beat": "b4", "text": "O pfctl é a ferramenta original do OpenBSD. Habilitamos o firewall e pedimos o status. A interface de ioctl, a tabela de estatísticas, os contadores das regras: tudo é a ABI do OpenBSD, sem alteração."},
+            {"beat": "b5", "text": "O ruleset ainda está vazio, e isso está certo: sem regras, o pf bloqueia tudo e devolve. O motor está armado e esperando instruções."},
+        ],
+    },
+}
+
+# ------------------------------------------------------------------ 03 ----
+PHASES["03-regras"] = {
+    "en": {
+        "title": "Basic rules",
+        "subtitle": "Tables, anchors, keep state and block drop",
+        "segments": [
+            {"beat": "b1", "text": "Now we write a real pf dot conf. This is the original OpenBSD syntax: a table with the trusted network, an anchor, and the usual quick rules with keep state. pfctl parses it and the kernel accepts it."},
+            {"beat": "b2", "text": "pfctl shows us what the kernel understood: the rules as they were compiled, the list of tables, and the contents of the trusted table."},
+            {"beat": "b3", "text": "Let the traffic through. From the client we ping the server, and the firewall creates a state. You can see it in the state table: the five tuple, the timeout, the counters."},
+            {"beat": "b4", "text": "Now the same thing with a drop. We replace the pass rule with a block drop rule for the client network, and reload."},
+            {"beat": "b5", "text": "The ping is dead. One hundred percent packet loss. And the rule counters show the packets that were evaluated and the ones that were blocked. This is a stateful firewall behaving exactly like the original."},
+            {"beat": "b6", "text": "Finally, anchors. We load a ruleset into the anchor called demo, and pfctl lists the rules that live inside it, separately from the main ruleset."},
+        ],
+    },
+    "pt": {
+        "title": "Regras básicas",
+        "subtitle": "Tabelas, anchors, keep state e block drop",
+        "segments": [
+            {"beat": "b1", "text": "Agora escrevemos um pf ponto conf de verdade. Esta é a sintaxe original do OpenBSD: uma tabela com a rede confiável, um anchor, e as regras quick de sempre com keep state. O pfctl faz o parsing e o kernel aceita."},
+            {"beat": "b2", "text": "O pfctl nos mostra o que o kernel entendeu: as regras como foram compiladas, a lista de tabelas e o conteúdo da tabela trusted."},
+            {"beat": "b3", "text": "Deixa o tráfego passar. Do cliente a gente dá ping no servidor, e o firewall cria um estado. Você vê isso na tabela de estados: a tupla de cinco campos, o timeout, os contadores."},
+            {"beat": "b4", "text": "Agora a mesma coisa com um drop. Trocamos a regra de pass por uma regra block drop para a rede do cliente, e recarregamos."},
+            {"beat": "b5", "text": "O ping morreu. Cem por cento de perda. E os contadores da regra mostram os pacotes avaliados e os bloqueados. Este é um firewall stateful se comportando exatamente como o original."},
+            {"beat": "b6", "text": "Por fim, os anchors. Carregamos um ruleset no anchor chamado demo, e o pfctl lista as regras que moram dentro dele, separadamente do ruleset principal."},
+        ],
+    },
+}
+
+# ------------------------------------------------------------------ 04 ----
+PHASES["04-roteamento"] = {
+    "en": {
+        "title": "Routing",
+        "subtitle": "route-to forces the next hop, reply-to forces the way back",
+        "segments": [
+            {"beat": "b1", "text": "Now the routing features. This rule matches traffic from the client to the server and sends it through the second gateway, ten point zero point three point two, instead of the normal path. pfctl shows the rule exactly as the kernel stored it.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "route-to: normal path is eth2, forced path is eth3"},
+            {"beat": "b2", "text": "To prove where the packet actually went, we capture on both interfaces at the same time: eth three, towards the gateway, and eth two, towards the server."},
+            {"beat": "b3", "text": "And now the client pings the server.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "the request leaves through eth3, to the gateway"},
+            {"beat": "b4", "text": "The evidence is in the captures. The request appears on eth three, on the way to the gateway, and it never appears on eth two. The firewall decided the next hop, not the routing table.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "1 request on eth3, 0 on eth2"},
+            {"beat": "b5", "text": "The other half of the problem is the way back. reply to forces the reply of a flow to leave through a different gateway than the request came in, which is how you build asymmetric routing.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "reply-to: the answer leaves through another gateway"},
+            {"beat": "b6", "text": "We capture eth three again and also eth one, the link where the client is."},
+            {"beat": "b7", "text": "The replies show up on eth three, on the gateway link, and not on the client link. The request and the reply now take different paths, exactly as commanded.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "reply on eth3, nothing on the client link"},
+        ],
+    },
+    "pt": {
+        "title": "Roteamento",
+        "subtitle": "route-to força o próximo salto, reply-to força o caminho de volta",
+        "segments": [
+            {"beat": "b1", "text": "Agora as funcionalidades de roteamento. Esta regra casa com o tráfego do cliente para o servidor e o manda pelo segundo gateway, dez ponto zero ponto três ponto dois, em vez do caminho normal. O pfctl mostra a regra exatamente como o kernel guardou.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "route-to: o caminho normal e' eth2; o forcado, eth3"},
+            {"beat": "b2", "text": "Para provar por onde o pacote realmente passou, capturamos nas duas interfaces ao mesmo tempo: eth três, rumo ao gateway, e eth dois, rumo ao servidor."},
+            {"beat": "b3", "text": "E agora o cliente dá ping no servidor.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "o pedido sai por eth3, rumo ao gateway"},
+            {"beat": "b4", "text": "A prova está nas capturas. O pedido aparece na eth três, indo para o gateway, e nunca aparece na eth dois. Quem decidiu o próximo salto foi o firewall, não a tabela de rotas.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "1 pedido em eth3, 0 em eth2"},
+            {"beat": "b5", "text": "A outra metade do problema é o caminho de volta. O reply to força a resposta de um fluxo a sair por um gateway diferente do por onde o pedido entrou, que é assim que se constrói roteamento assimétrico.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "reply-to: a resposta sai por um gateway diferente"},
+            {"beat": "b6", "text": "Capturamos a eth três de novo e também a eth um, o link onde está o cliente."},
+            {"beat": "b7", "text": "As respostas aparecem na eth três, no link do gateway, e não no link do cliente. O pedido e a resposta agora seguem caminhos diferentes, exatamente como foi pedido.", "highlight": ["cli", "pf0", "gw2"], "diagram_caption": "resposta em eth3, nada no link do cliente"},
+        ],
+    },
+}
+
+# ------------------------------------------------------------------ 05 ----
+PHASES["05-balanceamento"] = {
+    "en": {
+        "title": "Load balancing",
+        "subtitle": "NAT pools in round-robin and source-hash, plus dup-to",
+        "segments": [
+            {"beat": "b1", "text": "Load balancing in pf is done with pools. This rule translates the source of the client network into a pool of two addresses, the two gateways of the firewall, and selects between them round robin.", "highlight": ["cli", "pf0", "srv"], "diagram_caption": "pool { 10.0.2.1, 10.0.3.1 }: round-robin"},
+            {"beat": "b2", "text": "We capture on the interface towards the server to see which source address each packet carries."},
+            {"beat": "b3", "text": "Six packets from the client."},
+            {"beat": "b4", "text": "And the capture shows the truth: three packets went out with one address, three with the other. The pool is really rotating between its members, and the server sees a balanced load.", "highlight": ["cli", "pf0", "srv"], "diagram_caption": "3 packets with each source address"},
+            {"beat": "b5", "text": "Sometimes you do not want rotation. source hash keeps a given origin always mapped to the same pool member, which is what you want when a session has to be sticky.", "highlight": ["cli", "pf0", "srv"], "diagram_caption": "pool { 10.0.2.1, 10.0.3.1 }: source-hash"},
+            {"beat": "b6", "text": "Four more packets, and now every single one carries the same source address. The mapping is stable per origin.", "highlight": ["cli", "pf0", "srv"], "diagram_caption": "every packet with the same source"},
+            {"beat": "b7", "text": "And dup to is the mirror case: the packet keeps its normal path, and a copy is delivered to the second gateway. We count the requests on both interfaces: one on the normal path, one on the mirrored path. The packet was duplicated, not moved.", "highlight": ["cli", "pf0", "srv", "gw2"], "diagram_caption": "dup-to: the normal path and the mirrored copy"},
+        ],
+    },
+    "pt": {
+        "title": "Balanceamento",
+        "subtitle": "Pools de NAT em round-robin e source-hash, mais o dup-to",
+        "segments": [
+            {"beat": "b1", "text": "O balanceamento no pf é feito com pools. Esta regra traduz a origem da rede do cliente para um pool de dois endereços, os dois gateways do firewall, e escolhe entre eles em round robin.", "highlight": ["cli", "pf0", "srv"], "diagram_caption": "pool { 10.0.2.1, 10.0.3.1 }: round-robin"},
+            {"beat": "b2", "text": "Capturamos na interface que vai para o servidor para ver qual endereço de origem cada pacote carrega."},
+            {"beat": "b3", "text": "Seis pacotes vindo do cliente."},
+            {"beat": "b4", "text": "E a captura mostra a verdade: três pacotes saíram com um endereço, três com o outro. O pool está realmente rodando entre os membros, e o servidor enxerga a carga balanceada.", "highlight": ["cli", "pf0", "srv"], "diagram_caption": "3 pacotes com cada endereço de origem"},
+            {"beat": "b5", "text": "Às vezes você não quer rotação. O source hash mantém uma origem sempre mapeada para o mesmo membro do pool, que é o que se quer quando a sessão precisa ser sticky.", "highlight": ["cli", "pf0", "srv"], "diagram_caption": "pool { 10.0.2.1, 10.0.3.1 }: source-hash"},
+            {"beat": "b6", "text": "Mais quatro pacotes, e agora todos carregam o mesmo endereço de origem. O mapeamento é estável por origem.", "highlight": ["cli", "pf0", "srv"], "diagram_caption": "todos os pacotes com a mesma origem"},
+            {"beat": "b7", "text": "E o dup to é o caso espelho: o pacote mantém o caminho normal e uma cópia é entregue no segundo gateway. Contamos os pedidos nas duas interfaces: um no caminho normal, um no caminho espelhado. O pacote foi duplicado, não movido.", "highlight": ["cli", "pf0", "srv", "gw2"], "diagram_caption": "dup-to: o caminho normal e a cópia espelhada"},
+        ],
+    },
+}
+
+# ------------------------------------------------------------------ 06 ----
+PHASES["06-qos"] = {
+    "en": {
+        "title": "Quality of service",
+        "subtitle": "OpenBSD 8.0 queues: hfsc classes attached to the interface",
+        "segments": [
+            {"beat": "b1", "text": "The last piece is quality of service. This is the OpenBSD eight point zero queue syntax: a root class with ten megabits of bandwidth, a leaf class with two megabits as the default, and a rule that steers the traffic from the client to that leaf class."},
+            {"beat": "b2", "text": "pfctl shows the queues with their statistics, and the rule set shows the queue attached to the rule."},
+            {"beat": "b3", "text": "Now we move real traffic through the queue. On the server we prepare two megabytes and listen on port ninety ninety five."},
+            {"beat": "b4", "text": "And the client downloads it, through the firewall, through the class."},
+            {"beat": "b5", "text": "Two million bytes transferred, and look at the queue counters: the hfsc class counted the packets and the bytes. The scheduler is in the data path, not just in the configuration."},
+        ],
+    },
+    "pt": {
+        "title": "Qualidade de serviço",
+        "subtitle": "Filas do OpenBSD 8.0: classes hfsc anexadas à interface",
+        "segments": [
+            {"beat": "b1", "text": "A última peça é qualidade de serviço. Esta é a sintaxe de filas do OpenBSD oito ponto zero: uma classe raiz com dez megabits de banda, uma classe folha com dois megabits como default, e uma regra que direciona o tráfego do cliente para essa classe folha."},
+            {"beat": "b2", "text": "O pfctl mostra as filas com as estatísticas, e o ruleset mostra a fila anexada à regra."},
+            {"beat": "b3", "text": "Agora movemos tráfego de verdade pela fila. No servidor preparamos dois megabytes e escutamos na porta noventa e noventa e cinco."},
+            {"beat": "b4", "text": "E o cliente baixa isso, passando pelo firewall, passando pela classe."},
+            {"beat": "b5", "text": "Dois milhões de bytes transferidos, e olha os contadores das filas: a classe hfsc contou os pacotes e os bytes. O escalonador está no caminho de dados, não só na configuração."},
+        ],
+    },
+}
+
+# the diagram is drawn over these phases
+DIAGRAM_PHASES = {"00-ambiente", "04-roteamento", "05-balanceamento"}
+
+for phase, langs in PHASES.items():
+    for lang, data in langs.items():
+        out = {
+            "phase": phase, "lang": lang,
+            "voice": EN_VOICE if lang == "en" else PT_VOICE,
+            "title": data["title"], "subtitle": data["subtitle"],
+            "segments": data["segments"],
+        }
+        with open(os.path.join(OUT, f"{phase}.{lang}.json"), "w") as f:
+            json.dump(out, f, ensure_ascii=False, indent=2)
+print(f"wrote {sum(len(v) for v in PHASES.values())} narration scripts to {OUT}")
@@ -0,0 +1,43 @@
+{
+  "phase": "00-ambiente",
+  "lang": "en",
+  "voice": "English_ConfidentWoman",
+  "title": "The lab environment",
+  "subtitle": "Four Alpine VMs under libvirt, running a kernel built from source",
+  "segments": [
+    {
+      "beat": "b1",
+      "text": "Welcome to the PF on Linux demonstration. Before we look at the firewall itself, let me show you the environment where everything runs. These are four virtual machines managed by libvirt, all of them Alpine Linux, and the machine you are looking at is the firewall: a kernel we compiled from source, version seven point three point four, with our port of the OpenBSD packet filter built in as a module."
+    },
+    {
+      "beat": "b2",
+      "text": "The firewall has four interfaces. The management interface on the virtual network the hypervisor uses to reach us. Then three transit networks: ten point zero point one, where the client lives; ten point zero point two, where the server lives; and ten point zero point three, a second gateway we use to demonstrate routing decisions.",
+      "highlight": [
+        "cli",
+        "pf0",
+        "srv",
+        "gw2"
+      ],
+      "diagram_caption": "three transit networks, four interfaces"
+    },
+    {
+      "beat": "b3",
+      "text": "The OpenBSD tools are installed on this machine exactly as they ship: the original pfctl, a pflog daemon and our divert tool. The module is not loaded yet, which is where we will start.",
+      "highlight": [
+        "pf0"
+      ],
+      "diagram_caption": "pfctl, pflogd and pdivert, straight from OpenBSD"
+    },
+    {
+      "beat": "b4",
+      "text": "And from the firewall we can reach the other machines directly. The client is on ten point zero point one point ten, the server on ten point zero point two point twenty, and the second gateway on ten point zero point three point two. Every command in this demonstration is real traffic crossing real interfaces.",
+      "highlight": [
+        "cli",
+        "pf0",
+        "srv",
+        "gw2"
+      ],
+      "diagram_caption": "cli, srv and gw2 reachable from pf0"
+    }
+  ]
+}
@@ -0,0 +1,43 @@
+{
+  "phase": "00-ambiente",
+  "lang": "pt",
+  "voice": "Portuguese_ConfidentWoman",
+  "title": "O ambiente de testes",
+  "subtitle": "Quatro VMs Alpine sob libvirt, rodando um kernel compilado do fonte",
+  "segments": [
+    {
+      "beat": "b1",
+      "text": "Bem-vindo à demonstração do PF on Linux. Antes de falar do firewall em si, deixa eu mostrar o ambiente onde tudo acontece. São quatro máquinas virtuais administradas pelo libvirt, todas com Alpine Linux, e a máquina que você está vendo é o firewall: um kernel que compilamos do fonte, versão sete ponto três ponto quatro, com o nosso port do packet filter do OpenBSD compilado dentro como módulo."
+    },
+    {
+      "beat": "b2",
+      "text": "O firewall tem quatro interfaces. A interface de gerência, na rede virtual que o hypervisor usa para falar com a gente. E depois três redes de trânsito: dez ponto zero ponto um, onde mora o cliente; dez ponto zero ponto dois, onde mora o servidor; e dez ponto zero ponto três, um segundo gateway que vamos usar para demonstrar decisões de roteamento.",
+      "highlight": [
+        "cli",
+        "pf0",
+        "srv",
+        "gw2"
+      ],
+      "diagram_caption": "três redes de transito, quatro interfaces"
+    },
+    {
+      "beat": "b3",
+      "text": "As ferramentas do OpenBSD estão instaladas nesta máquina exatamente como são distribuídas: o pfctl original, um daemon de pflog e a nossa ferramenta de divert. O módulo ainda não está carregado, e é por aí que a gente começa.",
+      "highlight": [
+        "pf0"
+      ],
+      "diagram_caption": "pfctl, pflogd e pdivert originais do OpenBSD"
+    },
+    {
+      "beat": "b4",
+      "text": "E do firewall a gente alcança as outras máquinas diretamente. O cliente está em dez ponto zero ponto um ponto dez, o servidor em dez ponto zero ponto dois ponto vinte, e o segundo gateway em dez ponto zero ponto três ponto dois. Todo comando desta demonstração é tráfego real cruzando interfaces reais.",
+      "highlight": [
+        "cli",
+        "pf0",
+        "srv",
+        "gw2"
+      ],
+      "diagram_caption": "cli, srv e gw2 alcançáveis a partir do pf0"
+    }
+  ]
+}
@@ -0,0 +1,25 @@
+{
+  "phase": "01-implementacao",
+  "lang": "en",
+  "voice": "English_ConfidentWoman",
+  "title": "Implementation in the kernel",
+  "subtitle": "OpenBSD 8.0 sources plus a Linux compatibility layer equals pf.ko",
+  "segments": [
+    {
+      "beat": "b1",
+      "text": "This is the heart of the work. We did not rewrite the firewall. We took the OpenBSD eight point zero sources, nearly twenty seven thousand lines of C, and we kept them almost intact. On top of that we wrote a compatibility layer, about seven thousand lines, that translates the BSD kernel interfaces into Linux ones."
+    },
+    {
+      "beat": "b2",
+      "text": "The result is a normal Linux kernel module. Here modinfo shows us the license, the description and the vermagic, which tells us exactly which kernel this object was compiled against."
+    },
+    {
+      "beat": "b3",
+      "text": "The vermagic line matters: it is the kernel version, the compiler flags and the module signature. Load the wrong one and the kernel refuses it. Everything you will see in the next minutes is running inside that module."
+    },
+    {
+      "beat": "b4",
+      "text": "This file is what we load into the firewall. A single artifact, built out of tree, carrying the entire OpenBSD packet filter."
+    }
+  ]
+}
@@ -0,0 +1,25 @@
+{
+  "phase": "01-implementacao",
+  "lang": "pt",
+  "voice": "Portuguese_ConfidentWoman",
+  "title": "Implementação no kernel",
+  "subtitle": "Fontes do OpenBSD 8.0 mais uma camada de compatibilidade Linux resultam em pf.ko",
+  "segments": [
+    {
+      "beat": "b1",
+      "text": "Aqui está o coração do trabalho. A gente não reescreveu o firewall. Pegamos as fontes do OpenBSD oito ponto zero, quase vinte e sete mil linhas de C, e mantivemos praticamente intactas. Em cima disso escrevemos uma camada de compatibilidade, cerca de sete mil linhas, que traduz as interfaces de kernel do BSD para as do Linux."
+    },
+    {
+      "beat": "b2",
+      "text": "O resultado é um módulo de kernel Linux comum. Aqui o modinfo mostra a licença, a descrição e o vermagic, que nos diz exatamente com qual kernel este objeto foi compilado."
+    },
+    {
+      "beat": "b3",
+      "text": "A linha do vermagic importa: é a versão do kernel, as flags do compilador e a assinatura do módulo. Carregar o arquivo errado e o kernel recusa. Tudo que você vai ver nos próximos minutos roda dentro desse módulo."
+    },
+    {
+      "beat": "b4",
+      "text": "Este é o arquivo que carregamos no firewall. Um único artefato, compilado fora da árvore do kernel, carregando o packet filter inteiro do OpenBSD."
+    }
+  ]
+}
@@ -0,0 +1,29 @@
+{
+  "phase": "02-ativacao",
+  "lang": "en",
+  "voice": "English_ConfidentWoman",
+  "title": "Activation",
+  "subtitle": "insmod pf.ko, then pfctl talks to it over the OpenBSD ioctl ABI",
+  "segments": [
+    {
+      "beat": "b1",
+      "text": "First we make sure nothing is loaded, so the activation is honest. No module, no firewall."
+    },
+    {
+      "beat": "b2",
+      "text": "Now we insert it. The kernel accepts the module and the log shows our initialization message. This is the OpenBSD engine running inside Linux."
+    },
+    {
+      "beat": "b3",
+      "text": "The device appears, owned by root with mode six hundred, exactly like the BSD original, and the module shows up in the list of loaded modules."
+    },
+    {
+      "beat": "b4",
+      "text": "pfctl is the original OpenBSD tool. We enable the firewall and ask for its status. The ioctl interface, the statistics table, the rule counters, all of it is the OpenBSD ABI, unchanged."
+    },
+    {
+      "beat": "b5",
+      "text": "The ruleset is still empty, and that is exactly right: with no rules, pf blocks everything and returns. The engine is armed and waiting for instructions."
+    }
+  ]
+}
Author	SHA1	Message	Date
lgcosta	cc67531602	Screencasts v2: real shell sessions, MiniMax narration (EN/PT), lab diagram O problema da primeira serie era a sensacao de 'quadro a quadro': a captura era a saida de um script despejada em blocos. Agora cada video e uma sessao shell de verdade. - record.py: abre um pty, faz SSH no firewall e digita os comandos tecla a tecla (~34 c/s, com jitter). O tty remoto ecoa, o kernel responde ao vivo; a captura e asciicast v2 com timestamps. 'bash --noediting' evita que o editor de linha redesenhe o comando e o tty o repita (a linha aparecia duplicada). - record.py --pace: segura a tela enquanto a voz fala - cada batida dura o trecho de audio que a acompanha, de modo que uma unica captura serve as duas versoes de idioma. - record.py --ensure-pf: garante pf.ko carregado antes de gravar. Sem isso uma fase que roda 'rmmod' (ativacao) pode derrubar o /dev/pf de outra gravacao concorrentes - foi exatamente o que quebrou a fase de roteamento na primeira tentativa. - make_audio.py: geracao da narracao pelo MiniMax TTS, uma voz feminina por idioma (English_ConfidentWoman / Portuguese_ConfidentWoman), um arquivo por segmento. A API devolve o audio em hexadecimal, nao base64. - render_video.py: reproduz a captura por um emulador de terminal e escreve os frames direto no ffmpeg como RGB bruto (um PNG por frame era uma ordem de grandeza mais lento). Desenha o diagrama de rede do lab por cima do terminal nas fases de roteamento e balanceamento, destacando o caminho em discussao, e queima a legenda da narracao. - assemble.py: mixa os segmentos de audio na linha do tempo. - join.py: emenda as fases com crossfade sobre um cartao de capitulo e sincroniza o audio na mesma linha do tempo. - build-all.sh: roda o pipeline inteiro. Arte de fundo e audio vem do MiniMax; a geracao de video do MiniMax nao esta habilitada nesta conta (erro 2068 em todos os modelos), entao as transicoes sao renderizadas localmente com ffmpeg. 16 videos: 7 fases + filme completo, em ingles e portugues, com legenda queimada.	2026-11-12 10:57:29 -03:00
lgcosta	fe324259c0	Screencasts: seis videos silenciosos 1080p30 da demonstracao Novo pipeline de video: scripts/screencast/render.py roda uma fase em um pty, emula o terminal com pyte, gera frames PNG e mux com ffmpeg (H.264, yuv420p, +faststart, sem trilha de audio). Fallback de encoder: libx264 -> libopenh264 -> VP9. Fases (scripts/screencast/phases/, uma sessao real contra o lab por video): 1. implementacao no kernel - fontes OpenBSD + compat + build limpo do pf.ko 2. ativacao - insmod, /dev/pf, pfctl -e, pfctl -s info 3. regras basicas - tabela, anchor, keep state, block drop 4. roteamento - route-to e reply-to (provado com tcpdump nas 2 interfaces) 5. balanceamento - pool round-robin, pool source-hash, dup-to 6. QOS - filas hfsc, pfctl -s queue -v, transferencia de 2 MB pela fila Os videos ficam versionados em out/screencast/ (.gitignore ajustado para nao ignorar *.mp4) e o indice/texto de descricao do YouTube em docs/{en,pt-BR}/screencast.md. Correcoes na propria demo (encontradas gravando): a acao de uma regra no pf e pass OU block (nunca os dois); as regras de um anchor vivem em um ruleset proprio (pfctl -a <anchor> -f); o nc do QOS precisa rodar na VM do servidor, nao no firewall; o rotulo 'FASE x/6' vem do numero da fase, nao da posicao na lista de gravacao.	2026-11-12 08:41:41 -03:00
lgcosta	90c51f43fc	M5: queue gate 15 green (hfsc in the data path, pfctl -s queue works); vendor OpenBSD net/hfsc.h + net/fq_codel.h so kernel and pfctl share the ABI; pflog payload anchored; splassert no longer BUGs	2026-11-12 03:10:46 -03:00
lgcosta	4bade69cf9	docs: queue status honest - attach path reached, purge lock assert documented as the blocker (caveats #9 )	2026-11-12 01:42:51 -03:00
lgcosta	ccad35b247	hfsc: fix class-handle collision (root class used bit 0x1, colliding with odd pf qids -> pfq_addqueue EBUSY); guard against NULL discipline; drop debug prints	2026-11-12 01:40:49 -03:00
lgcosta	14ff7d1c39	ifq: real ifq_start (drain+transmit), dequeue cookie fix, pf_kifq_input hook in the data path; 14/14 suite unchanged	2026-11-12 01:15:26 -03:00
lgcosta	f34c4f92a9	M5 step 1: build OpenBSD hfsc/fq_codel back ends into pf.ko (ml_* API, ifq_q handshake, scheduler types); priq still attached, 14/14 suite unchanged	2026-11-12 00:48:56 -03:00
lgcosta	ca75fc49cc	docs: guide milestone tables synced with the verified state (EN+PT-BR)	2026-11-11 23:59:03 -03:00
lgcosta	12e9c1a2f3	reply-to: gate 13 green (reply forced onto the gateway link); docs/README/CHANGELOG for 14 gates	2026-11-11 23:56:01 -03:00
lgcosta	c2d1fc4c53	docs: fail-to is not an OpenBSD 8.0 keyword (removed upstream) - correct all references; reply-to gate added	2026-11-11 23:52:11 -03:00
lgcosta	3235af7f0b	pools: gate 10 green (round-robin vs source-hash); docs/README/CHANGELOG for 13 gates	2026-11-11 23:45:24 -03:00
lgcosta	422a325a56	docs: drop leftover line in pt-BR patches note	2026-11-11 23:37:38 -03:00
lgcosta	80396e0b36	docs: patches helpers are in tree (verified PATCHES_APPLIED=0 / UNPATCH_DONE); route pool gate 10 written	2026-11-11 23:37:02 -03:00
lgcosta	b3e7358868	scrub: gate 09 green (min-ttl/max-mss measured on egress); matrix + guides updated EN+PT-BR	2026-11-11 23:32:32 -03:00
lgcosta	251e5c09e0	demo+docs: 11-step recording (adds route-to), README status for 11/11 gates	2026-11-11 23:18:48 -03:00
lgcosta	e26c6d4a36	changelog: v0.5.0 (binat, route-to/dup-to, checksum correctness)	2026-11-11 23:13:07 -03:00
lgcosta	e7e941047f	docs: route-to/dup-to verified (matrix EN+PT-BR, guides)	2026-11-11 23:11:56 -03:00
lgcosta	1bda8b4fa2	route-to: forced nexthop via rt_gw4/rt_gw_family (Linux resolves neighbours from the gateway only when the route says so); cleanup of debug instrumentation	2026-11-11 23:08:11 -03:00
lgcosta	dc73274b19	route-to: fix skb reference imbalance in if_output_tso (stack output consumed the queue's ref -> double kfree_skb, wedging the box); look up the forced route by destination only	2026-11-11 22:35:05 -03:00
lgcosta	ecab31d704	docs: caveats EN+PT-BR updated to the verified state (hook order, soak, states, divert/pflog consumers)	2026-11-11 22:21:25 -03:00
lgcosta	2668d99d5a	binat: gate 07 green (pfctl's nat-to+rdr-to expansion verified both directions); docs updated	2026-11-11 22:14:44 -03:00