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. Otherwise, 701.Vt bpf_xhdr 702is used. However, 703.Vt bpf_hdr 704may be deprecated in the near future. 705Suitable precautions 706must be taken when accessing the link layer protocol fields on alignment 707restricted machines. 708(This is not a problem on an Ethernet, since 709the type field is a short falling on an even offset, 710and the addresses are probably accessed in a bytewise fashion). 711.Pp 712Additionally, individual packets are padded so that each starts 713on a word boundary. 714This requires that an application 715has some knowledge of how to get from packet to packet. 716The macro 717.Dv BPF_WORDALIGN 718is defined in 719.In net/bpf.h 720to facilitate 721this process. 722It rounds up its argument to the nearest word aligned value (where a word is 723.Dv BPF_ALIGNMENT 724bytes wide). 725.Pp 726For example, if 727.Sq Li p 728points to the start of a packet, this expression 729will advance it to the next packet: 730.Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) 731.Pp 732For the alignment mechanisms to work properly, the 733buffer passed to 734.Xr read 2 735must itself be word aligned. 736The 737.Xr malloc 3 738function 739will always return an aligned buffer. 740.Sh FILTER MACHINE 741A filter program is an array of instructions, with all branches forwardly 742directed, terminated by a 743.Em return 744instruction. 745Each instruction performs some action on the pseudo-machine state, 746which consists of an accumulator, index register, scratch memory store, 747and implicit program counter. 748.Pp 749The following structure defines the instruction format: 750.Bd -literal 751struct bpf_insn { 752 u_short code; 753 u_char jt; 754 u_char jf; 755 u_long k; 756}; 757.Ed 758.Pp 759The 760.Li k 761field is used in different ways by different instructions, 762and the 763.Li jt 764and 765.Li jf 766fields are used as offsets 767by the branch instructions. 768The opcodes are encoded in a semi-hierarchical fashion. 769There are eight classes of instructions: 770.Dv BPF_LD , 771.Dv BPF_LDX , 772.Dv BPF_ST , 773.Dv BPF_STX , 774.Dv BPF_ALU , 775.Dv BPF_JMP , 776.Dv BPF_RET , 777and 778.Dv BPF_MISC . 779Various other mode and 780operator bits are or'd into the class to give the actual instructions. 781The classes and modes are defined in 782.In net/bpf.h . 783.Pp 784Below are the semantics for each defined 785.Nm 786instruction. 787We use the convention that A is the accumulator, X is the index register, 788P[] packet data, and M[] scratch memory store. 789P[i:n] gives the data at byte offset 790.Dq i 791in the packet, 792interpreted as a word (n=4), 793unsigned halfword (n=2), or unsigned byte (n=1). 794M[i] gives the i'th word in the scratch memory store, which is only 795addressed in word units. 796The memory store is indexed from 0 to 797.Dv BPF_MEMWORDS 798- 1. 799.Li k , 800.Li jt , 801and 802.Li jf 803are the corresponding fields in the 804instruction definition. 805.Dq len 806refers to the length of the packet. 807.Pp 808.Bl -tag -width BPF_STXx 809.It Dv BPF_LD 810These instructions copy a value into the accumulator. 811The type of the source operand is specified by an 812.Dq addressing mode 813and can be a constant 814.Pq Dv BPF_IMM , 815packet data at a fixed offset 816.Pq Dv BPF_ABS , 817packet data at a variable offset 818.Pq Dv BPF_IND , 819the packet length 820.Pq Dv BPF_LEN , 821or a word in the scratch memory store 822.Pq Dv BPF_MEM . 823For 824.Dv BPF_IND 825and 826.Dv BPF_ABS , 827the data size must be specified as a word 828.Pq Dv BPF_W , 829halfword 830.Pq Dv BPF_H , 831or byte 832.Pq Dv BPF_B . 833The semantics of all the recognized 834.Dv BPF_LD 835instructions follow. 836.Pp 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.Pp 856.Bd -literal 857BPF_LDX+BPF_W+BPF_IMM X <- k 858BPF_LDX+BPF_W+BPF_MEM X <- M[k] 859BPF_LDX+BPF_W+BPF_LEN X <- len 860BPF_LDX+BPF_B+BPF_MSH X <- 4*(P[k:1]&0xf) 861.Ed 862.It Dv BPF_ST 863This instruction stores the accumulator into the scratch memory. 864We do not need an addressing mode since there is only one possibility 865for the destination. 866.Pp 867.Bd -literal 868BPF_ST M[k] <- A 869.Ed 870.It Dv BPF_STX 871This instruction stores the index register in the scratch memory store. 872.Pp 873.Bd -literal 874BPF_STX M[k] <- X 875.Ed 876.It Dv BPF_ALU 877The alu instructions perform operations between the accumulator and 878index register or constant, and store the result back in the accumulator. 879For binary operations, a source mode is required 880.Dv ( BPF_K 881or 882.Dv BPF_X ) . 883.Pp 884.Bd -literal 885BPF_ALU+BPF_ADD+BPF_K A <- A + k 886BPF_ALU+BPF_SUB+BPF_K A <- A - k 887BPF_ALU+BPF_MUL+BPF_K A <- A * k 888BPF_ALU+BPF_DIV+BPF_K A <- A / k 889BPF_ALU+BPF_AND+BPF_K A <- A & k 890BPF_ALU+BPF_OR+BPF_K A <- A | k 891BPF_ALU+BPF_LSH+BPF_K A <- A << k 892BPF_ALU+BPF_RSH+BPF_K A <- A >> k 893BPF_ALU+BPF_ADD+BPF_X A <- A + X 894BPF_ALU+BPF_SUB+BPF_X A <- A - X 895BPF_ALU+BPF_MUL+BPF_X A <- A * X 896BPF_ALU+BPF_DIV+BPF_X A <- A / X 897BPF_ALU+BPF_AND+BPF_X A <- A & X 898BPF_ALU+BPF_OR+BPF_X A <- A | X 899BPF_ALU+BPF_LSH+BPF_X A <- A << X 900BPF_ALU+BPF_RSH+BPF_X A <- A >> X 901BPF_ALU+BPF_NEG A <- -A 902.Ed 903.It Dv BPF_JMP 904The jump instructions alter flow of control. 905Conditional jumps 906compare the accumulator against a constant 907.Pq Dv BPF_K 908or the index register 909.Pq Dv BPF_X . 910If the result is true (or non-zero), 911the true branch is taken, otherwise the false branch is taken. 912Jump offsets are encoded in 8 bits so the longest jump is 256 instructions. 913However, the jump always 914.Pq Dv BPF_JA 915opcode uses the 32 bit 916.Li k 917field as the offset, allowing arbitrarily distant destinations. 918All conditionals use unsigned comparison conventions. 919.Pp 920.Bd -literal 921BPF_JMP+BPF_JA pc += k 922BPF_JMP+BPF_JGT+BPF_K pc += (A > k) ? jt : jf 923BPF_JMP+BPF_JGE+BPF_K pc += (A >= k) ? jt : jf 924BPF_JMP+BPF_JEQ+BPF_K pc += (A == k) ? jt : jf 925BPF_JMP+BPF_JSET+BPF_K pc += (A & k) ? jt : jf 926BPF_JMP+BPF_JGT+BPF_X pc += (A > X) ? jt : jf 927BPF_JMP+BPF_JGE+BPF_X pc += (A >= X) ? jt : jf 928BPF_JMP+BPF_JEQ+BPF_X pc += (A == X) ? jt : jf 929BPF_JMP+BPF_JSET+BPF_X pc += (A & X) ? jt : jf 930.Ed 931.It Dv BPF_RET 932The return instructions terminate the filter program and specify the amount 933of packet to accept (i.e., they return the truncation amount). 934A return value of zero indicates that the packet should be ignored. 935The return value is either a constant 936.Pq Dv BPF_K 937or the accumulator 938.Pq Dv BPF_A . 939.Pp 940.Bd -literal 941BPF_RET+BPF_A accept A bytes 942BPF_RET+BPF_K accept k bytes 943.Ed 944.It Dv BPF_MISC 945The miscellaneous category was created for anything that does not 946fit into the above classes, and for any new instructions that might need to 947be added. 948Currently, these are the register transfer instructions 949that copy the index register to the accumulator or vice versa. 950.Pp 951.Bd -literal 952BPF_MISC+BPF_TAX X <- A 953BPF_MISC+BPF_TXA A <- X 954.Ed 955.El 956.Pp 957The 958.Nm 959interface provides the following macros to facilitate 960array initializers: 961.Fn BPF_STMT opcode operand 962and 963.Fn BPF_JUMP opcode operand true_offset false_offset . 964.Sh FILES 965.Bl -tag -compact -width /dev/bpf 966.It Pa /dev/bpf 967the packet filter device 968.El 969.Sh EXAMPLES 970The following filter is taken from the Reverse ARP Daemon. 971It accepts only Reverse ARP requests. 972.Bd -literal 973struct bpf_insn insns[] = { 974 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), 975 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), 976 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), 977 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1), 978 BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + 979 sizeof(struct ether_header)), 980 BPF_STMT(BPF_RET+BPF_K, 0), 981}; 982.Ed 983.Pp 984This filter accepts only IP packets between host 128.3.112.15 and 985128.3.112.35. 986.Bd -literal 987struct bpf_insn insns[] = { 988 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), 989 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8), 990 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26), 991 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), 992 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), 993 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), 994 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), 995 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), 996 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), 997 BPF_STMT(BPF_RET+BPF_K, (u_int)-1), 998 BPF_STMT(BPF_RET+BPF_K, 0), 999}; 1000.Ed 1001.Pp 1002Finally, this filter returns only TCP finger packets. 1003We must parse the IP header to reach the TCP header. 1004The 1005.Dv BPF_JSET 1006instruction 1007checks that the IP fragment offset is 0 so we are sure 1008that we have a TCP header. 1009.Bd -literal 1010struct bpf_insn insns[] = { 1011 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), 1012 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), 1013 BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), 1014 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), 1015 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), 1016 BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), 1017 BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), 1018 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), 1019 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), 1020 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), 1021 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), 1022 BPF_STMT(BPF_RET+BPF_K, (u_int)-1), 1023 BPF_STMT(BPF_RET+BPF_K, 0), 1024}; 1025.Ed 1026.Sh SEE ALSO 1027.Xr tcpdump 1 , 1028.Xr ioctl 2 , 1029.Xr kqueue 2 , 1030.Xr poll 2 , 1031.Xr select 2 , 1032.Xr byteorder 3 , 1033.Xr ng_bpf 4 , 1034.Xr bpf 9 1035.Rs 1036.%A McCanne, S. 1037.%A Jacobson V. 1038.%T "An efficient, extensible, and portable network monitor" 1039.Re 1040.Sh HISTORY 1041The Enet packet filter was created in 1980 by Mike Accetta and 1042Rick Rashid at Carnegie-Mellon University. 1043Jeffrey Mogul, at 1044Stanford, ported the code to 1045.Bx 1046and continued its development from 10471983 on. 1048Since then, it has evolved into the Ultrix Packet Filter at 1049.Tn DEC , 1050a 1051.Tn STREAMS 1052.Tn NIT 1053module under 1054.Tn SunOS 4.1 , 1055and 1056.Tn BPF . 1057.Sh AUTHORS 1058.An -nosplit 1059.An Steven McCanne , 1060of Lawrence Berkeley Laboratory, implemented BPF in 1061Summer 1990. 1062Much of the design is due to 1063.An Van Jacobson . 1064.Pp 1065Support for zero-copy buffers was added by 1066.An Robert N. M. Watson 1067under contract to Seccuris Inc. 1068.Sh BUGS 1069The read buffer must be of a fixed size (returned by the 1070.Dv BIOCGBLEN 1071ioctl). 1072.Pp 1073A file that does not request promiscuous mode may receive promiscuously 1074received packets as a side effect of another file requesting this 1075mode on the same hardware interface. 1076This could be fixed in the kernel with additional processing overhead. 1077However, we favor the model where 1078all files must assume that the interface is promiscuous, and if 1079so desired, must utilize a filter to reject foreign packets. 1080.Pp 1081Data link protocols with variable length headers are not currently supported. 1082.Pp 1083The 1084.Dv SEESENT , 1085.Dv DIRECTION , 1086and 1087.Dv FEEDBACK 1088settings have been observed to work incorrectly on some interface 1089types, including those with hardware loopback rather than software loopback, 1090and point-to-point interfaces. 1091They appear to function correctly on a 1092broad range of Ethernet-style interfaces. 1093