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: src/share/man/man4/ng_bpf.4,v 1.17.2.1 2001/12/21 09:00:51 ru Exp $ 36.\" $Whistle: ng_bpf.8,v 1.2 1999/12/03 01:57:12 archie Exp $ 37.\" 38.Dd December 2, 1999 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 net/bpf.h 46.In netgraph/bpf/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. With each hook is associated a 55.Xr bpf 4 56filter program which is applied to incoming data only, a destination hook 57for matching packets, a destination hook for non-matching packets, 58and various statistics counters. 59.Pp 60A 61.Xr bpf 4 62program returns an unsigned integer, which is normally interpreted as 63the length of the prefix of the packet to return. In the context of this 64node type, returning zero is considered a non-match, in which case the 65entire packet is delivered out the non-match destination hook. 66Returning a value greater than zero causes the packet to be truncated 67to that length and delivered out the match destination hook. 68Either or both destination hooks may be the empty string, or may 69not exist, in which case the packet is dropped. 70.Pp 71New hooks are initially configured to drop all packets. 72A new filter program may be installed using the 73.Dv NGM_BPF_SET_PROGRAM 74control message. 75.Sh HOOKS 76This node type supports any number of hooks having arbitrary names. 77.Sh CONTROL MESSAGES 78This node type supports the generic control messages, plus the following: 79.Bl -tag -width foo 80.It Dv NGM_BPF_SET_PROGRAM 81This command sets the filter program that will be applied to incoming 82data on a hook. The following structure must be supplied as an argument: 83.Bd -literal -offset 4n 84struct ng_bpf_hookprog { 85 char thisHook[NG_HOOKSIZ]; /* name of hook */ 86 char ifMatch[NG_HOOKSIZ]; /* match dest hook */ 87 char ifNotMatch[NG_HOOKSIZ]; /* !match dest hook */ 88 int32_t bpf_prog_len; /* #isns in program */ 89 struct bpf_insn bpf_prog[0]; /* bpf program */ 90}; 91.Ed 92.Pp 93The hook to be updated is specified in 94.Dv thisHook . 95The BPF program is the sequence of instructions in the 96.Dv bpf_prog 97array; there must be 98.Dv bpf_prog_len 99of them. 100Matching and non-matching incoming packets are delivered out the hooks named 101.Dv ifMatch 102and 103.Dv ifNotMatch , 104respectively. The program must be a valid 105.Xr bpf 4 106program or else 107.Er EINVAL 108is returned. 109.It Dv NGM_BPF_GET_PROGRAM 110This command takes an 111.Tn ASCII 112string argument, the hook name, and returns the 113corresponding 114.Dv "struct ng_bpf_hookprog" 115as shown above. 116.It Dv NGM_BPF_GET_STATS 117This command takes an 118.Tn ASCII 119string argument, the hook name, and returns the 120statistics associated with the hook as a 121.Dv "struct ng_bpf_hookstat" . 122.It Dv NGM_BPF_CLR_STATS 123This command takes an 124.Tn ASCII 125string argument, the hook name, and clears the 126statistics associated with the hook. 127.It Dv NGM_BPF_GETCLR_STATS 128This command is identical to 129.Dv NGM_BPF_GET_STATS , 130except that the statistics are also atomically cleared. 131.El 132.Sh SHUTDOWN 133This node shuts down upon receipt of a 134.Dv NGM_SHUTDOWN 135control message, or when all hooks have been disconnected. 136.Sh EXAMPLES 137It is possible to configure a node from the command line, using 138.Xr tcpdump 1 139to generate raw BPF instructions which are then fed into an 140.Xr awk 1 141script to create 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 153cat > /tmp/bpf.awk << xxENDxx 154{ 155 if (!init) { 156 printf "bpf_prog_len=%d bpf_prog=[", \\$1; 157 init=1; 158 } else { 159 printf " { code=%d jt=%d jf=%d k=%d }", \\$1, \\$2, \\$3, \\$4; 160 } 161} 162END { 163 print " ]" 164} 165xxENDxx 166 167BPFPROG=`tcpdump -s 8192 -ddd ${PATTERN} | awk -f /tmp/bpf.awk` 168 169ngctl msg ${NODEPATH} setprogram { thisHook=\\"${INHOOK}\\" \\ 170 ifMatch=\\"${MATCHHOOK}\\" \\ 171 ifNotMatch=\\"${NOTMATCHHOOK}\\" \\ 172 ${BPFPROG} } } 173.Ed 174.Sh SEE ALSO 175.Xr bpf 4 , 176.Xr netgraph 4 , 177.Xr ngctl 8 178.Sh HISTORY 179The 180.Nm 181node type was implemented in 182.Fx 4.0 . 183.Sh AUTHORS 184.An Archie Cobbs Aq Mt archie@FreeBSD.org 185.Sh BUGS 186When built as a loadable kernel module, this module includes the file 187.Pa net/bpf_filter.c . 188Although loading the module should fail if 189.Pa net/bpf_filter.c 190already exists in the kernel, currently it does not, and the duplicate 191copies of the file do not interfere. 192However, this may change in the future. 193