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