1.\" $OpenBSD: bpf.4,v 1.47 2024/08/15 12:20:20 dlg Exp $ 2.\" $NetBSD: bpf.4,v 1.7 1995/09/27 18:31:50 thorpej Exp $ 3.\" 4.\" Copyright (c) 1990 The Regents of the University of California. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that: (1) source code distributions 9.\" retain the above copyright notice and this paragraph in its entirety, (2) 10.\" distributions including binary code include the above copyright notice and 11.\" this paragraph in its entirety in the documentation or other materials 12.\" provided with the distribution, and (3) all advertising materials mentioning 13.\" features or use of this software display the following acknowledgement: 14.\" ``This product includes software developed by the University of California, 15.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of 16.\" the University nor the names of its contributors may be used to endorse 17.\" or promote products derived from this software without specific prior 18.\" written permission. 19.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED 20.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF 21.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 22.\" 23.\" This document is derived in part from the enet man page (enet.4) 24.\" distributed with 4.3BSD Unix. 25.\" 26.Dd $Mdocdate: August 15 2024 $ 27.Dt BPF 4 28.Os 29.Sh NAME 30.Nm bpf 31.Nd Berkeley Packet Filter 32.Sh SYNOPSIS 33.Cd "pseudo-device bpfilter" 34.Sh DESCRIPTION 35The Berkeley Packet Filter provides a raw interface to data link layers in 36a protocol-independent fashion. 37All packets on the network, even those destined for other hosts, are 38accessible through this mechanism. 39.Pp 40The packet filter appears as a character special device, 41.Pa /dev/bpf . 42After opening the device, the file descriptor must be bound to a specific 43network interface with the 44.Dv BIOCSETIF 45.Xr ioctl 2 . 46A given interface can be shared between multiple listeners, and the filter 47underlying each descriptor will see an identical packet stream. 48.Pp 49Associated with each open instance of a 50.Nm 51file is a user-settable 52packet filter. 53Whenever a packet is received by an interface, all file descriptors 54listening on that interface apply their filter. 55Each descriptor that accepts the packet receives its own copy. 56.Pp 57Reads from these files return the next group of packets that have matched 58the filter. 59To improve performance, the buffer passed to read must be the same size as 60the buffers used internally by 61.Nm bpf . 62This size is returned by the 63.Dv BIOCGBLEN 64.Xr ioctl 2 65and can be set with 66.Dv BIOCSBLEN . 67Note that an individual packet larger than this size is necessarily truncated. 68.Pp 69A packet can be sent out on the network by writing to a 70.Nm 71file descriptor. 72Each descriptor can also have a user-settable filter 73for controlling the writes. 74Only packets matching the filter are sent out of the interface. 75The writes are unbuffered, meaning only one packet can be processed per write. 76.Pp 77Once a descriptor is configured, further changes to the configuration 78can be prevented using the 79.Dv BIOCLOCK 80.Xr ioctl 2 . 81.Sh IOCTL INTERFACE 82The 83.Xr ioctl 2 84command codes below are defined in 85.In net/bpf.h . 86All commands require these includes: 87.Pp 88.nr nS 1 89.In sys/types.h 90.In sys/time.h 91.In sys/ioctl.h 92.In net/bpf.h 93.nr nS 0 94.Pp 95Additionally, 96.Dv BIOCGETIF 97and 98.Dv BIOCSETIF 99require 100.In sys/socket.h 101and 102.In net/if.h . 103.Pp 104The (third) argument to the 105.Xr ioctl 2 106call should be a pointer to the type indicated. 107.Pp 108.Bl -tag -width Ds -compact 109.It Dv BIOCGBLEN Fa "u_int *" 110Returns the required buffer length for reads on 111.Nm 112files. 113.Pp 114.It Dv BIOCSBLEN Fa "u_int *" 115Sets the buffer length for reads on 116.Nm 117files. 118The buffer must be set before the file is attached to an interface with 119.Dv BIOCSETIF . 120If the requested buffer size cannot be accommodated, the closest allowable 121size will be set and returned in the argument. 122A read call will result in 123.Er EINVAL 124if it is passed a buffer that is not this size. 125.Pp 126.It Dv BIOCGDLT Fa "u_int *" 127Returns the type of the data link layer underlying the attached interface. 128.Er EINVAL 129is returned if no interface has been specified. 130The device types, prefixed with 131.Dq DLT_ , 132are defined in 133.In net/bpf.h . 134.Pp 135.It Dv BIOCGDLTLIST Fa "struct bpf_dltlist *" 136Returns an array of the available types of the data link layer 137underlying the attached interface: 138.Bd -literal -offset indent 139struct bpf_dltlist { 140 u_int bfl_len; 141 u_int *bfl_list; 142}; 143.Ed 144.Pp 145The available types are returned in the array pointed to by the 146.Va bfl_list 147field while their length in 148.Vt u_int 149is supplied to the 150.Va bfl_len 151field. 152.Er ENOMEM 153is returned if there is not enough buffer space and 154.Er EFAULT 155is returned if a bad address is encountered. 156The 157.Va bfl_len 158field is modified on return to indicate the actual length in 159.Vt u_int 160of the array returned. 161If 162.Va bfl_list 163is 164.Dv NULL , 165the 166.Va bfl_len 167field is set to indicate the required length of the array in 168.Vt u_int . 169.Pp 170.It Dv BIOCSDLT Fa "u_int *" 171Changes the type of the data link layer underlying the attached interface. 172.Er EINVAL 173is returned if no interface has been specified or the specified 174type is not available for the interface. 175.Pp 176.It Dv BIOCPROMISC 177Forces the interface into promiscuous mode. 178All packets, not just those destined for the local host, are processed. 179Since more than one file can be listening on a given interface, a listener 180that opened its interface non-promiscuously may receive packets promiscuously. 181This problem can be remedied with an appropriate filter. 182.Pp 183The interface remains in promiscuous mode until all files listening 184promiscuously are closed. 185.Pp 186.It Dv BIOCFLUSH 187Flushes the buffer of incoming packets and resets the statistics that are 188returned by 189.Dv BIOCGSTATS . 190.Pp 191.It Dv BIOCLOCK 192This ioctl is designed to prevent the security issues associated 193with an open 194.Nm 195descriptor in unprivileged programs. 196Even with dropped privileges, an open 197.Nm 198descriptor can be abused by a rogue program to listen on any interface 199on the system, send packets on these interfaces if the descriptor was 200opened read-write and send signals to arbitrary processes using the 201signaling mechanism of 202.Nm bpf . 203By allowing only 204.Dq known safe 205ioctls, the 206.Dv BIOCLOCK 207ioctl prevents this abuse. 208The allowable ioctls are 209.Dv BIOCFLUSH , 210.Dv BIOCGBLEN , 211.Dv BIOCGDIRFILT , 212.Dv BIOCGDLT , 213.Dv BIOCGDIRFILT , 214.Dv BIOCGDLTLIST , 215.Dv BIOCGETIF , 216.Dv BIOCGHDRCMPLT , 217.Dv BIOCGRSIG , 218.Dv BIOCGRTIMEOUT , 219.Dv BIOCGSTATS , 220.Dv BIOCIMMEDIATE , 221.Dv BIOCLOCK , 222.Dv BIOCSRTIMEOUT , 223.Dv BIOCSWTIMEOUT , 224.Dv BIOCDWTIMEOUT , 225.Dv BIOCVERSION , 226.Dv TIOCGPGRP , 227and 228.Dv FIONREAD . 229Use of any other ioctl is denied with error 230.Er EPERM . 231Once a descriptor is locked, it is not possible to unlock it. 232A process with root privileges is not affected by the lock. 233.Pp 234A privileged program can open a 235.Nm 236device, drop privileges, set the interface, filters and modes on the 237descriptor, and lock it. 238Once the descriptor is locked, the system is safe 239from further abuse through the descriptor. 240Locking a descriptor does not prevent writes. 241If the application does not need to send packets through 242.Nm bpf , 243it can open the device read-only to prevent writing. 244If sending packets is necessary, a write-filter can be set before locking the 245descriptor to prevent arbitrary packets from being sent out. 246.Pp 247.It Dv BIOCGETIF Fa "struct ifreq *" 248Returns the name of the hardware interface that the file is listening on. 249The name is returned in the 250.Fa ifr_name 251field of the 252.Vt struct ifreq . 253All other fields are undefined. 254.Pp 255.It Dv BIOCSETIF Fa "struct ifreq *" 256Sets the hardware interface associated with the file. 257This command must be performed before any packets can be read. 258The device is indicated by name using the 259.Fa ifr_name 260field of the 261.Vt struct ifreq . 262Additionally, performs the actions of 263.Dv BIOCFLUSH . 264.Pp 265.It Dv BIOCSRTIMEOUT Fa "struct timeval *" 266.It Dv BIOCGRTIMEOUT Fa "struct timeval *" 267Sets or gets the read timeout parameter. 268The 269.Ar timeval 270specifies the length of time to wait before timing out on a read request. 271This parameter is initialized to zero by 272.Xr open 2 , 273indicating no timeout. 274.Pp 275.It Dv BIOCGSTATS Fa "struct bpf_stat *" 276Returns the following structure of packet statistics: 277.Bd -literal -offset indent 278struct bpf_stat { 279 u_int bs_recv; 280 u_int bs_drop; 281}; 282.Ed 283.Pp 284The fields are: 285.Bl -tag -width bs_recv 286.It Fa bs_recv 287Number of packets received by the descriptor since opened or reset (including 288any buffered since the last read call). 289.It Fa bs_drop 290Number of packets which were accepted by the filter but dropped by the kernel 291because of buffer overflows (i.e., the application's reads aren't keeping up 292with the packet traffic). 293.El 294.Pp 295.It Dv BIOCIMMEDIATE Fa "u_int *" 296Enables or disables 297.Dq immediate mode , 298based on the truth value of the argument. 299When immediate mode is enabled, reads return immediately upon packet reception. 300Otherwise, a read will block until either the kernel buffer becomes full or a 301timeout occurs. 302This is useful for programs like 303.Xr rarpd 8 , 304which must respond to messages in real time. 305The default for a new file is off. 306.Pp 307.It Dv BIOCSWTIMEOUT Fa "struct timeval *" 308.It Dv BIOCGWTIMEOUT Fa "struct timeval *" 309.It Dv BIOCDWTIMEOUT 310Sets, gets, or deletes (resets) the wait timeout parameter. 311The 312.Ar timeval 313specifies the length of time to wait between receiving a packet and 314the kernel buffer becoming readable. 315By default, or when reset, the wait timeout is infinite, meaning 316the age of packets in the kernel buffer does not make the buffer 317readable. 318The maximum wait time that can be set is 5 minutes (300 seconds). 319.Pp 320.It Dv BIOCSETF Fa "struct bpf_program *" 321.It Dv BIOCSETFNR Fa "struct bpf_program *" 322Sets the filter program used by the kernel to discard uninteresting packets. 323An array of instructions and its length are passed in using the following 324structure: 325.Bd -literal -offset indent 326struct bpf_program { 327 u_int bf_len; 328 struct bpf_insn *bf_insns; 329}; 330.Ed 331.Pp 332The filter program is pointed to by the 333.Fa bf_insns 334field, while its length in units of 335.Vt struct bpf_insn 336is given by the 337.Fa bf_len 338field. 339If 340.Dv BIOCSETF 341is used, the actions of 342.Dv BIOCFLUSH 343are also performed. 344.Pp 345See section 346.Sx FILTER MACHINE 347for an explanation of the filter language. 348.Pp 349.It Dv BIOCSETWF Fa "struct bpf_program *" 350Sets the filter program used by the kernel to filter the packets 351written to the descriptor before the packets are sent out on the 352network. 353See 354.Dv BIOCSETF 355for a description of the filter program. 356.Pp 357Note that the filter operates on the packet data written to the descriptor. 358If the 359.Dq header complete 360flag is not set, the kernel sets the link-layer source address 361of the packet after filtering. 362.Pp 363.It Dv BIOCVERSION Fa "struct bpf_version *" 364Returns the major and minor version numbers of the filter language currently 365recognized by the kernel. 366Before installing a filter, applications must check that the current version 367is compatible with the running kernel. 368Version numbers are compatible if the major numbers match and the application 369minor is less than or equal to the kernel minor. 370The kernel version number is returned in the following structure: 371.Bd -literal -offset indent 372struct bpf_version { 373 u_short bv_major; 374 u_short bv_minor; 375}; 376.Ed 377.Pp 378The current version numbers are given by 379.Dv BPF_MAJOR_VERSION 380and 381.Dv BPF_MINOR_VERSION 382from 383.In net/bpf.h . 384An incompatible filter may result in undefined behavior (most likely, an 385error returned by 386.Xr ioctl 2 387or haphazard packet matching). 388.Pp 389.It Dv BIOCSRSIG Fa "u_int *" 390.It Dv BIOCGRSIG Fa "u_int *" 391Sets or gets the receive signal. 392This signal will be sent to the process or process group specified by 393.Dv FIOSETOWN . 394It defaults to 395.Dv SIGIO . 396.Pp 397.It Dv BIOCSHDRCMPLT Fa "u_int *" 398.It Dv BIOCGHDRCMPLT Fa "u_int *" 399Sets or gets the status of the 400.Dq header complete 401flag. 402Set to zero if the link level source address should be filled in 403automatically by the interface output routine. 404Set to one if the link level source address will be written, 405as provided, to the wire. 406This flag is initialized to zero by default. 407.Pp 408.It Dv BIOCSFILDROP Fa "u_int *" 409.It Dv BIOCGFILDROP Fa "u_int *" 410Sets or gets the 411.Dq filter drop 412action. 413The supported actions for packets matching the filter are: 414.Pp 415.Bl -tag -width "BPF_FILDROP_CAPTURE" -compact 416.It Dv BPF_FILDROP_PASS 417Accept and capture 418.It Dv BPF_FILDROP_CAPTURE 419Drop and capture 420.It Dv BPF_FILDROP_DROP 421Drop and do not capture 422.El 423.Pp 424Packets matching any filter configured to drop packets will be 425reported to the associated interface so that they can be dropped. 426The default action is 427.Dv BPF_FILDROP_PASS . 428.Pp 429.It Dv BIOCSDIRFILT Fa "u_int *" 430.It Dv BIOCGDIRFILT Fa "u_int *" 431Sets or gets the status of the 432.Dq direction filter 433flag. 434If non-zero, packets matching the specified direction (either 435.Dv BPF_DIRECTION_IN 436or 437.Dv BPF_DIRECTION_OUT ) 438will be ignored. 439.El 440.Ss Standard ioctls 441.Nm 442now supports several standard ioctls which allow the user to do asynchronous 443and/or non-blocking I/O to an open 444.Nm 445file descriptor. 446.Pp 447.Bl -tag -width Ds -compact 448.It Dv FIONREAD Fa "int *" 449Returns the number of bytes that are immediately available for reading. 450.Pp 451.It Dv FIONBIO Fa "int *" 452Sets or clears non-blocking I/O. 453If the argument is non-zero, enable non-blocking I/O. 454If the argument is zero, disable non-blocking I/O. 455If non-blocking I/O is enabled, the return value of a read while no data 456is available will be 0. 457The non-blocking read behavior is different from performing non-blocking 458reads on other file descriptors, which will return \-1 and set 459.Va errno 460to 461.Er EAGAIN 462if no data is available. 463Note: setting this overrides the timeout set by 464.Dv BIOCSRTIMEOUT . 465.Pp 466.It Dv FIOASYNC Fa "int *" 467Enables or disables asynchronous I/O. 468When enabled (argument is non-zero), the process or process group specified 469by 470.Dv FIOSETOWN 471will start receiving 472.Dv SIGIO 473signals when packets arrive. 474Note that you must perform an 475.Dv FIOSETOWN 476command in order for this to take effect, as the system will not do it by 477default. 478The signal may be changed via 479.Dv BIOCSRSIG . 480.Pp 481.It Dv FIOSETOWN Fa "int *" 482.It Dv FIOGETOWN Fa "int *" 483Sets or gets the process or process group (if negative) that should receive 484.Dv SIGIO 485when packets are available. 486The signal may be changed using 487.Dv BIOCSRSIG 488(see above). 489.El 490.Ss BPF header 491The following structure is prepended to each packet returned by 492.Xr read 2 : 493.Bd -literal -offset indent 494struct bpf_hdr { 495 struct bpf_timeval bh_tstamp; 496 u_int32_t bh_caplen; 497 u_int32_t bh_datalen; 498 u_int16_t bh_hdrlen; 499}; 500.Ed 501.Pp 502The fields, stored in host order, are as follows: 503.Bl -tag -width Ds 504.It Fa bh_tstamp 505Time at which the packet was processed by the packet filter. 506.It Fa bh_caplen 507Length of the captured portion of the packet. 508This is the minimum of the truncation amount specified by the filter and the 509length of the packet. 510.It Fa bh_datalen 511Length of the packet off the wire. 512This value is independent of the truncation amount specified by the filter. 513.It Fa bh_hdrlen 514Length of the BPF header, which may not be equal to 515.Li sizeof(struct bpf_hdr) . 516.El 517.Pp 518The 519.Fa bh_hdrlen 520field exists to account for padding between the header and the link level 521protocol. 522The purpose here is to guarantee proper alignment of the packet data 523structures, which is required on alignment-sensitive architectures and 524improves performance on many other architectures. 525The packet filter ensures that the 526.Fa bpf_hdr 527and the network layer header will be word aligned. 528Suitable precautions must be taken when accessing the link layer protocol 529fields on alignment restricted machines. 530(This isn't a problem on an Ethernet, since the type field is a 531.Vt short 532falling on an even offset, and the addresses are probably accessed in a 533bytewise fashion). 534.Pp 535Additionally, individual packets are padded so that each starts on a 536word boundary. 537This requires that an application has some knowledge of how to get from packet 538to packet. 539The macro 540.Dv BPF_WORDALIGN 541is defined in 542.In net/bpf.h 543to facilitate this process. 544It rounds up its argument to the nearest word aligned value (where a word is 545.Dv BPF_ALIGNMENT 546bytes wide). 547For example, if 548.Va p 549points to the start of a packet, this expression will advance it to the 550next packet: 551.Pp 552.Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen); 553.Pp 554For the alignment mechanisms to work properly, the buffer passed to 555.Xr read 2 556must itself be word aligned. 557.Xr malloc 3 558will always return an aligned buffer. 559.Ss Filter machine 560A filter program is an array of instructions with all branches forwardly 561directed, terminated by a 562.Dq return 563instruction. 564Each instruction performs some action on the pseudo-machine state, which 565consists of an accumulator, index register, scratch memory store, and 566implicit program counter. 567.Pp 568The following structure defines the instruction format: 569.Bd -literal -offset indent 570struct bpf_insn { 571 u_int16_t code; 572 u_char jt; 573 u_char jf; 574 u_int32_t k; 575}; 576.Ed 577.Pp 578The 579.Fa k 580field is used in different ways by different instructions, and the 581.Fa jt 582and 583.Fa jf 584fields are used as offsets by the branch instructions. 585The opcodes are encoded in a semi-hierarchical fashion. 586There are eight classes of instructions: 587.Dv BPF_LD , 588.Dv BPF_LDX , 589.Dv BPF_ST , 590.Dv BPF_STX , 591.Dv BPF_ALU , 592.Dv BPF_JMP , 593.Dv BPF_RET , 594and 595.Dv BPF_MISC . 596Various other mode and operator bits are logically OR'd into the class to 597give the actual instructions. 598The classes and modes are defined in 599.In net/bpf.h . 600Below are the semantics for each defined 601.Nm 602instruction. 603We use the convention that A is the accumulator, X is the index register, 604P[] packet data, and M[] scratch memory store. 605P[i:n] gives the data at byte offset 606.Dq i 607in the packet, interpreted as a word (n=4), unsigned halfword (n=2), or 608unsigned byte (n=1). 609M[i] gives the i'th word in the scratch memory store, which is only addressed 610in word units. 611The memory store is indexed from 0 to 612.Dv BPF_MEMWORDS Ns \-1 . 613.Fa k , 614.Fa jt , 615and 616.Fa jf 617are the corresponding fields in the instruction definition. 618.Dq len 619refers to the length of the packet. 620.Bl -tag -width Ds 621.It Dv BPF_LD 622These instructions copy a value into the accumulator. 623The type of the source operand is specified by an 624.Dq addressing mode 625and can be a constant 626.Pf ( Dv BPF_IMM ) , 627packet data at a fixed offset 628.Pf ( Dv BPF_ABS ) , 629packet data at a variable offset 630.Pf ( Dv BPF_IND ) , 631the packet length 632.Pf ( Dv BPF_LEN ) , 633a random number 634.Pf ( Dv BPF_RND ) , 635or a word in the scratch memory store 636.Pf ( Dv BPF_MEM ) . 637For 638.Dv BPF_IND 639and 640.Dv BPF_ABS , 641the data size must be specified as a word 642.Pf ( Dv BPF_W ) , 643halfword 644.Pf ( Dv BPF_H ) , 645or byte 646.Pf ( Dv BPF_B ) . 647The semantics of all recognized 648.Dv BPF_LD 649instructions follow. 650.Pp 651.Bl -tag -width 32n -compact 652.Sm off 653.It Xo Dv BPF_LD No + Dv BPF_W No + 654.Dv BPF_ABS 655.Xc 656.Sm on 657A <- P[k:4] 658.Sm off 659.It Xo Dv BPF_LD No + Dv BPF_H No + 660.Dv BPF_ABS 661.Xc 662.Sm on 663A <- P[k:2] 664.Sm off 665.It Xo Dv BPF_LD No + Dv BPF_B No + 666.Dv BPF_ABS 667.Xc 668.Sm on 669A <- P[k:1] 670.Sm off 671.It Xo Dv BPF_LD No + Dv BPF_W No + 672.Dv BPF_IND 673.Xc 674.Sm on 675A <- P[X+k:4] 676.Sm off 677.It Xo Dv BPF_LD No + Dv BPF_H No + 678.Dv BPF_IND 679.Xc 680.Sm on 681A <- P[X+k:2] 682.Sm off 683.It Xo Dv BPF_LD No + Dv BPF_B No + 684.Dv BPF_IND 685.Xc 686.Sm on 687A <- P[X+k:1] 688.Sm off 689.It Xo Dv BPF_LD No + Dv BPF_W No + 690.Dv BPF_LEN 691.Xc 692.Sm on 693A <- len 694.Sm off 695.It Xo Dv BPF_LD No + Dv BPF_W No + 696.Dv BPF_RND 697.Xc 698.Sm on 699A <- arc4random() 700.Sm off 701.It Dv BPF_LD No + Dv BPF_IMM 702.Sm on 703A <- k 704.Sm off 705.It Dv BPF_LD No + Dv BPF_MEM 706.Sm on 707A <- M[k] 708.El 709.It Dv BPF_LDX 710These instructions load a value into the index register. 711Note that the addressing modes are more restricted than those of the 712accumulator loads, but they include 713.Dv BPF_MSH , 714a hack for efficiently loading the IP header length. 715.Pp 716.Bl -tag -width 32n -compact 717.Sm off 718.It Xo Dv BPF_LDX No + Dv BPF_W No + 719.Dv BPF_IMM 720.Xc 721.Sm on 722X <- k 723.Sm off 724.It Xo Dv BPF_LDX No + Dv BPF_W No + 725.Dv BPF_MEM 726.Xc 727.Sm on 728X <- M[k] 729.Sm off 730.It Xo Dv BPF_LDX No + Dv BPF_W No + 731.Dv BPF_LEN 732.Xc 733.Sm on 734X <- len 735.Sm off 736.It Xo Dv BPF_LDX No + Dv BPF_B No + 737.Dv BPF_MSH 738.Xc 739.Sm on 740X <- 4*(P[k:1]&0xf) 741.El 742.It Dv BPF_ST 743This instruction stores the accumulator into the scratch memory. 744We do not need an addressing mode since there is only one possibility for 745the destination. 746.Pp 747.Bl -tag -width 32n -compact 748.It Dv BPF_ST 749M[k] <- A 750.El 751.It Dv BPF_STX 752This instruction stores the index register in the scratch memory store. 753.Pp 754.Bl -tag -width 32n -compact 755.It Dv BPF_STX 756M[k] <- X 757.El 758.It Dv BPF_ALU 759The ALU instructions perform operations between the accumulator and index 760register or constant, and store the result back in the accumulator. 761For binary operations, a source mode is required 762.Pf ( Dv BPF_K 763or 764.Dv BPF_X ) . 765.Pp 766.Bl -tag -width 32n -compact 767.Sm off 768.It Xo Dv BPF_ALU No + BPF_ADD No + 769.Dv BPF_K 770.Xc 771.Sm on 772A <- A + k 773.Sm off 774.It Xo Dv BPF_ALU No + BPF_SUB No + 775.Dv BPF_K 776.Xc 777.Sm on 778A <- A - k 779.Sm off 780.It Xo Dv BPF_ALU No + BPF_MUL No + 781.Dv BPF_K 782.Xc 783.Sm on 784A <- A * k 785.Sm off 786.It Xo Dv BPF_ALU No + BPF_DIV No + 787.Dv BPF_K 788.Xc 789.Sm on 790A <- A / k 791.Sm off 792.It Xo Dv BPF_ALU No + BPF_AND No + 793.Dv BPF_K 794.Xc 795.Sm on 796A <- A & k 797.Sm off 798.It Xo Dv BPF_ALU No + BPF_OR No + 799.Dv BPF_K 800.Xc 801.Sm on 802A <- A | k 803.Sm off 804.It Xo Dv BPF_ALU No + BPF_LSH No + 805.Dv BPF_K 806.Xc 807.Sm on 808A <- A << k 809.Sm off 810.It Xo Dv BPF_ALU No + BPF_RSH No + 811.Dv BPF_K 812.Xc 813.Sm on 814A <- A >> k 815.Sm off 816.It Xo Dv BPF_ALU No + BPF_ADD No + 817.Dv BPF_X 818.Xc 819.Sm on 820A <- A + X 821.Sm off 822.It Xo Dv BPF_ALU No + BPF_SUB No + 823.Dv BPF_X 824.Xc 825.Sm on 826A <- A - X 827.Sm off 828.It Xo Dv BPF_ALU No + BPF_MUL No + 829.Dv BPF_X 830.Xc 831.Sm on 832A <- A * X 833.Sm off 834.It Xo Dv BPF_ALU No + BPF_DIV No + 835.Dv BPF_X 836.Xc 837.Sm on 838A <- A / X 839.Sm off 840.It Xo Dv BPF_ALU No + BPF_AND No + 841.Dv BPF_X 842.Xc 843.Sm on 844A <- A & X 845.Sm off 846.It Xo Dv BPF_ALU No + BPF_OR No + 847.Dv BPF_X 848.Xc 849.Sm on 850A <- A | X 851.Sm off 852.It Xo Dv BPF_ALU No + BPF_LSH No + 853.Dv BPF_X 854.Xc 855.Sm on 856A <- A << X 857.Sm off 858.It Xo Dv BPF_ALU No + BPF_RSH No + 859.Dv BPF_X 860.Xc 861.Sm on 862A <- A >> X 863.Sm off 864.It Dv BPF_ALU No + BPF_NEG 865.Sm on 866A <- -A 867.El 868.It Dv BPF_JMP 869The jump instructions alter flow of control. 870Conditional jumps compare the accumulator against a constant 871.Pf ( Dv BPF_K ) 872or the index register 873.Pf ( Dv BPF_X ) . 874If the result is true (or non-zero), the true branch is taken, otherwise the 875false branch is taken. 876Jump offsets are encoded in 8 bits so the longest jump is 256 instructions. 877However, the jump always 878.Pf ( Dv BPF_JA ) 879opcode uses the 32-bit 880.Fa k 881field as the offset, allowing arbitrarily distant destinations. 882All conditionals use unsigned comparison conventions. 883.Pp 884.Bl -tag -width 32n -compact 885.Sm off 886.It Dv BPF_JMP No + BPF_JA 887pc += k 888.Sm on 889.Sm off 890.It Xo Dv BPF_JMP No + BPF_JGT No + 891.Dv BPF_K 892.Xc 893.Sm on 894pc += (A > k) ? jt : jf 895.Sm off 896.It Xo Dv BPF_JMP No + BPF_JGE No + 897.Dv BPF_K 898.Xc 899.Sm on 900pc += (A >= k) ? jt : jf 901.Sm off 902.It Xo Dv BPF_JMP No + BPF_JEQ No + 903.Dv BPF_K 904.Xc 905.Sm on 906pc += (A == k) ? jt : jf 907.Sm off 908.It Xo Dv BPF_JMP No + BPF_JSET No + 909.Dv BPF_K 910.Xc 911.Sm on 912pc += (A & k) ? jt : jf 913.Sm off 914.It Xo Dv BPF_JMP No + BPF_JGT No + 915.Dv BPF_X 916.Xc 917.Sm on 918pc += (A > X) ? jt : jf 919.Sm off 920.It Xo Dv BPF_JMP No + BPF_JGE No + 921.Dv BPF_X 922.Xc 923.Sm on 924pc += (A >= X) ? jt : jf 925.Sm off 926.It Xo Dv BPF_JMP No + BPF_JEQ No + 927.Dv BPF_X 928.Xc 929.Sm on 930pc += (A == X) ? jt : jf 931.Sm off 932.It Xo Dv BPF_JMP No + BPF_JSET No + 933.Dv BPF_X 934.Xc 935.Sm on 936pc += (A & X) ? jt : jf 937.El 938.It Dv BPF_RET 939The return instructions terminate the filter program and specify the 940amount of packet to accept (i.e., they return the truncation amount) 941or, for the write filter, the maximum acceptable size for the packet 942(i.e., the packet is dropped if it is larger than the returned 943amount). 944A return value of zero indicates that the packet should be ignored/dropped. 945The return value is either a constant 946.Pf ( Dv BPF_K ) 947or the accumulator 948.Pf ( Dv BPF_A ) . 949.Pp 950.Bl -tag -width 32n -compact 951.It Dv BPF_RET No + Dv BPF_A 952Accept A bytes. 953.It Dv BPF_RET No + Dv BPF_K 954Accept k bytes. 955.El 956.It Dv BPF_MISC 957The miscellaneous category was created for anything that doesn't fit into 958the above classes, and for any new instructions that might need to be added. 959Currently, these are the register transfer instructions that copy the index 960register to the accumulator or vice versa. 961.Pp 962.Bl -tag -width 32n -compact 963.Sm off 964.It Dv BPF_MISC No + Dv BPF_TAX 965.Sm on 966X <- A 967.Sm off 968.It Dv BPF_MISC No + Dv BPF_TXA 969.Sm on 970A <- X 971.El 972.El 973.Pp 974The 975.Nm 976interface provides the following macros to facilitate array initializers: 977.Bd -filled -offset indent 978.Dv BPF_STMT ( Ns Ar opcode , 979.Ar operand ) 980.Pp 981.Dv BPF_JUMP ( Ns Ar opcode , 982.Ar operand , 983.Ar true_offset , 984.Ar false_offset ) 985.Ed 986.Sh FILES 987.Bl -tag -width /dev/bpf -compact 988.It Pa /dev/bpf 989.Nm 990device 991.El 992.Sh EXAMPLES 993The following filter is taken from the Reverse ARP daemon. 994It accepts only Reverse ARP requests. 995.Bd -literal -offset indent 996struct bpf_insn insns[] = { 997 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), 998 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), 999 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), 1000 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1), 1001 BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + 1002 sizeof(struct ether_header)), 1003 BPF_STMT(BPF_RET+BPF_K, 0), 1004}; 1005.Ed 1006.Pp 1007This filter accepts only IP packets between host 128.3.112.15 and 1008128.3.112.35. 1009.Bd -literal -offset indent 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, 8), 1013 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26), 1014 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), 1015 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), 1016 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), 1017 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), 1018 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), 1019 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), 1020 BPF_STMT(BPF_RET+BPF_K, (u_int)-1), 1021 BPF_STMT(BPF_RET+BPF_K, 0), 1022}; 1023.Ed 1024.Pp 1025Finally, this filter returns only TCP finger packets. 1026We must parse the IP header to reach the TCP header. 1027The 1028.Dv BPF_JSET 1029instruction checks that the IP fragment offset is 0 so we are sure that we 1030have a TCP header. 1031.Bd -literal -offset indent 1032struct bpf_insn insns[] = { 1033 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), 1034 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), 1035 BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), 1036 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), 1037 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), 1038 BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), 1039 BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), 1040 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), 1041 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), 1042 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), 1043 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), 1044 BPF_STMT(BPF_RET+BPF_K, (u_int)-1), 1045 BPF_STMT(BPF_RET+BPF_K, 0), 1046}; 1047.Ed 1048.Sh ERRORS 1049If the 1050.Xr ioctl 2 1051call fails, 1052.Xr errno 2 1053is set to one of the following values: 1054.Bl -tag -width Er 1055.It Bq Er EINVAL 1056The timeout used in a 1057.Dv BIOCSRTIMEOUT 1058request is negative. 1059.It Bq Er EINVAL 1060The timeout used in a 1061.Dv BIOCSRTIMEOUT 1062request specified a microsecond value less than zero or 1063greater than or equal to 1 million. 1064.It Bq Er EOVERFLOW 1065The timeout used in a 1066.Dv BIOCSRTIMEOUT 1067request is too large to be represented by an 1068.Vt int . 1069.El 1070.Sh SEE ALSO 1071.Xr ioctl 2 , 1072.Xr read 2 , 1073.Xr select 2 , 1074.Xr signal 3 , 1075.Xr MAKEDEV 8 , 1076.Xr tcpdump 8 , 1077.Xr arc4random 9 1078.Rs 1079.%A McCanne, S. 1080.%A Jacobson, V. 1081.%D January 1993 1082.%J 1993 Winter USENIX Conference 1083.%T The BSD Packet Filter: A New Architecture for User-level Packet Capture 1084.Re 1085.Sh HISTORY 1086The Enet packet filter was created in 1980 by Mike Accetta and Rick Rashid 1087at Carnegie-Mellon University. 1088Jeffrey Mogul, at Stanford, ported the code to 1089.Bx 1090and continued its 1091development from 1983 on. 1092Since then, it has evolved into the Ultrix Packet Filter at DEC, a STREAMS 1093NIT module under SunOS 4.1, and BPF. 1094.Sh AUTHORS 1095.An -nosplit 1096.An Steve McCanne 1097of Lawrence Berkeley Laboratory implemented BPF in Summer 1990. 1098Much of the design is due to 1099.An Van Jacobson . 1100.Sh BUGS 1101The read buffer must be of a fixed size (returned by the 1102.Dv BIOCGBLEN 1103ioctl). 1104.Pp 1105A file that does not request promiscuous mode may receive promiscuously 1106received packets as a side effect of another file requesting this mode on 1107the same hardware interface. 1108This could be fixed in the kernel with additional processing overhead. 1109However, we favor the model where all files must assume that the interface 1110is promiscuous, and if so desired, must utilize a filter to reject foreign 1111packets. 1112