pf-linux-port/tools/UPSTREAM.md

# PFLINUX — OpenBSD 8.0 pfctl on Linux: upstream provenance and edits

Sources: `_vendor/upstream/sbin/pfctl/` (OpenBSD 8.0-current, see
`_vendor/upstream/IDS.txt`), ABI header: `module/include/net/pfvar.h`
(v1.548), ioctl encoding: `module/include/pfk.h`.
This document lists every deviation from the pristine vendor sources, the
compat layer added under `tools/`, and the warnings emitted by the build.

## Build-time header copies (Makefile rules, never hand-edited)

| tools/include/…            | copied from                              |
|----------------------------|------------------------------------------|
| `net/pfvar.h`              | `module/include/net/pfvar.h` (contract)  |
| `sys/tree.h`, `sys/queue.h`| `_vendor/upstream/sys/sys/{tree,queue}.h`|
| `net/radix.h`              | `_vendor/upstream/sys/net/radix.h`       |
| `net/hfsc.h`, `net/fq_codel.h` | `_vendor/upstream/sys/net/{hfsc,fq_codel}.h` |

`make abi` compiles `abitest.c` once against each header set and diffs the
tables + MD5, proving the copy is in lockstep with `module/include`.

## Compat headers (hand-written, tools/include/)

| file | purpose |
|------|---------|
| `sys/ioctl.h` | glibc `<sys/ioctl.h>` via `#include_next`, then `_IO/_IOW/_IOR/_IOWR` redefined to the PFKXIOC (OpenBSD ioccom.h) encoding copied verbatim from `module/include/pfk.h` (NRBITS 8, TYPEBITS 8, SIZEBITS 13, DIRBITS 2, NRSHIFT 0, TYPESHIFT 8, SIZESHIFT 16, DIRSHIFT 30, NONE 0, WRITE 1, READ 2). This makes every `DIOC*` number in pfvar.h identical to what pf.ko decodes. |
| `pflinux_compat.h` | force-included (`-include`): `<sys/types.h>`, `<strings.h>` (bzero/bcopy), `offsetof`, OpenBSD cdefs fallbacks `__dead`/`__printflike`/`__packed`/`__unused`/`__inline`, `HTONL/NTOL/HTONS/NOSH` (assignment-style, `<sys/param.h>`), `AF_LINK` → `AF_PACKET` (parse.y uses it without `<net/if_dl.h>`), prototypes for `strtonum`, `fgetln`, `freezero`, `uid_from_user`, `gid_from_group`, `pledge`, `unveil`. |
| `sys/sysctl.h` | CTL_*/KERN_MAXCLUSTERS(67)/HW_PHYSMEM64(19) constants (OpenBSD values) + `sysctl()` prototype (glibc dropped `<sys/sysctl.h>`). |
| `sys/syslimits.h` | → `<limits.h>` (PATH_MAX etc. for pfvar.h). |
| `sys/_null.h` | OpenBSD NULL header needed by vendored queue.h/tree.h. |
| `sys/refcnt.h` | userland `struct refcnt { unsigned int rc; }` — same size as the module kernel compat (`refcount_t` = one int); referenced by struct pf_anchor only, never crosses ioctl. |
| `sys/timeout.h` | minimal `struct timeout` — pfvar.h embeds it in `struct pf_pktdelay`, which is kernel-internal (userland state payloads use `struct pfsync_state`). |
| `net/route.h` | userland subset pfvar.h/parse.y need: RTLABEL_LEN 32, RT_TABLEID_MAX 32 (**matches `module/include/pfk.h`**, not OpenBSD's 255), NET_RT_* numbers, `struct rt_tableinfo` (verbatim from obbsd route.h), forward `struct rtentry`. AF_ROUTE/PF_ROUTE come from glibc `<sys/socket.h>` (both are 17 there, same as OpenBSD). |
| `net/if.h` | glibc header via `#include_next` + OpenBSD interface-group ABI (`struct ifg_req`, `struct ifgroupreq`, `SIOCGIFGMEMB` with the OpenBSD number, IFQ_NQUEUES/IFQ_MAXPRIO). Linux has no interface groups: the ioctl fails ENOTTY and group names degrade to "no such group", like an OpenBSD box missing the group. |
| `net/if_dl.h` | `AF_LINK` ≡ `AF_PACKET`; `struct sockaddr_dl` laid out to mirror Linux `sockaddr_ll` so pfctl_parser.c's `sdl_index` cast reads `sll_ifindex` (offset 4). AF_LINK is userland-internal (iftab bookkeeping); it never enters ioctl payloads. |
| `netinet/tcp_fsm.h` | TCPS_* states + TCP_NSTATES 11 (obbsd values); `tcpstates[]` extern (defined in compat). |
| `netinet/ip_icmp.h`, `netinet/icmp6.h`, `netinet/ip.h` | `#include_next` + the ICMP*/ICMP6_*/MLD_*/ND_*/IPTOS_DSCP_CS* constants glibc lacks (verbatim obbsd values). |
| `md5.h` | copy of `_vendor/upstream/sys/crypto/md5.h` minus the kernel-only `__bounded__` annotations. |

## Compat sources (tools/compat-user/)

| file | purpose |
|------|---------|
| `sysctl.c` | `sysctl(3)` emulation for exactly the three MIBs pfctl uses: HW_PHYSMEM64 (sysconf), KERN_MAXCLUSTERS (physmem/2048, the OpenBSD RAM-based sizing), NET_RT_TABLE (`struct rt_tableinfo`, always "exists" for ids ≤ RT_TABLEID_MAX — mirrors module `compat/pfk_rtable.c`: Linux has no per-rtableid FIBs, `rtable_exists()` accepts every id). |
| `strtonum.c` | BSD `strtonum(3)` (glibc has none). |
| `md5.c` | vendor `_vendor/upstream/sys/crypto/md5.c`, **only** the three include lines replaced (`sys/param.h`,`sys/systm.h`,`crypto/md5.h` → `sys/types.h`,`endian.h`,`string.h`,`md5.h`); algorithm byte-identical. |
| `rbtree.c` | OpenBSD's out-of-line generic RB tree (`_rb_insert/_rb_find/_rb_remove/_rb_min/_rb_next/...`) that `sys/tree.h`'s RBT_* macros call; OpenBSD ships it in libc, glibc has none. CLRS-based, verified by a 30k-op/12-seed fuzz harness (order, parent-links, bidirectional walks, find identity). |
| `bsd.c` | `tcpstates[]` (obbsd text), `pledge`/`unveil` no-op stubs (unused by 8.0 sources, kept for future syncs), `fgetln()` over `getline()` with OpenBSD `*len` semantics, `freezero()`, `uid_from_user()`, `gid_from_group()`. |
| `inet_net_pton.c` | BSD `inet_net_pton()` for AF_INET abbreviated CIDR ("10/8", classful defaults) + AF_INET6; glibc 2.43 declares it but exports no symbol. |

`pfctl/pf_ruleset.c`: not copied — the Makefile compiles
`_vendor/upstream/sys/net/pf_ruleset.c` **unmodified** into pfctl (its
`!_KERNEL` branch exists precisely "so we can lend code to pfctl", providing
`pf_anchor_setup`, `pf_find_or_create_ruleset`, `pf_main_anchor`, …).
Verified with `cmp` against vendor on every build (file read-only here).

## Grammar toolchain

Only bison is needed: OpenBSD `parse.y` carries a hand-written `yylex()`
(`flex` unused). bison 3.8 accepts the OpenBSD yacc idioms used here —
prologue `typedef struct {union{...} v; int lineno;} YYSTYPE` plus
`%type <v.member>` dotted tags — with zero pre-processing. Duplicate
`%token RTABLE/RDOMAIN` lines produce warnings (upstream text).

## Edits to the copied pfctl sources (all marked in-file with `/* PFLINUX */`)

1. **parse.y** (declarations section): `expand_label_addr`/`expand_label`
   prototypes: address-family parameter `u_int8_t` → `sa_family_t`.
   Linux `sa_family_t` is `unsigned short` (OpenBSD: `unsigned char`); the
   matching definitions in the same file already use `sa_family_t`.
2. **pfctl_parser.c** (`ifa_load`): dropped two
   `ifa_broadaddr->sa_len != 0` / `ifa_dstaddr->sa_len != 0` guards —
   glibc `struct sockaddr` has no `sa_len`; `getifaddrs(3)` only fills those
   members when a broadcast/destination address actually exists.
3. **pfctl_parser.h**: `geticmptypebynumber`, `geticmptypebyname`,
   `geticmpcodebynumber`, `geticmpcodebyname` prototype af parameters
   `u_int8_t` → `sa_family_t` (same reason as #1).
4. **pfctl_parser.c**: `print_fromto` forward prototype, af parameter
   `u_int8_t` → `sa_family_t`.
5. **pf_print_state.c** (`print_name`): removed `sin_len`/`sin6_len`
   assignments; added local `socklen_t slen` set to `sizeof(*sin|*sin6)` and
   passed to `getnameinfo(3)` (no `ss_len` on Linux).
6. **pfctl_table.c** (`print_ad` reverse-DNS): identical `sa_len` removal
   pattern as #5.
7. **pfctl_osfp.c** (`pfctl_file_fingerprints`): a missing `/etc/pf.os`
   (ENOENT) returns success instead of warn+fail — OpenBSD ships the file in
   base; this port has no fingerprint packaging yet. Other open errors still
   fatal. (Without this, every `-f` load exits 1 on stock Linux.)

No other lines differ from vendor; `cmp` each file against
`_vendor/upstream/sbin/pfctl/` to audit (`diff -u` shows only the sites above).

## ABI table notes (tools/abitest/abitest.c)

* The contract's `pf_state_key` is kernel-only in 8.0 (moved to
  `<net/pfvar_priv.h>`, which userland MUST NOT include). The table
  therefore probes its userland mirror `struct pf_state_key_cmp`
  ("keep synced with struct pf_state_key, used in RB_FIND") plus the
  wire-format `struct pfsync_state_key` / `struct pfsync_state` used by
  `DIOCGETSTATE` payloads. The kernel-side comparison of the real
  `struct pf_state_key` is the integrator's job, same as for all
  `-D_KERNEL` layout checks.

## Known warnings (intentional, benign)

* `-Wformat=` (×51): `%lld`/`%llu` vs `long` printf conversions. OpenBSD
  prints 64-bit values with `%ll*`; LP64 glibc types differ in spelling only.
  Output text is identical.
* `-Waddress-of-packed-member` (×6): `struct pfsync_state` is `__packed`
  (wire format shared with pf.ko); pf_print_state.c takes addresses of its
  members. Access is alignment-safe on x86-64 (no AVX requirement).
* `-Wother` (×6): bison "symbol RTABLE/RDOMAIN redeclared" — upstream
  parse.y declares these tokens twice.
* `-Wpointer-sign` (×15) / `-Wformat-truncation` (×10) / `-Wdiscarded-qualifiers`
  (×2): snprintf/`char*` signedness and const-preserving idioms from OpenBSD
  sources (e.g. `strrchr` result into non-const, GCC's path-insensitive
  truncation heuristics). Non-fatal, semantics unchanged.

## Out of scope / pending

* `pdivert` and `pflogd` — intentionally NOT ported here; owned by the
  integrator. (No skeleton stubs are shipped.)
* Kernel-side ABI confirmation (same table compiled under `-D_KERNEL` with
  the module compat headers) — integrator step; `out/abi-tools.tbl` /
  `out/abi-module.tbl` + `out/abitest` md5 line are the reference inputs.
* Runtime paths (`-s`, `-F`, live `-f` load) require `/dev/pf` from pf.ko and
  were exercised only through the `-n` (offline) code path here.