PFIL(9)

💖 PFIL(9) — Kernel Developer's Manual: packet filter interface 💖

✨ NAME ✨

pfil, pfil_head_register, pfil_head_unregister, pfil_link, pfil_run_hooks — packet filter interface

---

🌸 SYNOPSIS 🌸

#include <sys/param.h>
#include <sys/mbuf.h>
#include <net/pfil.h>

pfil_head_t
pfil_head_register(struct pfil_head_args *args);

void
pfil_head_unregister(struct pfil_head_t *head);

pfil_hook_t
pfil_add_hook(struct pfil_hook_args *);

void
pfil_remove_hook(pfil_hook_t);

int
pfil_link(struct pfil_link_args *args);

int
pfil_run_hooks(phil_head_t *, pfil_packet_t, struct ifnet *, int,
    struct inpcb *);

---

🦋 DESCRIPTION 🦋

okay so the pfil framework lets a specified function or a list of functions get invoked for every incoming or outgoing packet on a particular network I/O stream. These hooks may be used to implement a firewall or perform packet transformations. 🔥

Packet filtering points — for historical reasons named heads — are registered with pfil_head_register(). That function gets a special versioned struct pfil_head_args structure, which specifies the type and features of the head plus a human-readable name. If the filtering point is ever going to be destroyed, the subsystem that created it must unregister it by calling pfil_head_unregister(). 🫶

Packet filtering systems may register an arbitrary number of filters — for historical reasons named hooks. To register a new hook, you call pfil_add_hook() with a special versioned struct pfil_hook_args structure. That structure specifies the type and features of the hook, a pointer to the actual filtering function, and the user-readable name of the filtering module and the ruleset name. Later, hooks can be removed with the pfil_remove_hook() function. ✨

To connect an existing hook to an existing head, pfil_link() shall be used. It takes a versioned struct pfil_link_args structure that specifies either the literal names of the hook and head or pointers to them. Typically, filtering modules call pfil_link() to autoregister their default ruleset and default filtering points. It also serves on the kernel side of ioctl(2) when a user changes pfil configuration with help from the pfilctl(8) utility. 👑

For every packet traveling through a head, that head shall invoke pfil_run_hooks(). The function can accept either a struct mbuf * pointer or a void * pointer and a length. If a hooked filtering module cannot understand a void * pointer, pfil will provide it with a fake one. All calls to pfil_run_hooks() are performed in network epoch(9). 💅

---

👑 HEADS (filtering points) 👑

By default, the kernel creates these heads:

• inet — IPv4 packets. 🌈
• inet6 — IPv6 packets. 💜
• ethernet — Link-layer packets. 🦋

Default rulesets are automatically linked to these heads to preserve historical behaviour. periodt. 💖

---

🔍 SEE ALSO 🔍

ipfilter(4), ipfw(4), pf(4), pfilctl(8)

---

📜 HISTORY 📜

The pfil interface first appeared in NetBSD 1.3. The pfil interface was imported into FreeBSD 5.2. In FreeBSD 13.0 the interface was significantly rewritten. 😭✨

---

okay bestie, that's the whole page — this one comes from Debian, dated January 28, 2019, and it's the PFIL(9) manual page. mwah! 💋🎀