share/man/man9/bpf.9

   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
  60 The Berkeley Packet Filter provides a raw interface,
  61 that is protocol independent,
  62 to data link layers.
  63 It allows all packets on the network,
  64 even those destined for other hosts,
  65 to be passed from a network interface to user programs.
  66 Each program may specify a filter,
  67 in the form of a
  68 .Nm
  69 filter machine program.
  70 The
  71 .Xr bpf 4
  72 manual page
  73 describes the interface used by user programs.
  74 This manual page describes the functions used by interfaces to pass packets to
  75 .Nm
  76 and the functions for testing and running
  77 .Nm
  78 filter machine programs.
  79 .Pp
  80 The
  81 .Fn bpfattach
  82 function
  83 attaches a network interface to
  84 .Nm .
  85 The
  86 .Fa ifp
  87 argument
  88 is a pointer to the structure that defines the interface to be
  89 attached to an interface.
  90 The
  91 .Fa dlt
  92 argument
  93 is 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),
 100 etc.
 101 The rest of the link layer types can be found in
 102 .In net/bpf.h .
 103 The
 104 .Fa hdrlen
 105 argument
 106 is the fixed size of the link header;
 107 variable length headers are not yet supported.
 108 The
 109 .Nm
 110 system will hold a pointer to
 111 .Fa ifp->if_bpf .
 112 This variable will set to a
 113 .Pf non- Dv NULL
 114 value when
 115 .Nm
 116 requires packets from this interface to be tapped using the functions below.
 117 .Pp
 118 The
 119 .Fn bpfattach2
 120 function
 121 allows multiple
 122 .Nm
 123 instances to be attached to a single interface,
 124 by registering an explicit
 125 .Fa if_bpf
 126 rather than using
 127 .Fa ifp->if_bpf .
 128 It is then possible to run
 129 .Xr tcpdump 1
 130 on the interface for any data link-layer types attached.
 131 .Pp
 132 The
 133 .Fn bpfdetach
 134 function detaches a
 135 .Nm
 136 instance from an interface,
 137 specified by
 138 .Fa ifp .
 139 The
 140 .Fn bpfdetach
 141 function
 142 should be called once for each
 143 .Nm
 144 instance attached.
 145 .Pp
 146 The
 147 .Fn bpf_tap
 148 function
 149 is used by an interface to pass the packet to
 150 .Nm .
 151 The packet data (including link-header),
 152 pointed to by
 153 .Fa pkt ,
 154 is of length
 155 .Fa pktlen ,
 156 which must be a contiguous buffer.
 157 The
 158 .Fa ifp
 159 argument
 160 is a pointer to the structure that defines the interface to be tapped.
 161 The packet is parsed by each processes filter,
 162 and if accepted,
 163 it is buffered for the process to read.
 164 .Pp
 165 The
 166 .Fn bpf_mtap
 167 function is like
 168 .Fn bpf_tap
 169 except that it is used to tap packets that are in an
 170 .Vt mbuf
 171 chain,
 172 .Fa m .
 173 The
 174 .Fa ifp
 175 argument
 176 is a pointer to the structure that defines the interface to be tapped.
 177 Like
 178 .Fn bpf_tap ,
 179 .Fn bpf_mtap
 180 requires a link-header for whatever data link layer type is specified.
 181 Note that
 182 .Nm
 183 only reads from the
 184 .Vt mbuf
 185 chain,
 186 it does not free it or keep a pointer to it.
 187 This means that an
 188 .Vt mbuf
 189 containing the link-header
 190 can be prepended to the chain if necessary.
 191 A cleaner interface to achieve this is provided by
 192 .Fn bpf_mtap2 .
 193 .Pp
 194 The
 195 .Fn bpf_mtap2
 196 function
 197 allows the user to pass a link-header
 198 .Fa data ,
 199 of length
 200 .Fa dlen ,
 201 independent of the
 202 .Vt mbuf
 203 .Fa m ,
 204 containing the packet.
 205 This simplifies the passing of some link-headers.
 206 .Pp
 207 The
 208 .Fn bpf_filter
 209 function
 210 executes the filter program starting at
 211 .Fa pc
 212 on the packet
 213 .Fa pkt .
 214 The
 215 .Fa wirelen
 216 argument
 217 is the length of the original packet and
 218 .Fa buflen
 219 is the amount of data present.
 220 The
 221 .Fa buflen
 222 value of 0 is special; it indicates that the
 223 .Fa pkt
 224 is actually a pointer to an mbuf chain
 225 .Pq Vt "struct mbuf *" .
 226 .Pp
 227 The
 228 .Fn bpf_validate
 229 function
 230 checks that the filter code
 231 .Fa fcode ,
 232 of length
 233 .Fa flen ,
 234 is valid.
 235 .\"
 236 .Sh RETURN VALUES
 237 The
 238 .Fn bpf_filter
 239 function returns \-1
 240 (cast to an unsigned integer)
 241 if there is no filter.
 242 Otherwise, it returns the result of the filter program.
 243 .Pp
 244 The
 245 .Fn bpf_validate
 246 function
 247 returns 0 when the program is not a valid filter program.
 248 .\"
 249 .Sh EVENT HANDLERS
 250 .Nm
 251 invokes
 252 .Fa bpf_track
 253 .Xr EVENTHANDLER 9
 254 event each time listener attaches to or detaches from an interface.
 255 Pointer to
 256 .Pq Vt "struct ifnet *"
 257 is passed as the first argument, interface
 258 .Fa dlt
 259 follows. Last argument indicates listener is attached (1) or
 260 detached (0).
 261 Note that handler is invoked with
 262 .Nm
 263 global lock held, which implies restriction on sleeping and calling
 264 .Nm
 265 subsystem inside
 266 .Xr EVENTHANDLER 9
 267 dispatcher.
 268 Note 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
 276 The Enet packet filter was created in 1980 by Mike Accetta and
 277 Rick Rashid at Carnegie-Mellon University.
 278 Jeffrey Mogul,
 279 at Stanford,
 280 ported the code to
 281 .Bx
 282 and continued its development from 1983 on.
 283 Since then,
 284 it has evolved into the Ultrix Packet Filter at
 285 .Tn DEC ,
 286 a
 287 .Tn STREAMS
 288 .Tn NIT
 289 module under
 290 .Tn SunOS
 291 4.1, and
 292 .Tn BPF .
 293 .\"
 294 .Sh AUTHORS
 295 .An -nosplit
 296 .An Steven McCanne ,
 297 of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990.
 298 Much of the design is due to
 299 .An Van Jacobson .
 300 This manpage was written by
 301 .An Orla McGann .