1.\" Copyright (c) 1999 Whistle Communications, Inc. 2.\" All rights reserved. 3.\" 4.\" Subject to the following obligations and disclaimer of warranty, use and 5.\" redistribution of this software, in source or object code forms, with or 6.\" without modifications are expressly permitted by Whistle Communications; 7.\" provided, however, that: 8.\" 1. Any and all reproductions of the source or object code must include the 9.\" copyright notice above and the following disclaimer of warranties; and 10.\" 2. No rights are granted, in any manner or form, to use Whistle 11.\" Communications, Inc. trademarks, including the mark "WHISTLE 12.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as 13.\" such appears in the above copyright notice or in the software. 14.\" 15.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND 16.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO 17.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, 18.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF 19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. 20.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY 21.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS 22.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. 23.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES 24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING 25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR 27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY 31.\" OF SUCH DAMAGE. 32.\" 33.\" Author: Archie Cobbs <archie@FreeBSD.org> 34.\" $Whistle: ng_bpf.8,v 1.2 1999/12/03 01:57:12 archie Exp $ 35.\" 36.Dd September 20, 2020 37.Dt NG_BPF 4 38.Os 39.Sh NAME 40.Nm ng_bpf 41.Nd Berkeley packet filter netgraph node type 42.Sh SYNOPSIS 43.In sys/types.h 44.In net/bpf.h 45.In netgraph.h 46.In netgraph/ng_bpf.h 47.Sh DESCRIPTION 48The 49.Nm bpf 50node type allows Berkeley Packet Filter (see 51.Xr bpf 4 ) 52filters to be applied to data travelling through a Netgraph network. 53Each node allows an arbitrary number of connections to arbitrarily 54named hooks. 55With each hook is associated a 56.Xr bpf 4 57filter program which is applied to incoming data only, a destination hook 58for matching packets, a destination hook for non-matching packets, 59and various statistics counters. 60.Pp 61A 62.Xr bpf 4 63program returns an unsigned integer, which is normally interpreted as 64the length of the prefix of the packet to return. 65In the context of this 66node type, returning zero is considered a non-match, in which case the 67entire packet is delivered out the non-match destination hook. 68Returning a value greater than zero causes the packet to be truncated 69to that length and delivered out the match destination hook. 70Either or both destination hooks may be the empty string, or may 71not exist, in which case the packet is dropped. 72.Pp 73New hooks are initially configured to drop all packets. 74A new filter program may be installed using the 75.Dv NGM_BPF_SET_PROGRAM 76control message. 77.Sh HOOKS 78This node type supports any number of hooks having arbitrary names. 79.Sh CONTROL MESSAGES 80This node type supports the generic control messages, plus the following: 81.Bl -tag -width foo 82.It Dv NGM_BPF_SET_PROGRAM Pq Ic setprogram 83This command sets the filter program that will be applied to incoming 84data on a hook. 85The following structure must be supplied as an argument: 86.Bd -literal -offset 4n 87struct ng_bpf_hookprog { 88 char thisHook[NG_HOOKSIZ]; /* name of hook */ 89 char ifMatch[NG_HOOKSIZ]; /* match dest hook */ 90 char ifNotMatch[NG_HOOKSIZ]; /* !match dest hook */ 91 int32_t bpf_prog_len; /* #insns in program */ 92 struct bpf_insn bpf_prog[]; /* bpf program */ 93}; 94.Ed 95.Pp 96The hook to be updated is specified in 97.Dv thisHook . 98The BPF program is the sequence of instructions in the 99.Dv bpf_prog 100array; there must be 101.Dv bpf_prog_len 102of them. 103Matching and non-matching incoming packets are delivered out the hooks named 104.Dv ifMatch 105and 106.Dv ifNotMatch , 107respectively. 108The program must be a valid 109.Xr bpf 4 110program or else 111.Er EINVAL 112is returned. 113.It Dv NGM_BPF_GET_PROGRAM Pq Ic getprogram 114This command takes an ASCII 115string argument, the hook name, and returns the 116corresponding 117.Dv "struct ng_bpf_hookprog" 118as shown above. 119.It Dv NGM_BPF_GET_STATS Pq Ic getstats 120This command takes an ASCII 121string argument, the hook name, and returns the 122statistics associated with the hook as a 123.Dv "struct ng_bpf_hookstat" . 124.It Dv NGM_BPF_CLR_STATS Pq Ic clrstats 125This command takes an ASCII 126string argument, the hook name, and clears the 127statistics associated with the hook. 128.It Dv NGM_BPF_GETCLR_STATS Pq Ic getclrstats 129This command is identical to 130.Dv NGM_BPF_GET_STATS , 131except that the statistics are also atomically cleared. 132.El 133.Sh SHUTDOWN 134This node shuts down upon receipt of a 135.Dv NGM_SHUTDOWN 136control message, or when all hooks have been disconnected. 137.Sh EXAMPLES 138It is possible to configure a node from the command line, using 139.Xr tcpdump 1 140to generate raw BPF instructions which are then transformed 141into the ASCII form of a 142.Dv NGM_BPF_SET_PROGRAM 143control message, as demonstrated here: 144.Bd -literal -offset 4n 145#!/bin/sh 146 147PATTERN="tcp dst port 80" 148NODEPATH="my_node:" 149INHOOK="hook1" 150MATCHHOOK="hook2" 151NOTMATCHHOOK="hook3" 152 153BPFPROG=$( tcpdump -s 8192 -p -ddd ${PATTERN} | \\ 154 ( read len ; \\ 155 echo -n "bpf_prog_len=$len " ; \\ 156 echo -n "bpf_prog=[" ; \\ 157 while read code jt jf k ; do \\ 158 echo -n " { code=$code jt=$jt jf=$jf k=$k }" ; \\ 159 done ; \\ 160 echo " ]" ) ) 161 162ngctl msg ${NODEPATH} setprogram { thisHook=\\"${INHOOK}\\" \\ 163 ifMatch=\\"${MATCHHOOK}\\" \\ 164 ifNotMatch=\\"${NOTMATCHHOOK}\\" \\ 165 ${BPFPROG} } 166.Ed 167.Pp 168Based on the previous example, it is possible to prevent a jail (or a VM) 169from spoofing by allowing only traffic that has the expected ethernet and 170IP addresses: 171.Bd -literal -offset 4n 172#!/bin/sh 173 174NODEPATH="my_node:" 175JAIL_MAC="0a:00:de:ad:be:ef" 176JAIL_IP="128.66.1.42" 177JAIL_HOOK="jail" 178HOST_HOOK="host" 179DEBUG_HOOK="nomatch" 180 181bpf_prog() { 182 local PATTERN=$1 183 184 tcpdump -s 8192 -p -ddd ${PATTERN} | ( 185 read len 186 echo -n "bpf_prog_len=$len " 187 echo -n "bpf_prog=[" 188 while read code jt jf k ; do 189 echo -n " { code=$code jt=$jt jf=$jf k=$k }" 190 done 191 echo " ]" 192 ) 193} 194 195# Prevent jail from spoofing (filter packets coming from jail) 196ngctl msg ${NODEPATH} setprogram { \\ 197 thisHook=\\"${JAIL_HOOK}\\" \\ 198 ifMatch=\\"${HOST_HOOK}\\" \\ 199 ifNotMatch=\\"${DEBUG_HOOK}\\" \\ 200 $(bpf_prog "ether src ${JAIL_MAC} && src ${JAIL_IP}") \\ 201} 202 203# Prevent jail from receiving spoofed packets (filter packets 204# coming from host) 205ngctl msg ${NODEPATH} setprogram { \\ 206 thisHook=\\"${HOST_HOOK}\\" \\ 207 ifMatch=\\"${JAIL_HOOK}\\" \\ 208 ifNotMatch=\\"${DEBUG_HOOK}\\" \\ 209 $(bpf_prog "ether dst ${JAIL_MAC} && dst ${JAIL_IP}") \\ 210} 211.Ed 212.Sh SEE ALSO 213.Xr bpf 4 , 214.Xr netgraph 4 , 215.Xr ngctl 8 216.Sh HISTORY 217The 218.Nm 219node type was implemented in 220.Fx 4.0 . 221.Sh AUTHORS 222.An Archie Cobbs Aq Mt archie@FreeBSD.org 223.Sh BUGS 224When built as a loadable kernel module, this module includes the file 225.Pa net/bpf_filter.c . 226Although loading the module should fail if 227.Pa net/bpf_filter.c 228already exists in the kernel, currently it does not, and the duplicate 229copies of the file do not interfere. 230However, this may change in the future. 231