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