caveats §13 documents the capacity ceiling the stress test found: the
workqueue backlog grows with the offered rate and OOM-panics a 1 GB guest
above ~1 Gbit/s. Gate count, suite status and the doc indexes move to
16/16 green.
The manual is the from-zero path on Debian 13 (trixie): packages, the
7.3.4 kernel tree, pf.ko, the userland, the libvirt lab, the gate suite,
the stress test and running PF on the host itself. Every command in it was
executed on the lab's Debian 13.7 host, including the toolchain report
and the kernel.org checksum.
Trixie ships gcc 14 and no gcc-15; the kernel and pf.ko build with gcc
14 unpatched, so the manual documents that instead of the gcc >= 15 the
generic install guide asks for.
Gate 16 asserts invariants under load: states tracked under concurrent
connections and drained again, 200 ruleset reloads without failure, 2000
table entries flushed back to zero, 2 MB intact through NAT under a
concurrent stream, no kernel faults. Throughput is measured and reported
rather than gated, and the traffic phases run at a bounded rate because
the PF workqueue backlog exhausts a 1 GB guest above ~1 Gbit/s.
The runner writes out/stress/<timestamp>/report.md and captures the guest
serial console so a panic stays diagnosable.
kernel-config.sh looked for the tree two levels up and build-kernel.sh
did not pass on the tree it had resolved, so a plain
./scripts/build-kernel.sh could configure one tree and build another.
Both resolve <repo>/../linux-7.3.4.
- Demo docs replaced by the screencast docs (single source of truth): the
legacy demo-session.sh/demo-record.py and the v0.9 renderer were removed
instead of being kept as a second convention.
- feature-matrix: stale 'M2-in-progress' vocabulary gone; the rows the 15
gates prove now say VERIFIED-in-VM and name the gate; af-to is now an
explicit non-goal row (INET6 0 in this build).
- guide: the queues/divert/pflog sections described a state that no longer
exists (priq-only, divert dropping packets, pflog logging nothing); they
now describe the shipped behaviour.
- vm-lab: the 15 real gates with what each proves, 15/15 green, and the
pf0 -> cli/srv/gw2 ssh setup the screencasts rely on.
- install/build: pdivert and pflogd are built and ported (docs said
otherwise); module object list now includes hfsc.c, fq_codel.c, pfk_pflog.c;
the screencast pipeline is an optional build stage.
- pf-guide: the 'M2 scope only' framing is gone; honest gaps listed.
- caveats: three new sections about the screencast pipeline (MiniMax video
generation blocked by the account tier, narration as a separate track, a
video frame is not a verdict).
- porting-notes: what the recording taught us.
- README/README.pt-BR: status, milestones, layout and video section updated.
All internal doc links verified.
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.
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.
lgcosta