share/man/man4/bpf.4

   1 .\" Copyright (c) 1990 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that: (1) source code distributions
   6 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   7 .\" distributions including binary code include the above copyright notice and
   8 .\" this paragraph in its entirety in the documentation or other materials
   9 .\" provided with the distribution, and (3) all advertising materials mentioning
  10 .\" features or use of this software display the following acknowledgement:
  11 .\" ``This product includes software developed by the University of California,
  12 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  13 .\" the University nor the names of its contributors may be used to endorse
  14 .\" or promote products derived from this software without specific prior
  15 .\" written permission.
  16 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  17 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  18 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  19 .\"
  20 .\" This document is derived in part from the enet man page (enet.4)
  21 .\" distributed with 4.3BSD Unix.
  22 .\"
  23 .\" $FreeBSD: src/share/man/man4/bpf.4,v 1.21.2.11 2002/04/07 04:57:13 dd Exp $
  24 .\" $DragonFly: src/share/man/man4/bpf.4,v 1.6 2007/11/04 19:04:42 swildner Exp $
  25 .\"
  26 .Dd January 16, 1996
  27 .Dt BPF 4
  28 .Os
  29 .Sh NAME
  30 .Nm bpf
  31 .Nd Berkeley Packet Filter
  32 .Sh SYNOPSIS
  33 .Cd pseudo-device bpf
  34 .Sh DESCRIPTION
  35 The Berkeley Packet Filter
  36 provides a raw interface to data link layers in a protocol
  37 independent fashion.
  38 All packets on the network, even those destined for other hosts,
  39 are accessible through this mechanism.
  40 .Pp
  41 The packet filter appears as a character special device,
  42 .Pa /dev/bpf0 ,
  43 .Pa /dev/bpf1 ,
  44 etc.
  45 After opening the device, the file descriptor must be bound to a
  46 specific network interface with the
  47 .Dv BIOCSETIF
  48 ioctl.
  49 A given interface can be shared by multiple listeners, and the filter
  50 underlying each descriptor will see an identical packet stream.
  51 .Pp
  52 A separate device file is required for each minor device.
  53 If a file is in use, the open will fail and
  54 .Va errno
  55 will be set to
  56 .Er EBUSY .
  57 .Pp
  58 Associated with each open instance of a
  59 .Nm
  60 file is a user-settable packet filter.
  61 Whenever a packet is received by an interface,
  62 all file descriptors listening on that interface apply their filter.
  63 Each descriptor that accepts the packet receives its own copy.
  64 .Pp
  65 Reads from these files return the next group of packets
  66 that have matched the filter.
  67 To improve performance, the buffer passed to read must be
  68 the same size as the buffers used internally by
  69 .Nm .
  70 This size is returned by the
  71 .Dv BIOCGBLEN
  72 ioctl (see below), and
  73 can be set with
  74 .Dv BIOCSBLEN .
  75 Note that an individual packet larger than this size is necessarily
  76 truncated.
  77 .Pp
  78 The packet filter will support any link level protocol that has fixed length
  79 headers.  Currently, only Ethernet,
  80 .Tn SLIP ,
  81 and
  82 .Tn PPP
  83 drivers have been modified to interact with
  84 .Nm .
  85 .Pp
  86 Since packet data is in network byte order, applications should use the
  87 .Xr byteorder 3
  88 macros to extract multi-byte values.
  89 .Pp
  90 A packet can be sent out on the network by writing to a
  91 .Nm
  92 file descriptor.  The writes are unbuffered, meaning only one
  93 packet can be processed per write.
  94 Currently, only writes to Ethernets and
  95 .Tn SLIP
  96 links are supported.
  97 .Sh IOCTLS
  98 The
  99 .Xr ioctl 2
 100 command codes below are defined in
 101 .In net/bpf.h .
 102 All commands require
 103 these includes:
 104 .Bd -literal
 105         #include <sys/types.h>
 106         #include <sys/time.h>
 107         #include <sys/ioctl.h>
 108         #include <net/bpf.h>
 109 .Ed
 110 .Pp
 111 Additionally,
 112 .Dv BIOCGETIF
 113 and
 114 .Dv BIOCSETIF
 115 require
 116 .In sys/socket.h
 117 and
 118 .In net/if.h .
 119 .Pp
 120 In addition to
 121 .Dv FIONREAD
 122 and
 123 .Dv SIOCGIFADDR ,
 124 the following commands may be applied to any open
 125 .Nm
 126 file.
 127 The (third) argument to
 128 .Xr ioctl 2
 129 should be a pointer to the type indicated.
 130 .Bl -tag -width ".Dv BIOCGRTIMEOUT"
 131 .It Dv BIOCGBLEN
 132 .Pq Li u_int
 133 Returns the required buffer length for reads on
 134 .Nm
 135 files.
 136 .It Dv BIOCSBLEN
 137 .Pq Li u_int
 138 Sets the buffer length for reads on
 139 .Nm
 140 files.  The buffer must be set before the file is attached to an interface
 141 with
 142 .Dv BIOCSETIF .
 143 If the requested buffer size cannot be accommodated, the closest
 144 allowable size will be set and returned in the argument.
 145 A read call will result in
 146 .Er EIO
 147 if it is passed a buffer that is not this size.
 148 .It Dv BIOCGDLT
 149 .Pq Li u_int
 150 Returns the type of the data link layer underlying the attached interface.
 151 .Er EINVAL
 152 is returned if no interface has been specified.
 153 The device types, prefixed with
 154 .Dq Li DLT_ ,
 155 are defined in
 156 .In net/bpf.h .
 157 .It Dv BIOCPROMISC
 158 Forces the interface into promiscuous mode.
 159 All packets, not just those destined for the local host, are processed.
 160 Since more than one file can be listening on a given interface,
 161 a listener that opened its interface non-promiscuously may receive
 162 packets promiscuously.  This problem can be remedied with an
 163 appropriate filter.
 164 .It Dv BIOCFLUSH
 165 Flushes the buffer of incoming packets,
 166 and resets the statistics that are returned by
 167 .Dv BIOCGSTATS .
 168 .It Dv BIOCGETIF
 169 .Pq Li "struct ifreq"
 170 Returns the name of the hardware interface that the file is listening on.
 171 The name is returned in the ifr_name field of
 172 the
 173 .Li ifreq
 174 structure.
 175 All other fields are undefined.
 176 .It Dv BIOCSETIF
 177 .Pq Li "struct ifreq"
 178 Sets the hardware interface associated with the file.
 179 This command must be performed before any packets can be read.
 180 The device is indicated by name using the
 181 .Li ifr_name
 182 field of the
 183 .Li ifreq
 184 structure.
 185 Additionally, performs the actions of
 186 .Dv BIOCFLUSH .
 187 .It Dv BIOCSRTIMEOUT
 188 .It Dv BIOCGRTIMEOUT
 189 .Pq Li "struct timeval"
 190 Set or get the read timeout parameter.
 191 The argument
 192 specifies the length of time to wait before timing
 193 out on a read request.
 194 This parameter is initialized to zero by
 195 .Xr open 2 ,
 196 indicating no timeout.
 197 .It Dv BIOCGSTATS
 198 .Pq Li "struct bpf_stat"
 199 Returns the following structure of packet statistics:
 200 .Bd -literal
 201 struct bpf_stat {
 202         u_int bs_recv;    /* number of packets received */
 203         u_int bs_drop;    /* number of packets dropped */
 204 };
 205 .Ed
 206 .Pp
 207 The fields are:
 208 .Bl -hang -offset indent
 209 .It Li bs_recv
 210 the number of packets received by the descriptor since opened or reset
 211 (including any buffered since the last read call);
 212 and
 213 .It Li bs_drop
 214 the number of packets which were accepted by the filter but dropped by the
 215 kernel because of buffer overflows
 216 (i.e., the application's reads aren't keeping up with the packet traffic).
 217 .El
 218 .It Dv BIOCIMMEDIATE
 219 .Pq Li u_int
 220 Enable or disable
 221 .Dq immediate mode ,
 222 based on the truth value of the argument.
 223 When immediate mode is enabled, reads return immediately upon packet
 224 reception.  Otherwise, a read will block until either the kernel buffer
 225 becomes full or a timeout occurs.
 226 This is useful for programs like
 227 .Xr rarpd 8
 228 which must respond to messages in real time.
 229 The default for a new file is off.
 230 .It Dv BIOCSETF
 231 .Pq Li "struct bpf_program"
 232 Sets the filter program used by the kernel to discard uninteresting
 233 packets.  An array of instructions and its length is passed in using
 234 the following structure:
 235 .Bd -literal
 236 struct bpf_program {
 237         int bf_len;
 238         struct bpf_insn *bf_insns;
 239 };
 240 .Ed
 241 .Pp
 242 The filter program is pointed to by the
 243 .Li bf_insns
 244 field while its length in units of
 245 .Sq Li struct bpf_insn
 246 is given by the
 247 .Li bf_len
 248 field.
 249 Also, the actions of
 250 .Dv BIOCFLUSH
 251 are performed.
 252 See section
 253 .Sx "FILTER MACHINE"
 254 for an explanation of the filter language.
 255 .It Dv BIOCVERSION
 256 .Pq Li "struct bpf_version"
 257 Returns the major and minor version numbers of the filter language currently
 258 recognized by the kernel.  Before installing a filter, applications must check
 259 that the current version is compatible with the running kernel.  Version
 260 numbers are compatible if the major numbers match and the application minor
 261 is less than or equal to the kernel minor.  The kernel version number is
 262 returned in the following structure:
 263 .Bd -literal
 264 struct bpf_version {
 265         u_short bv_major;
 266         u_short bv_minor;
 267 };
 268 .Ed
 269 .Pp
 270 The current version numbers are given by
 271 .Dv BPF_MAJOR_VERSION
 272 and
 273 .Dv BPF_MINOR_VERSION
 274 from
 275 .In net/bpf.h .
 276 An incompatible filter
 277 may result in undefined behavior (most likely, an error returned by
 278 .Fn ioctl
 279 or haphazard packet matching).
 280 .It Dv BIOCSHDRCMPLT
 281 .It Dv BIOCGHDRCMPLT
 282 .Pq Li u_int
 283 Set or get the status of the
 284 .Dq header complete
 285 flag.
 286 Set to zero if the link level source address should be filled in automatically
 287 by the interface output routine.  Set to one if the link level source
 288 address will be written, as provided, to the wire.  This flag is initialized
 289 to zero by default.
 290 .It Dv BIOCSSEESENT
 291 .It Dv BIOCGSEESENT
 292 .Pq Li u_int
 293 Set or get the flag determining whether locally generated packets on the
 294 interface should be returned by BPF.  Set to zero to see only incoming
 295 packets on the interface.  Set to one to see packets originating
 296 locally and remotely on the interface.  This flag is initialized to one by
 297 default.
 298 .El
 299 .Sh BPF HEADER
 300 The following structure is prepended to each packet returned by
 301 .Xr read 2 :
 302 .Bd -literal
 303 struct bpf_hdr {
 304         struct timeval bh_tstamp;     /* time stamp */
 305         u_long bh_caplen;             /* length of captured portion */
 306         u_long bh_datalen;            /* original length of packet */
 307         u_short bh_hdrlen;            /* length of bpf header (this struct
 308                                          plus alignment padding */
 309 };
 310 .Ed
 311 .Pp
 312 The fields, whose values are stored in host order, and are:
 313 .Pp
 314 .Bl -tag -compact -width bh_datalen
 315 .It Li bh_tstamp
 316 The time at which the packet was processed by the packet filter.
 317 .It Li bh_caplen
 318 The length of the captured portion of the packet.  This is the minimum of
 319 the truncation amount specified by the filter and the length of the packet.
 320 .It Li bh_datalen
 321 The length of the packet off the wire.
 322 This value is independent of the truncation amount specified by the filter.
 323 .It Li bh_hdrlen
 324 The length of the
 325 .Nm
 326 header, which may not be equal to
 327 .\" XXX - not really a function call
 328 .Fn sizeof "struct bpf_hdr" .
 329 .El
 330 .Pp
 331 The
 332 .Li bh_hdrlen
 333 field exists to account for
 334 padding between the header and the link level protocol.
 335 The purpose here is to guarantee proper alignment of the packet
 336 data structures, which is required on alignment sensitive
 337 architectures and improves performance on many other architectures.
 338 The packet filter insures that the
 339 .Li bpf_hdr
 340 and the network layer
 341 header will be word aligned.  Suitable precautions
 342 must be taken when accessing the link layer protocol fields on alignment
 343 restricted machines.  (This isn't a problem on an Ethernet, since
 344 the type field is a short falling on an even offset,
 345 and the addresses are probably accessed in a bytewise fashion).
 346 .Pp
 347 Additionally, individual packets are padded so that each starts
 348 on a word boundary.  This requires that an application
 349 has some knowledge of how to get from packet to packet.
 350 The macro
 351 .Dv BPF_WORDALIGN
 352 is defined in
 353 .In net/bpf.h
 354 to facilitate
 355 this process.  It rounds up its argument
 356 to the nearest word aligned value (where a word is
 357 .Dv BPF_ALIGNMENT
 358 bytes wide).
 359 .Pp
 360 For example, if
 361 .Sq Li p
 362 points to the start of a packet, this expression
 363 will advance it to the next packet:
 364 .Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen)
 365 .Pp
 366 For the alignment mechanisms to work properly, the
 367 buffer passed to
 368 .Xr read 2
 369 must itself be word aligned.
 370 The
 371 .Xr malloc 3
 372 function
 373 will always return an aligned buffer.
 374 .Sh FILTER MACHINE
 375 A filter program is an array of instructions, with all branches forwardly
 376 directed, terminated by a
 377 .Em return
 378 instruction.
 379 Each instruction performs some action on the pseudo-machine state,
 380 which consists of an accumulator, index register, scratch memory store,
 381 and implicit program counter.
 382 .Pp
 383 The following structure defines the instruction format:
 384 .Bd -literal
 385 struct bpf_insn {
 386         u_short code;
 387         u_char  jt;
 388         u_char  jf;
 389         u_long k;
 390 };
 391 .Ed
 392 .Pp
 393 The
 394 .Li k
 395 field is used in different ways by different instructions,
 396 and the
 397 .Li jt
 398 and
 399 .Li jf
 400 fields are used as offsets
 401 by the branch instructions.
 402 The opcodes are encoded in a semi-hierarchical fashion.
 403 There are eight classes of instructions:
 404 .Dv BPF_LD ,
 405 .Dv BPF_LDX ,
 406 .Dv BPF_ST ,
 407 .Dv BPF_STX ,
 408 .Dv BPF_ALU ,
 409 .Dv BPF_JMP ,
 410 .Dv BPF_RET ,
 411 and
 412 .Dv BPF_MISC .
 413 Various other mode and
 414 operator bits are or'd into the class to give the actual instructions.
 415 The classes and modes are defined in
 416 .In net/bpf.h .
 417 .Pp
 418 Below are the semantics for each defined
 419 .Nm
 420 instruction.
 421 We use the convention that A is the accumulator, X is the index register,
 422 P[] packet data, and M[] scratch memory store.
 423 P[i:n] gives the data at byte offset
 424 .Dq i
 425 in the packet,
 426 interpreted as a word (n=4),
 427 unsigned halfword (n=2), or unsigned byte (n=1).
 428 M[i] gives the i'th word in the scratch memory store, which is only
 429 addressed in word units.  The memory store is indexed from 0 to
 430 .Dv BPF_MEMWORDS
 431 - 1.
 432 .Li k ,
 433 .Li jt ,
 434 and
 435 .Li jf
 436 are the corresponding fields in the
 437 instruction definition.
 438 .Dq len
 439 refers to the length of the packet.
 440 .Pp
 441 .Bl -tag -width BPF_STXx
 442 .It Dv BPF_LD
 443 These instructions copy a value into the accumulator.  The type of the
 444 source operand is specified by an
 445 .Dq addressing mode
 446 and can be a constant
 447 .Pq Dv BPF_IMM ,
 448 packet data at a fixed offset
 449 .Pq Dv BPF_ABS ,
 450 packet data at a variable offset
 451 .Pq Dv BPF_IND ,
 452 the packet length
 453 .Pq Dv BPF_LEN ,
 454 or a word in the scratch memory store
 455 .Pq Dv BPF_MEM .
 456 For
 457 .Dv BPF_IND
 458 and
 459 .Dv BPF_ABS ,
 460 the data size must be specified as a word
 461 .Pq Dv BPF_W ,
 462 halfword
 463 .Pq Dv BPF_H ,
 464 or byte
 465 .Pq Dv BPF_B .
 466 The semantics of all the recognized
 467 .Dv BPF_LD
 468 instructions follow.
 469 .Pp
 470 .Bl -tag -width "BPF_LD+BPF_W+BPF_IND" -compact
 471 .It Li BPF_LD+BPF_W+BPF_ABS
 472 A <- P[k:4]
 473 .It Li BPF_LD+BPF_H+BPF_ABS
 474 A <- P[k:2]
 475 .It Li BPF_LD+BPF_B+BPF_ABS
 476 A <- P[k:1]
 477 .It Li BPF_LD+BPF_W+BPF_IND
 478 A <- P[X+k:4]
 479 .It Li BPF_LD+BPF_H+BPF_IND
 480 A <- P[X+k:2]
 481 .It Li BPF_LD+BPF_B+BPF_IND
 482 A <- P[X+k:1]
 483 .It Li BPF_LD+BPF_W+BPF_LEN
 484 A <- len
 485 .It Li BPF_LD+BPF_IMM
 486 A <- k
 487 .It Li BPF_LD+BPF_MEM
 488 A <- M[k]
 489 .El
 490 .It Dv BPF_LDX
 491 These instructions load a value into the index register.  Note that
 492 the addressing modes are more restrictive than those of the accumulator loads,
 493 but they include
 494 .Dv BPF_MSH ,
 495 a hack for efficiently loading the IP header length.
 496 .Pp
 497 .Bl -tag -width "BPF_LDX+BPF_W+BPF_MEM" -compact
 498 .It Li BPF_LDX+BPF_W+BPF_IMM
 499 X <- k
 500 .It Li BPF_LDX+BPF_W+BPF_MEM
 501 X <- M[k]
 502 .It Li BPF_LDX+BPF_W+BPF_LEN
 503 X <- len
 504 .It Li BPF_LDX+BPF_B+BPF_MSH
 505 X <- 4*(P[k:1]&0xf)
 506 .El
 507 .It Dv BPF_ST
 508 This instruction stores the accumulator into the scratch memory.
 509 We do not need an addressing mode since there is only one possibility
 510 for the destination.
 511 .Pp
 512 .Bl -tag -width "BPF_ST" -compact
 513 .It Li BPF_ST
 514 M[k] <- A
 515 .El
 516 .It Dv BPF_STX
 517 This instruction stores the index register in the scratch memory store.
 518 .Pp
 519 .Bl -tag -width "BPF_STX" -compact
 520 .It Li BPF_STX
 521 M[k] <- X
 522 .El
 523 .It Dv BPF_ALU
 524 The alu instructions perform operations between the accumulator and
 525 index register or constant, and store the result back in the accumulator.
 526 For binary operations, a source mode is required
 527 .Dv ( BPF_K
 528 or
 529 .Dv BPF_X ) .
 530 .Pp
 531 .Bl -tag -width "BPF_ALU+BPF_MUL+BPF_K" -compact
 532 .It Li BPF_ALU+BPF_ADD+BPF_K
 533 A <- A + k
 534 .It Li BPF_ALU+BPF_SUB+BPF_K
 535 A <- A - k
 536 .It Li BPF_ALU+BPF_MUL+BPF_K
 537 A <- A * k
 538 .It Li BPF_ALU+BPF_DIV+BPF_K
 539 A <- A / k
 540 .It Li BPF_ALU+BPF_AND+BPF_K
 541 A <- A & k
 542 .It Li BPF_ALU+BPF_OR+BPF_K
 543 A <- A | k
 544 .It Li BPF_ALU+BPF_LSH+BPF_K
 545 A <- A << k
 546 .It Li BPF_ALU+BPF_RSH+BPF_K
 547 A <- A >> k
 548 .It Li BPF_ALU+BPF_ADD+BPF_X
 549 A <- A + X
 550 .It Li BPF_ALU+BPF_SUB+BPF_X
 551 A <- A - X
 552 .It Li BPF_ALU+BPF_MUL+BPF_X
 553 A <- A * X
 554 .It Li BPF_ALU+BPF_DIV+BPF_X
 555 A <- A / X
 556 .It Li BPF_ALU+BPF_AND+BPF_X
 557 A <- A & X
 558 .It Li BPF_ALU+BPF_OR+BPF_X
 559 A <- A | X
 560 .It Li BPF_ALU+BPF_LSH+BPF_X
 561 A <- A << X
 562 .It Li BPF_ALU+BPF_RSH+BPF_X
 563 A <- A >> X
 564 .It Li BPF_ALU+BPF_NEG
 565 A <- -A
 566 .El
 567 .It Dv BPF_JMP
 568 The jump instructions alter flow of control.  Conditional jumps
 569 compare the accumulator against a constant
 570 .Pq Dv BPF_K
 571 or the index register
 572 .Pq Dv BPF_X .
 573 If the result is true (or non-zero),
 574 the true branch is taken, otherwise the false branch is taken.
 575 Jump offsets are encoded in 8 bits so the longest jump is 256 instructions.
 576 However, the jump always
 577 .Pq Dv BPF_JA
 578 opcode uses the 32 bit
 579 .Li k
 580 field as the offset, allowing arbitrarily distant destinations.
 581 All conditionals use unsigned comparison conventions.
 582 .Pp
 583 .Bl -tag -width "BPF_JMP+BPF_KSET+BPF_X" -compact
 584 .It Li BPF_JMP+BPF_JA
 585 pc += k
 586 .It Li BPF_JMP+BPF_JGT+BPF_K
 587 pc += (A > k) ? jt : jf
 588 .It Li BPF_JMP+BPF_JGE+BPF_K
 589 pc += (A >= k) ? jt : jf
 590 .It Li BPF_JMP+BPF_JEQ+BPF_K
 591 pc += (A == k) ? jt : jf
 592 .It Li BPF_JMP+BPF_JSET+BPF_K
 593 pc += (A & k) ? jt : jf
 594 .It Li BPF_JMP+BPF_JGT+BPF_X
 595 pc += (A > X) ? jt : jf
 596 .It Li BPF_JMP+BPF_JGE+BPF_X
 597 pc += (A >= X) ? jt : jf
 598 .It Li BPF_JMP+BPF_JEQ+BPF_X
 599 pc += (A == X) ? jt : jf
 600 .It Li BPF_JMP+BPF_JSET+BPF_X
 601 pc += (A & X) ? jt : jf
 602 .El
 603 .It Dv BPF_RET
 604 The return instructions terminate the filter program and specify the amount
 605 of packet to accept (i.e., they return the truncation amount).  A return
 606 value of zero indicates that the packet should be ignored.
 607 The return value is either a constant
 608 .Pq Dv BPF_K
 609 or the accumulator
 610 .Pq Dv BPF_A .
 611 .Pp
 612 .Bl -tag -width "BPF_RET+BPF_K" -compact
 613 .It Li BPF_RET+BPF_A
 614 accept A bytes
 615 .It Li BPF_RET+BPF_K
 616 accept k bytes
 617 .El
 618 .It Dv BPF_MISC
 619 The miscellaneous category was created for anything that doesn't
 620 fit into the above classes, and for any new instructions that might need to
 621 be added.  Currently, these are the register transfer instructions
 622 that copy the index register to the accumulator or vice versa.
 623 .Pp
 624 .Bl -tag -width "BPF_MISC+BPF_TAX" -compact
 625 .It Li BPF_MISC+BPF_TAX
 626 X <- A
 627 .It Li BPF_MISC+BPF_TXA
 628 A <- X
 629 .El
 630 .El
 631 .Pp
 632 The
 633 .Nm
 634 interface provides the following macros to facilitate
 635 array initializers:
 636 .Fn BPF_STMT opcode operand
 637 and
 638 .Fn BPF_JUMP opcode operand true_offset false_offset .
 639 .Sh FILES
 640 .Bl -tag -compact -width /dev/bpfXXX
 641 .It Pa /dev/bpf Ns Sy n
 642 the packet filter device
 643 .El
 644 .Sh EXAMPLES
 645 The following filter is taken from the Reverse ARP Daemon.  It accepts
 646 only Reverse ARP requests.
 647 .Bd -literal
 648 struct bpf_insn insns[] = {
 649         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
 650         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3),
 651         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
 652         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1),
 653         BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) +
 654                  sizeof(struct ether_header)),
 655         BPF_STMT(BPF_RET+BPF_K, 0),
 656 };
 657 .Ed
 658 .Pp
 659 This filter accepts only IP packets between host 128.3.112.15 and
 660 128.3.112.35.
 661 .Bd -literal
 662 struct bpf_insn insns[] = {
 663         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
 664         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8),
 665         BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26),
 666         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2),
 667         BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
 668         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4),
 669         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3),
 670         BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
 671         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1),
 672         BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
 673         BPF_STMT(BPF_RET+BPF_K, 0),
 674 };
 675 .Ed
 676 .Pp
 677 Finally, this filter returns only TCP finger packets.  We must parse
 678 the IP header to reach the TCP header.  The
 679 .Dv BPF_JSET
 680 instruction
 681 checks that the IP fragment offset is 0 so we are sure
 682 that we have a TCP header.
 683 .Bd -literal
 684 struct bpf_insn insns[] = {
 685         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
 686         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10),
 687         BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23),
 688         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8),
 689         BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
 690         BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0),
 691         BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14),
 692         BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14),
 693         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0),
 694         BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16),
 695         BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1),
 696         BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
 697         BPF_STMT(BPF_RET+BPF_K, 0),
 698 };
 699 .Ed
 700 .Sh SEE ALSO
 701 .Xr tcpdump 1 ,
 702 .Xr ioctl 2 ,
 703 .Xr byteorder 3 ,
 704 .Xr ng_bpf 4
 705 .Rs
 706 .%A McCanne, S.
 707 .%A Jacobson V.
 708 .%T "An efficient, extensible, and portable network monitor"
 709 .Re
 710 .Sh HISTORY
 711 The Enet packet filter was created in 1980 by Mike Accetta and
 712 Rick Rashid at Carnegie-Mellon University.  Jeffrey Mogul, at
 713 Stanford, ported the code to
 714 .Bx
 715 and continued its development from
 716 1983 on.  Since then, it has evolved into the Ultrix Packet Filter
 717 at
 718 .Tn DEC ,
 719 a
 720 .Tn STREAMS
 721 .Tn NIT
 722 module under
 723 .Tn SunOS 4.1 ,
 724 and
 725 .Tn BPF .
 726 .Sh AUTHORS
 727 .An -nosplit
 728 .An Steven McCanne ,
 729 of Lawrence Berkeley Laboratory, implemented BPF in
 730 Summer 1990.  Much of the design is due to
 731 .An Van Jacobson .
 732 .Sh BUGS
 733 The read buffer must be of a fixed size (returned by the
 734 .Dv BIOCGBLEN
 735 ioctl).
 736 .Pp
 737 A file that does not request promiscuous mode may receive promiscuously
 738 received packets as a side effect of another file requesting this
 739 mode on the same hardware interface.  This could be fixed in the kernel
 740 with additional processing overhead.  However, we favor the model where
 741 all files must assume that the interface is promiscuous, and if
 742 so desired, must utilize a filter to reject foreign packets.
 743 .Pp
 744 Data link protocols with variable length headers are not currently supported.