1.\" Copyright (c) 2007 Seccuris Inc. 2.\" All rights reserved. 3.\" 4.\" This software was developed by Robert N. M. Watson under contract to 5.\" Seccuris Inc. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" Copyright (c) 1990 The Regents of the University of California. 29.\" All rights reserved. 30.\" 31.\" Redistribution and use in source and binary forms, with or without 32.\" modification, are permitted provided that: (1) source code distributions 33.\" retain the above copyright notice and this paragraph in its entirety, (2) 34.\" distributions including binary code include the above copyright notice and 35.\" this paragraph in its entirety in the documentation or other materials 36.\" provided with the distribution, and (3) all advertising materials mentioning 37.\" features or use of this software display the following acknowledgement: 38.\" ``This product includes software developed by the University of California, 39.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of 40.\" the University nor the names of its contributors may be used to endorse 41.\" or promote products derived from this software without specific prior 42.\" written permission. 43.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED 44.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF 45.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 46.\" 47.\" This document is derived in part from the enet man page (enet.4) 48.\" distributed with 4.3BSD Unix. 49.\" 50.\" $FreeBSD$ 51.\" 52.Dd June 15, 2010 53.Dt BPF 4 54.Os 55.Sh NAME 56.Nm bpf 57.Nd Berkeley Packet Filter 58.Sh SYNOPSIS 59.Cd device bpf 60.Sh DESCRIPTION 61The Berkeley Packet Filter 62provides a raw interface to data link layers in a protocol 63independent fashion. 64All packets on the network, even those destined for other hosts, 65are accessible through this mechanism. 66.Pp 67The packet filter appears as a character special device, 68.Pa /dev/bpf . 69After opening the device, the file descriptor must be bound to a 70specific network interface with the 71.Dv BIOCSETIF 72ioctl. 73A given interface can be shared by multiple listeners, and the filter 74underlying each descriptor will see an identical packet stream. 75.Pp 76A separate device file is required for each minor device. 77If a file is in use, the open will fail and 78.Va errno 79will be set to 80.Er EBUSY . 81.Pp 82Associated with each open instance of a 83.Nm 84file is a user-settable packet filter. 85Whenever a packet is received by an interface, 86all file descriptors listening on that interface apply their filter. 87Each descriptor that accepts the packet receives its own copy. 88.Pp 89The packet filter will support any link level protocol that has fixed length 90headers. 91Currently, only Ethernet, 92.Tn SLIP , 93and 94.Tn PPP 95drivers have been modified to interact with 96.Nm . 97.Pp 98Since packet data is in network byte order, applications should use the 99.Xr byteorder 3 100macros to extract multi-byte values. 101.Pp 102A packet can be sent out on the network by writing to a 103.Nm 104file descriptor. 105The writes are unbuffered, meaning only one packet can be processed per write. 106Currently, only writes to Ethernets and 107.Tn SLIP 108links are supported. 109.Sh BUFFER MODES 110.Nm 111devices deliver packet data to the application via memory buffers provided by 112the application. 113The buffer mode is set using the 114.Dv BIOCSETBUFMODE 115ioctl, and read using the 116.Dv BIOCGETBUFMODE 117ioctl. 118.Ss Buffered read mode 119By default, 120.Nm 121devices operate in the 122.Dv BPF_BUFMODE_BUFFER 123mode, in which packet data is copied explicitly from kernel to user memory 124using the 125.Xr read 2 126system call. 127The user process will declare a fixed buffer size that will be used both for 128sizing internal buffers and for all 129.Xr read 2 130operations on the file. 131This size is queried using the 132.Dv BIOCGBLEN 133ioctl, and is set using the 134.Dv BIOCSBLEN 135ioctl. 136Note that an individual packet larger than the buffer size is necessarily 137truncated. 138.Ss Zero-copy buffer mode 139.Nm 140devices may also operate in the 141.Dv BPF_BUFMODE_ZEROCOPY 142mode, in which packet data is written directly into two user memory buffers 143by the kernel, avoiding both system call and copying overhead. 144Buffers are of fixed (and equal) size, page-aligned, and an even multiple of 145the page size. 146The maximum zero-copy buffer size is returned by the 147.Dv BIOCGETZMAX 148ioctl. 149Note that an individual packet larger than the buffer size is necessarily 150truncated. 151.Pp 152The user process registers two memory buffers using the 153.Dv BIOCSETZBUF 154ioctl, which accepts a 155.Vt struct bpf_zbuf 156pointer as an argument: 157.Bd -literal 158struct bpf_zbuf { 159 void *bz_bufa; 160 void *bz_bufb; 161 size_t bz_buflen; 162}; 163.Ed 164.Pp 165.Vt bz_bufa 166is a pointer to the userspace address of the first buffer that will be 167filled, and 168.Vt bz_bufb 169is a pointer to the second buffer. 170.Nm 171will then cycle between the two buffers as they fill and are acknowledged. 172.Pp 173Each buffer begins with a fixed-length header to hold synchronization and 174data length information for the buffer: 175.Bd -literal 176struct bpf_zbuf_header { 177 volatile u_int bzh_kernel_gen; /* Kernel generation number. */ 178 volatile u_int bzh_kernel_len; /* Length of data in the buffer. */ 179 volatile u_int bzh_user_gen; /* User generation number. */ 180 /* ...padding for future use... */ 181}; 182.Ed 183.Pp 184The header structure of each buffer, including all padding, should be zeroed 185before it is configured using 186.Dv BIOCSETZBUF . 187Remaining space in the buffer will be used by the kernel to store packet 188data, laid out in the same format as with buffered read mode. 189.Pp 190The kernel and the user process follow a simple acknowledgement protocol via 191the buffer header to synchronize access to the buffer: when the header 192generation numbers, 193.Vt bzh_kernel_gen 194and 195.Vt bzh_user_gen , 196hold the same value, the kernel owns the buffer, and when they differ, 197userspace owns the buffer. 198.Pp 199While the kernel owns the buffer, the contents are unstable and may change 200asynchronously; while the user process owns the buffer, its contents are 201stable and will not be changed until the buffer has been acknowledged. 202.Pp 203Initializing the buffer headers to all 0's before registering the buffer has 204the effect of assigning initial ownership of both buffers to the kernel. 205The kernel signals that a buffer has been assigned to userspace by modifying 206.Vt bzh_kernel_gen , 207and userspace acknowledges the buffer and returns it to the kernel by setting 208the value of 209.Vt bzh_user_gen 210to the value of 211.Vt bzh_kernel_gen . 212.Pp 213In order to avoid caching and memory re-ordering effects, the user process 214must use atomic operations and memory barriers when checking for and 215acknowledging buffers: 216.Bd -literal 217#include <machine/atomic.h> 218 219/* 220 * Return ownership of a buffer to the kernel for reuse. 221 */ 222static void 223buffer_acknowledge(struct bpf_zbuf_header *bzh) 224{ 225 226 atomic_store_rel_int(&bzh->bzh_user_gen, bzh->bzh_kernel_gen); 227} 228 229/* 230 * Check whether a buffer has been assigned to userspace by the kernel. 231 * Return true if userspace owns the buffer, and false otherwise. 232 */ 233static int 234buffer_check(struct bpf_zbuf_header *bzh) 235{ 236 237 return (bzh->bzh_user_gen != 238 atomic_load_acq_int(&bzh->bzh_kernel_gen)); 239} 240.Ed 241.Pp 242The user process may force the assignment of the next buffer, if any data 243is pending, to userspace using the 244.Dv BIOCROTZBUF 245ioctl. 246This allows the user process to retrieve data in a partially filled buffer 247before the buffer is full, such as following a timeout; the process must 248recheck for buffer ownership using the header generation numbers, as the 249buffer will not be assigned to userspace if no data was present. 250.Pp 251As in the buffered read mode, 252.Xr kqueue 2 , 253.Xr poll 2 , 254and 255.Xr select 2 256may be used to sleep awaiting the availability of a completed buffer. 257They will return a readable file descriptor when ownership of the next buffer 258is assigned to user space. 259.Pp 260In the current implementation, the kernel may assign zero, one, or both 261buffers to the user process; however, an earlier implementation maintained 262the invariant that at most one buffer could be assigned to the user process 263at a time. 264In order to both ensure progress and high performance, user processes should 265acknowledge a completely processed buffer as quickly as possible, returning 266it for reuse, and not block waiting on a second buffer while holding another 267buffer. 268.Sh IOCTLS 269The 270.Xr ioctl 2 271command codes below are defined in 272.In net/bpf.h . 273All commands require 274these includes: 275.Bd -literal 276 #include <sys/types.h> 277 #include <sys/time.h> 278 #include <sys/ioctl.h> 279 #include <net/bpf.h> 280.Ed 281.Pp 282Additionally, 283.Dv BIOCGETIF 284and 285.Dv BIOCSETIF 286require 287.In sys/socket.h 288and 289.In net/if.h . 290.Pp 291In addition to 292.Dv FIONREAD 293and 294.Dv SIOCGIFADDR , 295the following commands may be applied to any open 296.Nm 297file. 298The (third) argument to 299.Xr ioctl 2 300should be a pointer to the type indicated. 301.Bl -tag -width BIOCGETBUFMODE 302.It Dv BIOCGBLEN 303.Pq Li u_int 304Returns the required buffer length for reads on 305.Nm 306files. 307.It Dv BIOCSBLEN 308.Pq Li u_int 309Sets the buffer length for reads on 310.Nm 311files. 312The buffer must be set before the file is attached to an interface 313with 314.Dv BIOCSETIF . 315If the requested buffer size cannot be accommodated, the closest 316allowable size will be set and returned in the argument. 317A read call will result in 318.Er EIO 319if it is passed a buffer that is not this size. 320.It Dv BIOCGDLT 321.Pq Li u_int 322Returns the type of the data link layer underlying the attached interface. 323.Er EINVAL 324is returned if no interface has been specified. 325The device types, prefixed with 326.Dq Li DLT_ , 327are defined in 328.In net/bpf.h . 329.It Dv BIOCPROMISC 330Forces the interface into promiscuous mode. 331All packets, not just those destined for the local host, are processed. 332Since more than one file can be listening on a given interface, 333a listener that opened its interface non-promiscuously may receive 334packets promiscuously. 335This problem can be remedied with an appropriate filter. 336.It Dv BIOCFLUSH 337Flushes the buffer of incoming packets, 338and resets the statistics that are returned by BIOCGSTATS. 339.It Dv BIOCGETIF 340.Pq Li "struct ifreq" 341Returns the name of the hardware interface that the file is listening on. 342The name is returned in the ifr_name field of 343the 344.Li ifreq 345structure. 346All other fields are undefined. 347.It Dv BIOCSETIF 348.Pq Li "struct ifreq" 349Sets the hardware interface associate with the file. 350This 351command must be performed before any packets can be read. 352The device is indicated by name using the 353.Li ifr_name 354field of the 355.Li ifreq 356structure. 357Additionally, performs the actions of 358.Dv BIOCFLUSH . 359.It Dv BIOCSRTIMEOUT 360.It Dv BIOCGRTIMEOUT 361.Pq Li "struct timeval" 362Set or get the read timeout parameter. 363The argument 364specifies the length of time to wait before timing 365out on a read request. 366This parameter is initialized to zero by 367.Xr open 2 , 368indicating no timeout. 369.It Dv BIOCGSTATS 370.Pq Li "struct bpf_stat" 371Returns the following structure of packet statistics: 372.Bd -literal 373struct bpf_stat { 374 u_int bs_recv; /* number of packets received */ 375 u_int bs_drop; /* number of packets dropped */ 376}; 377.Ed 378.Pp 379The fields are: 380.Bl -hang -offset indent 381.It Li bs_recv 382the number of packets received by the descriptor since opened or reset 383(including any buffered since the last read call); 384and 385.It Li bs_drop 386the number of packets which were accepted by the filter but dropped by the 387kernel because of buffer overflows 388(i.e., the application's reads are not keeping up with the packet traffic). 389.El 390.It Dv BIOCIMMEDIATE 391.Pq Li u_int 392Enable or disable 393.Dq immediate mode , 394based on the truth value of the argument. 395When immediate mode is enabled, reads return immediately upon packet 396reception. 397Otherwise, a read will block until either the kernel buffer 398becomes full or a timeout occurs. 399This is useful for programs like 400.Xr rarpd 8 401which must respond to messages in real time. 402The default for a new file is off. 403.It Dv BIOCSETF 404.It Dv BIOCSETFNR 405.Pq Li "struct bpf_program" 406Sets the read filter program used by the kernel to discard uninteresting 407packets. 408An array of instructions and its length is passed in using 409the following structure: 410.Bd -literal 411struct bpf_program { 412 int bf_len; 413 struct bpf_insn *bf_insns; 414}; 415.Ed 416.Pp 417The filter program is pointed to by the 418.Li bf_insns 419field while its length in units of 420.Sq Li struct bpf_insn 421is given by the 422.Li bf_len 423field. 424See section 425.Sx "FILTER MACHINE" 426for an explanation of the filter language. 427The only difference between 428.Dv BIOCSETF 429and 430.Dv BIOCSETFNR 431is 432.Dv BIOCSETF 433performs the actions of 434.Dv BIOCFLUSH 435while 436.Dv BIOCSETFNR 437does not. 438.It Dv BIOCSETWF 439.Pq Li "struct bpf_program" 440Sets the write filter program used by the kernel to control what type of 441packets can be written to the interface. 442See the 443.Dv BIOCSETF 444command for more 445information on the 446.Nm 447filter program. 448.It Dv BIOCVERSION 449.Pq Li "struct bpf_version" 450Returns the major and minor version numbers of the filter language currently 451recognized by the kernel. 452Before installing a filter, applications must check 453that the current version is compatible with the running kernel. 454Version numbers are compatible if the major numbers match and the application minor 455is less than or equal to the kernel minor. 456The kernel version number is returned in the following structure: 457.Bd -literal 458struct bpf_version { 459 u_short bv_major; 460 u_short bv_minor; 461}; 462.Ed 463.Pp 464The current version numbers are given by 465.Dv BPF_MAJOR_VERSION 466and 467.Dv BPF_MINOR_VERSION 468from 469.In net/bpf.h . 470An incompatible filter 471may result in undefined behavior (most likely, an error returned by 472.Fn ioctl 473or haphazard packet matching). 474.It Dv BIOCSHDRCMPLT 475.It Dv BIOCGHDRCMPLT 476.Pq Li u_int 477Set or get the status of the 478.Dq header complete 479flag. 480Set to zero if the link level source address should be filled in automatically 481by the interface output routine. 482Set to one if the link level source 483address will be written, as provided, to the wire. 484This flag is initialized to zero by default. 485.It Dv BIOCSSEESENT 486.It Dv BIOCGSEESENT 487.Pq Li u_int 488These commands are obsolete but left for compatibility. 489Use 490.Dv BIOCSDIRECTION 491and 492.Dv BIOCGDIRECTION 493instead. 494Set or get the flag determining whether locally generated packets on the 495interface should be returned by BPF. 496Set to zero to see only incoming packets on the interface. 497Set to one to see packets originating locally and remotely on the interface. 498This flag is initialized to one by default. 499.It Dv BIOCSDIRECTION 500.It Dv BIOCGDIRECTION 501.Pq Li u_int 502Set or get the setting determining whether incoming, outgoing, or all packets 503on the interface should be returned by BPF. 504Set to 505.Dv BPF_D_IN 506to see only incoming packets on the interface. 507Set to 508.Dv BPF_D_INOUT 509to see packets originating locally and remotely on the interface. 510Set to 511.Dv BPF_D_OUT 512to see only outgoing packets on the interface. 513This setting is initialized to 514.Dv BPF_D_INOUT 515by default. 516.It Dv BIOCSTSTAMP 517.It Dv BIOCGTSTAMP 518.Pq Li u_int 519Set or get format and resolution of the time stamps returned by BPF. 520Set to 521.Dv BPF_T_MICROTIME , 522.Dv BPF_T_MICROTIME_FAST , 523.Dv BPF_T_MICROTIME_MONOTONIC , 524or 525.Dv BPF_T_MICROTIME_MONOTONIC_FAST 526to get time stamps in 64-bit 527.Vt struct timeval 528format. 529Set to 530.Dv BPF_T_NANOTIME , 531.Dv BPF_T_NANOTIME_FAST , 532.Dv BPF_T_NANOTIME_MONOTONIC , 533or 534.Dv BPF_T_NANOTIME_MONOTONIC_FAST 535to get time stamps in 64-bit 536.Vt struct timespec 537format. 538Set to 539.Dv BPF_T_BINTIME , 540.Dv BPF_T_BINTIME_FAST , 541.Dv BPF_T_NANOTIME_MONOTONIC , 542or 543.Dv BPF_T_BINTIME_MONOTONIC_FAST 544to get time stamps in 64-bit 545.Vt struct bintime 546format. 547Set to 548.Dv BPF_T_NONE 549to ignore time stamp. 550All 64-bit time stamp formats are wrapped in 551.Vt struct bpf_ts . 552The 553.Dv BPF_T_MICROTIME_FAST , 554.Dv BPF_T_NANOTIME_FAST , 555.Dv BPF_T_BINTIME_FAST , 556.Dv BPF_T_MICROTIME_MONOTONIC_FAST , 557.Dv BPF_T_NANOTIME_MONOTONIC_FAST , 558and 559.Dv BPF_T_BINTIME_MONOTONIC_FAST 560are analogs of corresponding formats without _FAST suffix but do not perform 561a full time counter query, so their accuracy is one timer tick. 562The 563.Dv BPF_T_MICROTIME_MONOTONIC , 564.Dv BPF_T_NANOTIME_MONOTONIC , 565.Dv BPF_T_BINTIME_MONOTONIC , 566.Dv BPF_T_MICROTIME_MONOTONIC_FAST , 567.Dv BPF_T_NANOTIME_MONOTONIC_FAST , 568and 569.Dv BPF_T_BINTIME_MONOTONIC_FAST 570store the time elapsed since kernel boot. 571This setting is initialized to 572.Dv BPF_T_MICROTIME 573by default. 574.It Dv BIOCFEEDBACK 575.Pq Li u_int 576Set packet feedback mode. 577This allows injected packets to be fed back as input to the interface when 578output via the interface is successful. 579When 580.Dv BPF_D_INOUT 581direction is set, injected outgoing packet is not returned by BPF to avoid 582duplication. This flag is initialized to zero by default. 583.It Dv BIOCLOCK 584Set the locked flag on the 585.Nm 586descriptor. 587This prevents the execution of 588ioctl commands which could change the underlying operating parameters of 589the device. 590.It Dv BIOCGETBUFMODE 591.It Dv BIOCSETBUFMODE 592.Pq Li u_int 593Get or set the current 594.Nm 595buffering mode; possible values are 596.Dv BPF_BUFMODE_BUFFER , 597buffered read mode, and 598.Dv BPF_BUFMODE_ZBUF , 599zero-copy buffer mode. 600.It Dv BIOCSETZBUF 601.Pq Li struct bpf_zbuf 602Set the current zero-copy buffer locations; buffer locations may be 603set only once zero-copy buffer mode has been selected, and prior to attaching 604to an interface. 605Buffers must be of identical size, page-aligned, and an integer multiple of 606pages in size. 607The three fields 608.Vt bz_bufa , 609.Vt bz_bufb , 610and 611.Vt bz_buflen 612must be filled out. 613If buffers have already been set for this device, the ioctl will fail. 614.It Dv BIOCGETZMAX 615.Pq Li size_t 616Get the largest individual zero-copy buffer size allowed. 617As two buffers are used in zero-copy buffer mode, the limit (in practice) is 618twice the returned size. 619As zero-copy buffers consume kernel address space, conservative selection of 620buffer size is suggested, especially when there are multiple 621.Nm 622descriptors in use on 32-bit systems. 623.It Dv BIOCROTZBUF 624Force ownership of the next buffer to be assigned to userspace, if any data 625present in the buffer. 626If no data is present, the buffer will remain owned by the kernel. 627This allows consumers of zero-copy buffering to implement timeouts and 628retrieve partially filled buffers. 629In order to handle the case where no data is present in the buffer and 630therefore ownership is not assigned, the user process must check 631.Vt bzh_kernel_gen 632against 633.Vt bzh_user_gen . 634.El 635.Sh BPF HEADER 636One of the following structures is prepended to each packet returned by 637.Xr read 2 638or via a zero-copy buffer: 639.Bd -literal 640struct bpf_xhdr { 641 struct bpf_ts bh_tstamp; /* time stamp */ 642 uint32_t bh_caplen; /* length of captured portion */ 643 uint32_t bh_datalen; /* original length of packet */ 644 u_short bh_hdrlen; /* length of bpf header (this struct 645 plus alignment padding) */ 646}; 647 648struct bpf_hdr { 649 struct timeval bh_tstamp; /* time stamp */ 650 uint32_t bh_caplen; /* length of captured portion */ 651 uint32_t bh_datalen; /* original length of packet */ 652 u_short bh_hdrlen; /* length of bpf header (this struct 653 plus alignment padding) */ 654}; 655.Ed 656.Pp 657The fields, whose values are stored in host order, and are: 658.Pp 659.Bl -tag -compact -width bh_datalen 660.It Li bh_tstamp 661The time at which the packet was processed by the packet filter. 662.It Li bh_caplen 663The length of the captured portion of the packet. 664This is the minimum of 665the truncation amount specified by the filter and the length of the packet. 666.It Li bh_datalen 667The length of the packet off the wire. 668This value is independent of the truncation amount specified by the filter. 669.It Li bh_hdrlen 670The length of the 671.Nm 672header, which may not be equal to 673.\" XXX - not really a function call 674.Fn sizeof "struct bpf_xhdr" 675or 676.Fn sizeof "struct bpf_hdr" . 677.El 678.Pp 679The 680.Li bh_hdrlen 681field exists to account for 682padding between the header and the link level protocol. 683The purpose here is to guarantee proper alignment of the packet 684data structures, which is required on alignment sensitive 685architectures and improves performance on many other architectures. 686The packet filter ensures that the 687.Vt bpf_xhdr , 688.Vt bpf_hdr 689and the network layer 690header will be word aligned. 691Currently, 692.Vt bpf_hdr 693is used when the time stamp is set to 694.Dv BPF_T_MICROTIME , 695.Dv BPF_T_MICROTIME_FAST , 696.Dv BPF_T_MICROTIME_MONOTONIC , 697.Dv BPF_T_MICROTIME_MONOTONIC_FAST , 698or 699.Dv BPF_T_NONE 700for backward compatibility reasons. 701Otherwise, 702.Vt bpf_xhdr 703is used. 704However, 705.Vt bpf_hdr 706may be deprecated in the near future. 707Suitable precautions 708must be taken when accessing the link layer protocol fields on alignment 709restricted machines. 710(This is not a problem on an Ethernet, since 711the type field is a short falling on an even offset, 712and the addresses are probably accessed in a bytewise fashion). 713.Pp 714Additionally, individual packets are padded so that each starts 715on a word boundary. 716This requires that an application 717has some knowledge of how to get from packet to packet. 718The macro 719.Dv BPF_WORDALIGN 720is defined in 721.In net/bpf.h 722to facilitate 723this process. 724It rounds up its argument to the nearest word aligned value (where a word is 725.Dv BPF_ALIGNMENT 726bytes wide). 727.Pp 728For example, if 729.Sq Li p 730points to the start of a packet, this expression 731will advance it to the next packet: 732.Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) 733.Pp 734For the alignment mechanisms to work properly, the 735buffer passed to 736.Xr read 2 737must itself be word aligned. 738The 739.Xr malloc 3 740function 741will always return an aligned buffer. 742.Sh FILTER MACHINE 743A filter program is an array of instructions, with all branches forwardly 744directed, terminated by a 745.Em return 746instruction. 747Each instruction performs some action on the pseudo-machine state, 748which consists of an accumulator, index register, scratch memory store, 749and implicit program counter. 750.Pp 751The following structure defines the instruction format: 752.Bd -literal 753struct bpf_insn { 754 u_short code; 755 u_char jt; 756 u_char jf; 757 u_long k; 758}; 759.Ed 760.Pp 761The 762.Li k 763field is used in different ways by different instructions, 764and the 765.Li jt 766and 767.Li jf 768fields are used as offsets 769by the branch instructions. 770The opcodes are encoded in a semi-hierarchical fashion. 771There are eight classes of instructions: 772.Dv BPF_LD , 773.Dv BPF_LDX , 774.Dv BPF_ST , 775.Dv BPF_STX , 776.Dv BPF_ALU , 777.Dv BPF_JMP , 778.Dv BPF_RET , 779and 780.Dv BPF_MISC . 781Various other mode and 782operator bits are or'd into the class to give the actual instructions. 783The classes and modes are defined in 784.In net/bpf.h . 785.Pp 786Below are the semantics for each defined 787.Nm 788instruction. 789We use the convention that A is the accumulator, X is the index register, 790P[] packet data, and M[] scratch memory store. 791P[i:n] gives the data at byte offset 792.Dq i 793in the packet, 794interpreted as a word (n=4), 795unsigned halfword (n=2), or unsigned byte (n=1). 796M[i] gives the i'th word in the scratch memory store, which is only 797addressed in word units. 798The memory store is indexed from 0 to 799.Dv BPF_MEMWORDS 800- 1. 801.Li k , 802.Li jt , 803and 804.Li jf 805are the corresponding fields in the 806instruction definition. 807.Dq len 808refers to the length of the packet. 809.Bl -tag -width BPF_STXx 810.It Dv BPF_LD 811These instructions copy a value into the accumulator. 812The type of the source operand is specified by an 813.Dq addressing mode 814and can be a constant 815.Pq Dv BPF_IMM , 816packet data at a fixed offset 817.Pq Dv BPF_ABS , 818packet data at a variable offset 819.Pq Dv BPF_IND , 820the packet length 821.Pq Dv BPF_LEN , 822or a word in the scratch memory store 823.Pq Dv BPF_MEM . 824For 825.Dv BPF_IND 826and 827.Dv BPF_ABS , 828the data size must be specified as a word 829.Pq Dv BPF_W , 830halfword 831.Pq Dv BPF_H , 832or byte 833.Pq Dv BPF_B . 834The semantics of all the recognized 835.Dv BPF_LD 836instructions follow. 837.Bd -literal 838BPF_LD+BPF_W+BPF_ABS A <- P[k:4] 839BPF_LD+BPF_H+BPF_ABS A <- P[k:2] 840BPF_LD+BPF_B+BPF_ABS A <- P[k:1] 841BPF_LD+BPF_W+BPF_IND A <- P[X+k:4] 842BPF_LD+BPF_H+BPF_IND A <- P[X+k:2] 843BPF_LD+BPF_B+BPF_IND A <- P[X+k:1] 844BPF_LD+BPF_W+BPF_LEN A <- len 845BPF_LD+BPF_IMM A <- k 846BPF_LD+BPF_MEM A <- M[k] 847.Ed 848.It Dv BPF_LDX 849These instructions load a value into the index register. 850Note that 851the addressing modes are more restrictive than those of the accumulator loads, 852but they include 853.Dv BPF_MSH , 854a hack for efficiently loading the IP header length. 855.Bd -literal 856BPF_LDX+BPF_W+BPF_IMM X <- k 857BPF_LDX+BPF_W+BPF_MEM X <- M[k] 858BPF_LDX+BPF_W+BPF_LEN X <- len 859BPF_LDX+BPF_B+BPF_MSH X <- 4*(P[k:1]&0xf) 860.Ed 861.It Dv BPF_ST 862This instruction stores the accumulator into the scratch memory. 863We do not need an addressing mode since there is only one possibility 864for the destination. 865.Bd -literal 866BPF_ST M[k] <- A 867.Ed 868.It Dv BPF_STX 869This instruction stores the index register in the scratch memory store. 870.Bd -literal 871BPF_STX M[k] <- X 872.Ed 873.It Dv BPF_ALU 874The alu instructions perform operations between the accumulator and 875index register or constant, and store the result back in the accumulator. 876For binary operations, a source mode is required 877.Dv ( BPF_K 878or 879.Dv BPF_X ) . 880.Bd -literal 881BPF_ALU+BPF_ADD+BPF_K A <- A + k 882BPF_ALU+BPF_SUB+BPF_K A <- A - k 883BPF_ALU+BPF_MUL+BPF_K A <- A * k 884BPF_ALU+BPF_DIV+BPF_K A <- A / k 885BPF_ALU+BPF_AND+BPF_K A <- A & k 886BPF_ALU+BPF_OR+BPF_K A <- A | k 887BPF_ALU+BPF_LSH+BPF_K A <- A << k 888BPF_ALU+BPF_RSH+BPF_K A <- A >> k 889BPF_ALU+BPF_ADD+BPF_X A <- A + X 890BPF_ALU+BPF_SUB+BPF_X A <- A - X 891BPF_ALU+BPF_MUL+BPF_X A <- A * X 892BPF_ALU+BPF_DIV+BPF_X A <- A / X 893BPF_ALU+BPF_AND+BPF_X A <- A & X 894BPF_ALU+BPF_OR+BPF_X A <- A | X 895BPF_ALU+BPF_LSH+BPF_X A <- A << X 896BPF_ALU+BPF_RSH+BPF_X A <- A >> X 897BPF_ALU+BPF_NEG A <- -A 898.Ed 899.It Dv BPF_JMP 900The jump instructions alter flow of control. 901Conditional jumps 902compare the accumulator against a constant 903.Pq Dv BPF_K 904or the index register 905.Pq Dv BPF_X . 906If the result is true (or non-zero), 907the true branch is taken, otherwise the false branch is taken. 908Jump offsets are encoded in 8 bits so the longest jump is 256 instructions. 909However, the jump always 910.Pq Dv BPF_JA 911opcode uses the 32 bit 912.Li k 913field as the offset, allowing arbitrarily distant destinations. 914All conditionals use unsigned comparison conventions. 915.Bd -literal 916BPF_JMP+BPF_JA pc += k 917BPF_JMP+BPF_JGT+BPF_K pc += (A > k) ? jt : jf 918BPF_JMP+BPF_JGE+BPF_K pc += (A >= k) ? jt : jf 919BPF_JMP+BPF_JEQ+BPF_K pc += (A == k) ? jt : jf 920BPF_JMP+BPF_JSET+BPF_K pc += (A & k) ? jt : jf 921BPF_JMP+BPF_JGT+BPF_X pc += (A > X) ? jt : jf 922BPF_JMP+BPF_JGE+BPF_X pc += (A >= X) ? jt : jf 923BPF_JMP+BPF_JEQ+BPF_X pc += (A == X) ? jt : jf 924BPF_JMP+BPF_JSET+BPF_X pc += (A & X) ? jt : jf 925.Ed 926.It Dv BPF_RET 927The return instructions terminate the filter program and specify the amount 928of packet to accept (i.e., they return the truncation amount). 929A return value of zero indicates that the packet should be ignored. 930The return value is either a constant 931.Pq Dv BPF_K 932or the accumulator 933.Pq Dv BPF_A . 934.Bd -literal 935BPF_RET+BPF_A accept A bytes 936BPF_RET+BPF_K accept k bytes 937.Ed 938.It Dv BPF_MISC 939The miscellaneous category was created for anything that does not 940fit into the above classes, and for any new instructions that might need to 941be added. 942Currently, these are the register transfer instructions 943that copy the index register to the accumulator or vice versa. 944.Bd -literal 945BPF_MISC+BPF_TAX X <- A 946BPF_MISC+BPF_TXA A <- X 947.Ed 948.El 949.Pp 950The 951.Nm 952interface provides the following macros to facilitate 953array initializers: 954.Fn BPF_STMT opcode operand 955and 956.Fn BPF_JUMP opcode operand true_offset false_offset . 957.Sh SYSCTL VARIABLES 958A set of 959.Xr sysctl 8 960variables controls the behaviour of the 961.Nm 962subsystem 963.Bl -tag -width indent 964.It Va net.bpf.optimize_writers: No 0 965Various programs use BPF to send (but not receive) raw packets 966(cdpd, lldpd, dhcpd, dhcp relays, etc. are good examples of such programs). 967They do not need incoming packets to be send to them. 968Turning this option on 969makes new BPF users to be attached to write-only interface list until program 970explicitly specifies read filter via 971.Fn pcap_set_filter . 972This removes any performance degradation for high-speed interfaces. 973.It Va net.bpf.stats: 974Binary interface for retrieving general statistics. 975.It Va net.bpf.zerocopy_enable: No 0 976Permits zero-copy to be used with net BPF readers. 977Use with caution. 978.It Va net.bpf.maxinsns: No 512 979Maximum number of instructions that BPF program can contain. 980Use 981.Xr tcpdump 1 982.Fl d 983option to determine approximate number of instruction for any filter. 984.It Va net.bpf.maxbufsize: No 524288 985Maximum buffer size to allocate for packets buffer. 986.It Va net.bpf.bufsize: No 4096 987Default buffer size to allocate for packets buffer. 988.El 989.Sh EXAMPLES 990The following filter is taken from the Reverse ARP Daemon. 991It accepts only Reverse ARP requests. 992.Bd -literal 993struct bpf_insn insns[] = { 994 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), 995 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), 996 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), 997 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1), 998 BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + 999 sizeof(struct ether_header)), 1000 BPF_STMT(BPF_RET+BPF_K, 0), 1001}; 1002.Ed 1003.Pp 1004This filter accepts only IP packets between host 128.3.112.15 and 1005128.3.112.35. 1006.Bd -literal 1007struct bpf_insn insns[] = { 1008 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), 1009 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8), 1010 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26), 1011 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), 1012 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), 1013 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), 1014 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), 1015 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), 1016 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), 1017 BPF_STMT(BPF_RET+BPF_K, (u_int)-1), 1018 BPF_STMT(BPF_RET+BPF_K, 0), 1019}; 1020.Ed 1021.Pp 1022Finally, this filter returns only TCP finger packets. 1023We must parse the IP header to reach the TCP header. 1024The 1025.Dv BPF_JSET 1026instruction 1027checks that the IP fragment offset is 0 so we are sure 1028that we have a TCP header. 1029.Bd -literal 1030struct bpf_insn insns[] = { 1031 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), 1032 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), 1033 BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), 1034 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), 1035 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), 1036 BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), 1037 BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), 1038 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), 1039 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), 1040 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), 1041 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), 1042 BPF_STMT(BPF_RET+BPF_K, (u_int)-1), 1043 BPF_STMT(BPF_RET+BPF_K, 0), 1044}; 1045.Ed 1046.Sh SEE ALSO 1047.Xr tcpdump 1 , 1048.Xr ioctl 2 , 1049.Xr kqueue 2 , 1050.Xr poll 2 , 1051.Xr select 2 , 1052.Xr byteorder 3 , 1053.Xr ng_bpf 4 , 1054.Xr bpf 9 1055.Rs 1056.%A McCanne, S. 1057.%A Jacobson V. 1058.%T "An efficient, extensible, and portable network monitor" 1059.Re 1060.Sh HISTORY 1061The Enet packet filter was created in 1980 by Mike Accetta and 1062Rick Rashid at Carnegie-Mellon University. 1063Jeffrey Mogul, at 1064Stanford, ported the code to 1065.Bx 1066and continued its development from 10671983 on. 1068Since then, it has evolved into the Ultrix Packet Filter at 1069.Tn DEC , 1070a 1071.Tn STREAMS 1072.Tn NIT 1073module under 1074.Tn SunOS 4.1 , 1075and 1076.Tn BPF . 1077.Sh AUTHORS 1078.An -nosplit 1079.An Steven McCanne , 1080of Lawrence Berkeley Laboratory, implemented BPF in 1081Summer 1990. 1082Much of the design is due to 1083.An Van Jacobson . 1084.Pp 1085Support for zero-copy buffers was added by 1086.An Robert N. M. Watson 1087under contract to Seccuris Inc. 1088.Sh BUGS 1089The read buffer must be of a fixed size (returned by the 1090.Dv BIOCGBLEN 1091ioctl). 1092.Pp 1093A file that does not request promiscuous mode may receive promiscuously 1094received packets as a side effect of another file requesting this 1095mode on the same hardware interface. 1096This could be fixed in the kernel with additional processing overhead. 1097However, we favor the model where 1098all files must assume that the interface is promiscuous, and if 1099so desired, must utilize a filter to reject foreign packets. 1100.Pp 1101Data link protocols with variable length headers are not currently supported. 1102.Pp 1103The 1104.Dv SEESENT , 1105.Dv DIRECTION , 1106and 1107.Dv FEEDBACK 1108settings have been observed to work incorrectly on some interface 1109types, including those with hardware loopback rather than software loopback, 1110and point-to-point interfaces. 1111They appear to function correctly on a 1112broad range of Ethernet-style interfaces. 1113