AF_DIVERT family restored & compiling: full socket family (PF_DIVERT=32, sock_register), blocking recv/poll, divert_output-compatible sendmsg reinject, mtag type passthrough; pfk_api decls

2026-11-11 18:47:04 -03:00
1 parent fe6f767561
commit ac56534c3b
@@ -0,0 +1,105 @@
+# 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-11)
+
+- 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 apenas o `pfctl` e o verificador de ABI (alvos de
+  `make -C tools`: `pfctl abitest abi test clean`). `pdivert` existe como
+  arquivo-fonte sem alvo no Makefile por enquanto; `pflogd` ainda não foi
+  portado.
+- Depois do 2.5, o que dá para usar de verdade é o núcleo de filtragem M2
+  (pass/block/quick/keep state/tabelas/anchors); NAT/scrub/queues/divert/
+  pflog dependem dos próximos milestones — consulte a
+  [matriz de features](feature-matrix.md) e leia [pf-guide.md](pf-guide.md)
+  antes de habilitar PF num caminho que você precisa manter vivo.
+
+## 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) |