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.\" 35.\" $FreeBSD$ 36.\" $Whistle: ng_bpf.8,v 1.2 1999/12/03 01:57:12 archie Exp $ 37.\" 38.Dd September 20, 2020 39.Dt NG_BPF 4 40.Os 41.Sh NAME 42.Nm ng_bpf 43.Nd Berkeley packet filter netgraph node type 44.Sh SYNOPSIS 45.In sys/types.h 46.In net/bpf.h 47.In netgraph.h 48.In netgraph/ng_bpf.h 49.Sh DESCRIPTION 50The 51.Nm bpf 52node type allows Berkeley Packet Filter (see 53.Xr bpf 4 ) 54filters to be applied to data travelling through a Netgraph network. 55Each node allows an arbitrary number of connections to arbitrarily 56named hooks. 57With each hook is associated a 58.Xr bpf 4 59filter program which is applied to incoming data only, a destination hook 60for matching packets, a destination hook for non-matching packets, 61and various statistics counters. 62.Pp 63A 64.Xr bpf 4 65program returns an unsigned integer, which is normally interpreted as 66the length of the prefix of the packet to return. 67In the context of this 68node type, returning zero is considered a non-match, in which case the 69entire packet is delivered out the non-match destination hook. 70Returning a value greater than zero causes the packet to be truncated 71to that length and delivered out the match destination hook. 72Either or both destination hooks may be the empty string, or may 73not exist, in which case the packet is dropped. 74.Pp 75New hooks are initially configured to drop all packets. 76A new filter program may be installed using the 77.Dv NGM_BPF_SET_PROGRAM 78control message. 79.Sh HOOKS 80This node type supports any number of hooks having arbitrary names. 81.Sh CONTROL MESSAGES 82This node type supports the generic control messages, plus the following: 83.Bl -tag -width foo 84.It Dv NGM_BPF_SET_PROGRAM Pq Ic setprogram 85This command sets the filter program that will be applied to incoming 86data on a hook. 87The following structure must be supplied as an argument: 88.Bd -literal -offset 4n 89struct ng_bpf_hookprog { 90 char thisHook[NG_HOOKSIZ]; /* name of hook */ 91 char ifMatch[NG_HOOKSIZ]; /* match dest hook */ 92 char ifNotMatch[NG_HOOKSIZ]; /* !match dest hook */ 93 int32_t bpf_prog_len; /* #insns in program */ 94 struct bpf_insn bpf_prog[]; /* bpf program */ 95}; 96.Ed 97.Pp 98The hook to be updated is specified in 99.Dv thisHook . 100The BPF program is the sequence of instructions in the 101.Dv bpf_prog 102array; there must be 103.Dv bpf_prog_len 104of them. 105Matching and non-matching incoming packets are delivered out the hooks named 106.Dv ifMatch 107and 108.Dv ifNotMatch , 109respectively. 110The program must be a valid 111.Xr bpf 4 112program or else 113.Er EINVAL 114is returned. 115.It Dv NGM_BPF_GET_PROGRAM Pq Ic getprogram 116This command takes an ASCII 117string argument, the hook name, and returns the 118corresponding 119.Dv "struct ng_bpf_hookprog" 120as shown above. 121.It Dv NGM_BPF_GET_STATS Pq Ic getstats 122This command takes an ASCII 123string argument, the hook name, and returns the 124statistics associated with the hook as a 125.Dv "struct ng_bpf_hookstat" . 126.It Dv NGM_BPF_CLR_STATS Pq Ic clrstats 127This command takes an ASCII 128string argument, the hook name, and clears the 129statistics associated with the hook. 130.It Dv NGM_BPF_GETCLR_STATS Pq Ic getclrstats 131This command is identical to 132.Dv NGM_BPF_GET_STATS , 133except that the statistics are also atomically cleared. 134.El 135.Sh SHUTDOWN 136This node shuts down upon receipt of a 137.Dv NGM_SHUTDOWN 138control message, or when all hooks have been disconnected. 139.Sh EXAMPLES 140It is possible to configure a node from the command line, using 141.Xr tcpdump 1 142to generate raw BPF instructions which are then transformed 143into the ASCII form of a 144.Dv NGM_BPF_SET_PROGRAM 145control message, as demonstrated here: 146.Bd -literal -offset 4n 147#!/bin/sh 148 149PATTERN="tcp dst port 80" 150NODEPATH="my_node:" 151INHOOK="hook1" 152MATCHHOOK="hook2" 153NOTMATCHHOOK="hook3" 154 155BPFPROG=$( tcpdump -s 8192 -p -ddd ${PATTERN} | \\ 156 ( read len ; \\ 157 echo -n "bpf_prog_len=$len " ; \\ 158 echo -n "bpf_prog=[" ; \\ 159 while read code jt jf k ; do \\ 160 echo -n " { code=$code jt=$jt jf=$jf k=$k }" ; \\ 161 done ; \\ 162 echo " ]" ) ) 163 164ngctl msg ${NODEPATH} setprogram { thisHook=\\"${INHOOK}\\" \\ 165 ifMatch=\\"${MATCHHOOK}\\" \\ 166 ifNotMatch=\\"${NOTMATCHHOOK}\\" \\ 167 ${BPFPROG} } 168.Ed 169.Pp 170Based on the previous example, it is possible to prevent a jail (or a VM) 171from spoofing by allowing only traffic that has the expected ethernet and 172IP addresses: 173.Bd -literal -offset 4n 174#!/bin/sh 175 176NODEPATH="my_node:" 177JAIL_MAC="0a:00:de:ad:be:ef" 178JAIL_IP="128.66.1.42" 179JAIL_HOOK="jail" 180HOST_HOOK="host" 181DEBUG_HOOK="nomatch" 182 183bpf_prog() { 184 local PATTERN=$1 185 186 tcpdump -s 8192 -p -ddd ${PATTERN} | ( 187 read len 188 echo -n "bpf_prog_len=$len " 189 echo -n "bpf_prog=[" 190 while read code jt jf k ; do 191 echo -n " { code=$code jt=$jt jf=$jf k=$k }" 192 done 193 echo " ]" 194 ) 195} 196 197# Prevent jail from spoofing (filter packets coming from jail) 198ngctl msg ${NODEPATH} setprogram { \\ 199 thisHook=\\"${JAIL_HOOK}\\" \\ 200 ifMatch=\\"${HOST_HOOK}\\" \\ 201 ifNotMatch=\\"${DEBUG_HOOK}\\" \\ 202 $(bpf_prog "ether src ${JAIL_MAC} && src ${JAIL_IP}") \\ 203} 204 205# Prevent jail from receiving spoofed packets (filter packets 206# coming from host) 207ngctl msg ${NODEPATH} setprogram { \\ 208 thisHook=\\"${HOST_HOOK}\\" \\ 209 ifMatch=\\"${JAIL_HOOK}\\" \\ 210 ifNotMatch=\\"${DEBUG_HOOK}\\" \\ 211 $(bpf_prog "ether dst ${JAIL_MAC} && dst ${JAIL_IP}") \\ 212} 213.Ed 214.Sh SEE ALSO 215.Xr bpf 4 , 216.Xr netgraph 4 , 217.Xr ngctl 8 218.Sh HISTORY 219The 220.Nm 221node type was implemented in 222.Fx 4.0 . 223.Sh AUTHORS 224.An Archie Cobbs Aq Mt archie@FreeBSD.org 225.Sh BUGS 226When built as a loadable kernel module, this module includes the file 227.Pa net/bpf_filter.c . 228Although loading the module should fail if 229.Pa net/bpf_filter.c 230already exists in the kernel, currently it does not, and the duplicate 231copies of the file do not interfere. 232However, this may change in the future. 233