1.\" Copyright (c) 2004 FreeBSD Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd May 11, 2012 28.Dt BPF 9 29.Os 30.\" 31.Sh NAME 32.Nm bpf 33.Nd "Berkeley Packet Filter" 34.\" 35.Sh SYNOPSIS 36.In net/bpf.h 37.\" 38.Ft void 39.Fn bpfattach "struct ifnet *ifp" "u_int dlt" "u_int hdrlen" 40.Ft void 41.Fo bpfattach2 42.Fa "struct ifnet *ifp" "u_int dlt" "u_int hdrlen" "struct bpf_if **driverp" 43.Fc 44.Ft void 45.Fn bpfdetach "struct ifnet *ifp" 46.Ft void 47.Fn bpf_tap "struct ifnet *ifp" "u_char *pkt" "u_int *pktlen" 48.Ft void 49.Fn bpf_mtap "struct ifnet *ifp" "struct mbuf *m" 50.Ft void 51.Fn bpf_mtap2 "struct bpf_if *bp" "void *data" "u_int dlen" "struct mbuf *m" 52.Ft u_int 53.Fo bpf_filter 54.Fa "const struct bpf_insn *pc " "u_char *pkt" "u_int wirelen" "u_int buflen" 55.Fc 56.Ft int 57.Fn bpf_validate "const struct bpf_insn *fcode" "int flen" 58.\" 59.Sh DESCRIPTION 60The Berkeley Packet Filter provides a raw interface, 61that is protocol independent, 62to data link layers. 63It allows all packets on the network, 64even those destined for other hosts, 65to be passed from a network interface to user programs. 66Each program may specify a filter, 67in the form of a 68.Nm 69filter machine program. 70The 71.Xr bpf 4 72manual page 73describes the interface used by user programs. 74This manual page describes the functions used by interfaces to pass packets to 75.Nm 76and the functions for testing and running 77.Nm 78filter machine programs. 79.Pp 80The 81.Fn bpfattach 82function 83attaches a network interface to 84.Nm . 85The 86.Fa ifp 87argument 88is a pointer to the structure that defines the interface to be 89attached to an interface. 90The 91.Fa dlt 92argument 93is the data link-layer type: 94.Dv DLT_NULL 95(no link-layer encapsulation), 96.Dv DLT_EN10MB 97(Ethernet), 98.Dv DLT_IEEE802_11 99(802.11 wireless networks), 100etc. 101The rest of the link layer types can be found in 102.In net/bpf.h . 103The 104.Fa hdrlen 105argument 106is the fixed size of the link header; 107variable length headers are not yet supported. 108The 109.Nm 110system will hold a pointer to 111.Fa ifp->if_bpf . 112This variable will set to a 113.Pf non- Dv NULL 114value when 115.Nm 116requires packets from this interface to be tapped using the functions below. 117.Pp 118The 119.Fn bpfattach2 120function 121allows multiple 122.Nm 123instances to be attached to a single interface, 124by registering an explicit 125.Fa if_bpf 126rather than using 127.Fa ifp->if_bpf . 128It is then possible to run 129.Xr tcpdump 1 130on the interface for any data link-layer types attached. 131.Pp 132The 133.Fn bpfdetach 134function detaches a 135.Nm 136instance from an interface, 137specified by 138.Fa ifp . 139The 140.Fn bpfdetach 141function 142should be called once for each 143.Nm 144instance attached. 145.Pp 146The 147.Fn bpf_tap 148function 149is used by an interface to pass the packet to 150.Nm . 151The packet data (including link-header), 152pointed to by 153.Fa pkt , 154is of length 155.Fa pktlen , 156which must be a contiguous buffer. 157The 158.Fa ifp 159argument 160is a pointer to the structure that defines the interface to be tapped. 161The packet is parsed by each processes filter, 162and if accepted, 163it is buffered for the process to read. 164.Pp 165The 166.Fn bpf_mtap 167function is like 168.Fn bpf_tap 169except that it is used to tap packets that are in an 170.Vt mbuf 171chain, 172.Fa m . 173The 174.Fa ifp 175argument 176is a pointer to the structure that defines the interface to be tapped. 177Like 178.Fn bpf_tap , 179.Fn bpf_mtap 180requires a link-header for whatever data link layer type is specified. 181Note that 182.Nm 183only reads from the 184.Vt mbuf 185chain, 186it does not free it or keep a pointer to it. 187This means that an 188.Vt mbuf 189containing the link-header 190can be prepended to the chain if necessary. 191A cleaner interface to achieve this is provided by 192.Fn bpf_mtap2 . 193.Pp 194The 195.Fn bpf_mtap2 196function 197allows the user to pass a link-header 198.Fa data , 199of length 200.Fa dlen , 201independent of the 202.Vt mbuf 203.Fa m , 204containing the packet. 205This simplifies the passing of some link-headers. 206.Pp 207The 208.Fn bpf_filter 209function 210executes the filter program starting at 211.Fa pc 212on the packet 213.Fa pkt . 214The 215.Fa wirelen 216argument 217is the length of the original packet and 218.Fa buflen 219is the amount of data present. 220The 221.Fa buflen 222value of 0 is special; it indicates that the 223.Fa pkt 224is actually a pointer to an mbuf chain 225.Pq Vt "struct mbuf *" . 226.Pp 227The 228.Fn bpf_validate 229function 230checks that the filter code 231.Fa fcode , 232of length 233.Fa flen , 234is valid. 235.\" 236.Sh RETURN VALUES 237The 238.Fn bpf_filter 239function returns \-1 240(cast to an unsigned integer) 241if there is no filter. 242Otherwise, it returns the result of the filter program. 243.Pp 244The 245.Fn bpf_validate 246function 247returns 0 when the program is not a valid filter program. 248.\" 249.Sh EVENT HANDLERS 250.Nm 251invokes 252.Fa bpf_track 253.Xr EVENTHANDLER 9 254event each time listener attaches to or detaches from an interface. 255Pointer to 256.Pq Vt "struct ifnet *" 257is passed as the first argument, interface 258.Fa dlt 259follows. Last argument indicates listener is attached (1) or 260detached (0). 261Note that handler is invoked with 262.Nm 263global lock held, which implies restriction on sleeping and calling 264.Nm 265subsystem inside 266.Xr EVENTHANDLER 9 267dispatcher. 268Note that handler is not called for write-only listeners. 269.\" 270.Sh SEE ALSO 271.Xr tcpdump 1 , 272.Xr bpf 4 , 273.Xr EVENTHANDLER 9 274.\" 275.Sh HISTORY 276The Enet packet filter was created in 1980 by Mike Accetta and 277Rick Rashid at Carnegie-Mellon University. 278Jeffrey Mogul, 279at Stanford, 280ported the code to 281.Bx 282and continued its development from 1983 on. 283Since then, 284it has evolved into the Ultrix Packet Filter at 285.Tn DEC , 286a 287.Tn STREAMS 288.Tn NIT 289module under 290.Tn SunOS 2914.1, and 292.Tn BPF . 293.\" 294.Sh AUTHORS 295.An -nosplit 296.An Steven McCanne , 297of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990. 298Much of the design is due to 299.An Van Jacobson . 300This manpage was written by 301.An Orla McGann . 302