lgcosta
dff2185b20
- 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.
120 lines
4.9 KiB
Markdown
120 lines
4.9 KiB
Markdown
# Aplicando o conjunto de patches PF-on-Linux / guia de compilação
|
||
|
||
Este documento é a versão em português de `docs/en/install.md`.
|
||
|
||
Alvo: árvore de fontes do **Linux 7.3.4** + módulos out-of-tree `pf.ko`
|
||
(engine PF, família divert(4), filas ifq). O port é entregue como
|
||
**árvore de código-fonte + zero patches de core** (ver `patches/kernel/README.md`):
|
||
o módulo linka apenas símbolos que o kernel 7.3.4 puro já exporta.
|
||
|
||
## 1. Pré-requisitos
|
||
|
||
| Requisito | Por quê |
|
||
|---|---|
|
||
| gcc >= 15, GNU make, flex, bison, bc | build do kernel + pfctl |
|
||
| `glibc-static` (ou musl-static) | pfctl estático para as VMs guest |
|
||
| Fontes Linux 7.3.4 | alvo da compilação |
|
||
| `sys.tar.gz` + `src.tar.gz` do OpenBSD 8.0 | fontes portados (baixados e verificados por sha256; mirror primário openbsd.c3sl.ufpr.br, fallback cdn.openbsd.org) |
|
||
| root no host de build | `insmod` como root |
|
||
|
||
## 2. Passos
|
||
|
||
```sh
|
||
cd pf_port
|
||
|
||
# 2.1 busca e verifica as fontes OpenBSD 8.0 (sha256 fixados em VERSIONS)
|
||
./scripts/fetch-sources.sh
|
||
./scripts/vendorize.sh # staging em _vendor/upstream + IDS.txt
|
||
|
||
# 2.2 prepara o kernel (config + build + preparação p/ módulos externos)
|
||
KERNELDIR=/path/to/linux-7.3.4 ./scripts/build-kernel.sh
|
||
# - defconfig + virtio/EXT4 embutidos (boot direto do kernel na VM)
|
||
# - make bzImage modules_prepare
|
||
# - copia vmlinux.symvers -> Module.symvers (necessário para builds M=)
|
||
|
||
# 2.3 aplica os patches de core (atualmente NENHUM é necessário)
|
||
./scripts/apply-patches.sh /path/to/linux-7.3.4
|
||
# patches/kernel/series está vazio por projeto; se futuros milestones
|
||
# precisarem de exports, cada um entra como 000N-*.patch documentado em
|
||
# docs/pt-BR/patches.md.
|
||
|
||
# 2.4 compila módulo e userland
|
||
./scripts/build-module.sh # -> module/pf.ko
|
||
make -C tools # -> tools/out/pfctl (estático)
|
||
|
||
# 2.5 instala num sistema 7.3.4 rodando
|
||
sudo insmod module/pf.ko # cria /dev/pf (0600 root)
|
||
sudo cp tools/out/pfctl /usr/local/sbin/
|
||
sudo pfctl -e # habilita
|
||
sudo pfctl -f /etc/pf.conf # sintaxe real do OpenBSD 8.0
|
||
```
|
||
|
||
## 3. Verificação
|
||
|
||
```sh
|
||
pfctl -s info # "Status: Enabled", contadores ao vivo
|
||
pfctl -nf /etc/pf.conf # checagem de parse apenas
|
||
dmesg | grep pfk # hooks registrados (data path via workqueue netisr)
|
||
```
|
||
|
||
Bancada de VMs (Alpine em libvirt): `./scripts/vm-create.sh`,
|
||
`./scripts/vm-deploy.sh`, `./scripts/vm-run-tests.sh` — ver `docs/pt-BR/vm-lab.md`.
|
||
|
||
## 4. Remoção / reversão
|
||
|
||
```sh
|
||
sudo pfctl -d; sudo rmmod pf
|
||
./scripts/unpatch.sh /path/to/linux-7.3.4 # desfaz patches futuros, se houver
|
||
```
|
||
|
||
## 5. O que "aplicar o patch" significa aqui
|
||
|
||
Como a entrega é um módulo out-of-tree, "aplicar o conjunto" = passos
|
||
2.1–2.4; a árvore Linux intacta é apenas *configurada e compilada*
|
||
(virtio/EXT4 =y). Nenhum arquivo do kernel é modificado, salvo se um futuro
|
||
milestone acrescentar `patches/kernel/000N-*.patch` documentado (cada patch:
|
||
uma seção em docs/pt-BR/patches.md com o quê/por quê/impacto/reversão).
|
||
|
||
## 6. Notas sobre os passos acima (2026-11-12)
|
||
|
||
- O passo **2.3 é um no-op documentado hoje**: o conjunto de patches está
|
||
vazio e os scripts `scripts/apply-patches.sh` / `scripts/unpatch.sh` e o
|
||
arquivo `patches/kernel/series` ainda não existem na árvore (entram junto
|
||
com o primeiro patch real de core — ver [patches.md](patches.md)). Pode
|
||
pular 2.3 com segurança.
|
||
- O passo 2.4 compila todas as ferramentas de userland: os alvos de
|
||
`make -C tools` são `pfctl`, `pdivert`, `pflogd` e o verificador de ABI
|
||
(`abitest`, `abi`, `test`, `clean`).
|
||
- Depois do 2.5, todo o conjunto de features é usável e coberto pela suíte do
|
||
lab — filtragem com estado, tabelas e anchors, NAT (`nat-to`/`rdr-to`/
|
||
`binat-to` e pools), scrub, roteamento forçado (`route-to`/`dup-to`/
|
||
`reply-to`), `divert`, `pflog` e as filas do OpenBSD 8.0 (HFSC). A
|
||
[matriz de features](feature-matrix.md) diz qual gate prova o quê; leia
|
||
[pf-guide.md](pf-guide.md) para conhecer as divergências antes de habilitar
|
||
o PF num caminho que você precisa manter vivo.
|
||
|
||
## 6.1 Opcional: os screencasts narrados
|
||
|
||
```sh
|
||
export MINIMAX_API_KEY=... # TTS do MiniMax para a narração
|
||
./scripts/vm-create.sh # o lab precisa estar no ar
|
||
./scripts/screencast/build-all.sh # -> out/screencast/{en,pt}/*.mp4
|
||
```
|
||
|
||
O pipeline grava sessões shell reais contra o lab, gera a narração com uma
|
||
voz feminina do MiniMax (inglês e português) e renderiza MP4 1080p30 com
|
||
legendas queimadas e o diagrama de rede do lab. Detalhes:
|
||
[screencast.md](screencast.md).
|
||
|
||
## 7. Para onde ir agora
|
||
|
||
| | |
|
||
|---|---|
|
||
| Arquitetura em uma página | [guide.md](guide.md) |
|
||
| Etapas de build em detalhe | [build.md](build.md) |
|
||
| Bancada de VMs de validação | [vm-lab.md](vm-lab.md) |
|
||
| Regras do dia a dia e avisos | [pf-guide.md](pf-guide.md) |
|
||
| Divergências conhecidas | [caveats.md](caveats.md) |
|
||
| Mecanismo de patches de core | [patches.md](patches.md) |
|
||
| Índice da documentação | [README.md](README.md) |
|