NG_BPF(4)

💖 NG_BPF — Berkeley packet filter netgraph node type 💖

okay bestie, gather round, because today we're talking about ng_bpf — the Kernel Interfaces Manual girlie who lets you run Berkeley Packet Filter magic on data zooming through a Netgraph network. she's giving filter vibes and she's so good at her job. no cap. 🦋

---

✨ SYNOPSIS ✨

#include <sys/types.h>
#include <net/bpf.h>
#include <netgraph.h>
#include <netgraph/ng_bpf.h>

---

🌸 DESCRIPTION 🌸

so the bpf node type lets you apply Berkeley Packet Filter filters (that's bpf(4), iykyk) to data travelling through a Netgraph network. each node can have an arbitrary number of connections to arbitrarily named hooks — yes, you read that right, go wild with the names. 🎀

with each hook you get:

• a bpf(4) filter program, applied to incoming data only (not outgoing, she's got boundaries)
• a destination hook for matching packets
• a destination hook for non-matching packets
• and a whole lil collection of statistics counters ✨

a bpf(4) program returns an unsigned integer, which normally gets interpreted as the length of the prefix of the packet to return. in this node type's context tho:

• returning zero = a non-match, and the entire packet gets delivered out the non-match destination hook
• returning anything greater than zero = the packet gets truncated to that length and delivered out the match destination hook

either or both destination hooks may be the empty string, or may just not exist at all — in which case, bestie, the packet is dropped. 💀

new hooks start out configured to drop all packets. a new filter program can be installed using the NGM_BPF_SET_PROGRAM control message. slay. 💅

---

🪝 HOOKS 🪝

this node type supports any number of hooks having arbitrary names. periodt.

---

👑 CONTROL MESSAGES 👑

this node type supports the generic control messages, plus these icons:

• NGM_BPF_SET_PROGRAM (setprogram) — sets the filter program that will be applied to incoming data on a hook. you gotta supply the following structure as an argument:

struct ng_bpf_hookprog {
  char            thisHook[NG_HOOKSIZ];     /* name of hook */
  char            ifMatch[NG_HOOKSIZ];      /* match dest hook */
  char            ifNotMatch[NG_HOOKSIZ];   /* !match dest hook */
  int32_t         bpf_prog_len;             /* #insns in program */
  struct bpf_insn bpf_prog[];               /* bpf program */
};

the hook to be updated is specified in thisHook. the BPF program is the sequence of instructions in the bpf_prog array, and there must be bpf_prog_len of them — count them, bestie, don't be sloppy. matching incoming packets get delivered out the hook named ifMatch, and non-matching ones go out ifNotMatch. the program must be a valid bpf(4) program, or else EINVAL gets returned. 🚨

• NGM_BPF_GET_PROGRAM (getprogram) — this command takes an ASCII string argument (the hook name) and returns the corresponding struct ng_bpf_hookprog as shown above.
• NGM_BPF_GET_STATS (getstats) — takes an ASCII string argument, the hook name, and returns the statistics associated with the hook as a struct ng_bpf_hookstat.
• NGM_BPF_CLR_STATS (clrstats) — takes an ASCII string argument, the hook name, and clears the statistics associated with the hook. clean slate energy. ✨
• NGM_BPF_GETCLR_STATS (getclrstats) — identical to NGM_BPF_GET_STATS, except the statistics are also atomically cleared. two things at once? she's multitasking, she's iconic. 💅

---

🦋 SHUTDOWN 🦋

this node shuts down when it receives a NGM_SHUTDOWN control message, or when all hooks have been disconnected. bye bestie 👋

---

🌈 EXAMPLES 🌈

you can totally configure a node straight from the command line — use tcpdump(1) to generate raw BPF instructions, then feed those into an awk(1) script to create the ASCII form of a NGM_BPF_SET_PROGRAM control message. like this, watch:

#!/bin/sh

PATTERN="tcp dst port 80"
NODEPATH="my_node:"
INHOOK="hook1"
MATCHHOOK="hook2"
NOTMATCHHOOK="hook3"

BPFPROG=$( tcpdump -s 8192 -p -ddd ${PATTERN} | \
           ( read len ; \
             echo -n "bpf_prog_len=$len" ; \
             echo -n "bpf_prog=[" ; \
             while read code jt jf k ; do \
                 echo -n " { code=$code jt=$jt jf=$jf k=$k }" ; \
             done ; \
             echo " ]" ) )

ngctl msg ${NODEPATH} setprogram { thisHook=\"${INHOOK}\" \
  ifMatch=\"${MATCHHOOK}\" \
  ifNotMatch=\"${NOTMATCHHOOK}\" \
  ${BPFPROG} }

ate that fr fr. 🔥

---

👀 SEE ALSO 👀

bpf(4), netgraph(4), ngctl(8)

---

⭐ HISTORY ⭐

the ng_bpf node type was implemented in FreeBSD 4.0. she's been thriving for a minute. 👑

---

🎀 AUTHORS 🎀

Archie Cobbs <archie@FreeBSD.org> — thank you for your service, king 🫶

---

💀 BUGS 💀

okay so here's the tea. when built as a loadable kernel module, this module includes the file net/bpf_filter.c. loading the module should fail if net/bpf_filter.c already exists in the kernel, but currently it does not, and the duplicate copies of the file do not interfere. however, this may change in the future. so like… noted. 🙈

---

cute lil sign-off: this page came to you from Debian, dated November 13, 2012. mwah 💖