0 Fork 0

Files

T

lgcosta dff2185b20 Docs: bring the documentation in line with the code

- 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.

2026-11-12 11:51:25 -03:00

4.9 KiB

Raw Blame History

Aplicando o conjunto de patches PF-on-Linux / guia de compilação

Este documento é a versão em português de docs/en/install.md.

Alvo: árvore de fontes do Linux 7.3.4 + módulos out-of-tree pf.ko (engine PF, família divert(4), filas ifq). O port é entregue como árvore de código-fonte + zero patches de core (ver patches/kernel/README.md): o módulo linka apenas símbolos que o kernel 7.3.4 puro já exporta.

1. Pré-requisitos

Requisito	Por quê
gcc >= 15, GNU make, flex, bison, bc	build do kernel + pfctl
`glibc-static` (ou musl-static)	pfctl estático para as VMs guest
Fontes Linux 7.3.4	alvo da compilação
`sys.tar.gz` + `src.tar.gz` do OpenBSD 8.0	fontes portados (baixados e verificados por sha256; mirror primário openbsd.c3sl.ufpr.br, fallback cdn.openbsd.org)
root no host de build	`insmod` como root

2. Passos

cd pf_port

# 2.1 busca e verifica as fontes OpenBSD 8.0 (sha256 fixados em VERSIONS)
./scripts/fetch-sources.sh
./scripts/vendorize.sh          # staging em _vendor/upstream + IDS.txt

# 2.2 prepara o kernel (config + build + preparação p/ módulos externos)
KERNELDIR=/path/to/linux-7.3.4 ./scripts/build-kernel.sh
#   - defconfig + virtio/EXT4 embutidos (boot direto do kernel na VM)
#   - make bzImage modules_prepare
#   - copia vmlinux.symvers -> Module.symvers (necessário para builds M=)

# 2.3 aplica os patches de core (atualmente NENHUM é necessário)
./scripts/apply-patches.sh /path/to/linux-7.3.4
#   patches/kernel/series está vazio por projeto; se futuros milestones
#   precisarem de exports, cada um entra como 000N-*.patch documentado em
#   docs/pt-BR/patches.md.

# 2.4 compila módulo e userland
./scripts/build-module.sh        # -> module/pf.ko
make -C tools                    # -> tools/out/pfctl (estático)

# 2.5 instala num sistema 7.3.4 rodando
sudo insmod module/pf.ko         # cria /dev/pf (0600 root)
sudo cp tools/out/pfctl /usr/local/sbin/
sudo pfctl -e                    # habilita
sudo pfctl -f /etc/pf.conf       # sintaxe real do OpenBSD 8.0

3. Verificação

pfctl -s info            # "Status: Enabled", contadores ao vivo
pfctl -nf /etc/pf.conf   # checagem de parse apenas
dmesg | grep pfk         # hooks registrados (data path via workqueue netisr)

Bancada de VMs (Alpine em libvirt): ./scripts/vm-create.sh, ./scripts/vm-deploy.sh, ./scripts/vm-run-tests.sh — ver docs/pt-BR/vm-lab.md.

4. Remoção / reversão

sudo pfctl -d; sudo rmmod pf
./scripts/unpatch.sh /path/to/linux-7.3.4   # desfaz patches futuros, se houver

5. O que "aplicar o patch" significa aqui

Como a entrega é um módulo out-of-tree, "aplicar o conjunto" = passos 2.1–2.4; a árvore Linux intacta é apenas configurada e compilada (virtio/EXT4 =y). Nenhum arquivo do kernel é modificado, salvo se um futuro milestone acrescentar patches/kernel/000N-*.patch documentado (cada patch: uma seção em docs/pt-BR/patches.md com o quê/por quê/impacto/reversão).

6. Notas sobre os passos acima (2026-11-12)

O passo 2.3 é um no-op documentado hoje: o conjunto de patches está vazio e os scripts scripts/apply-patches.sh / scripts/unpatch.sh e o arquivo patches/kernel/series ainda não existem na árvore (entram junto com o primeiro patch real de core — ver patches.md). Pode pular 2.3 com segurança.
O passo 2.4 compila todas as ferramentas de userland: os alvos de make -C tools são pfctl, pdivert, pflogd e o verificador de ABI (abitest, abi, test, clean).
Depois do 2.5, todo o conjunto de features é usável e coberto pela suíte do lab — filtragem com estado, tabelas e anchors, NAT (nat-to/rdr-to/ binat-to e pools), scrub, roteamento forçado (route-to/dup-to/ reply-to), divert, pflog e as filas do OpenBSD 8.0 (HFSC). A matriz de features diz qual gate prova o quê; leia pf-guide.md para conhecer as divergências antes de habilitar o PF num caminho que você precisa manter vivo.

6.1 Opcional: os screencasts narrados

export MINIMAX_API_KEY=...          # TTS do MiniMax para a narração
./scripts/vm-create.sh               # o lab precisa estar no ar
./scripts/screencast/build-all.sh    # -> out/screencast/{en,pt}/*.mp4

O pipeline grava sessões shell reais contra o lab, gera a narração com uma voz feminina do MiniMax (inglês e português) e renderiza MP4 1080p30 com legendas queimadas e o diagrama de rede do lab. Detalhes: screencast.md.

7. Para onde ir agora


Arquitetura em uma página	guide.md
Etapas de build em detalhe	build.md
Bancada de VMs de validação	vm-lab.md
Regras do dia a dia e avisos	pf-guide.md
Divergências conhecidas	caveats.md
Mecanismo de patches de core	patches.md
Índice da documentação	README.md

4.9 KiB Raw Blame History Unescape Escape