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 December 13, 2006
  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 SEE ALSO
 250 .Xr tcpdump 1 ,
 251 .Xr bpf 4
 252 .\"
 253 .Sh HISTORY
 254 The Enet packet filter was created in 1980 by Mike Accetta and
 255 Rick Rashid at Carnegie-Mellon University.
 256 Jeffrey Mogul,
 257 at Stanford,
 258 ported the code to
 259 .Bx
 260 and continued its development from 1983 on.
 261 Since then,
 262 it has evolved into the Ultrix Packet Filter at
 263 .Tn DEC ,
 264 a
 265 .Tn STREAMS
 266 .Tn NIT
 267 module under
 268 .Tn SunOS
 269 4.1, and
 270 .Tn BPF .
 271 .\"
 272 .Sh AUTHORS
 273 .An -nosplit
 274 .An Steven McCanne ,
 275 of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990.
 276 Much of the design is due to
 277 .An Van Jacobson .
 278 This manpage was written by
 279 .An Orla McGann .