*** UNIX MANUAL PAGE BROWSER ***

bpf(7) Miscellaneous Information Manual bpf(7) NAME bpf - BSD Packet Filter Extensions DESCRIPTION The BSD Packet Filter (BPF) is similar to the DIGITAL UNIX Packet Fil- ter facility (see packetfilter(7)), but provides a slightly different programming interface. The BPF Extensions to the DIGITAL UNIX packet filter provide nearly complete source-level compatibility with BPF. The reader should be familiar with the packetfilter(7) reference page before reading this reference page. The most useful feature of the BPF Extensions is that packet filter programs may be written in the BPF filter language, which is more effi- cient and more flexible than the original packet filter language. The original language uses a stack-machine model, deals only in 16-bit quantities, has minimal control flow primitives. It also does not sup- port indirect loads, which are necessary for parsing variable-length headers. The BPF language uses a register-machine model, supports 1, 2, and 4 byte data, has a rich set of control flow primitives, and sup- ports indirection. IOCTLS The BPF Extensions consist of a set of ioctl commands that may be ap- plied to a packetfilter(7) file descriptor. The command codes below are defined in <net/bpf.h>. All commands require these header files: #include <sys/types.h> #include <sys/time.h> #include <sys/ioctl.h> #include <net/bpf.h> Additionally, BIOCGETIF and BIOCSETIF require <net/if.h>. For the following commands, the third argument to the ioctl(2) system call should be a pointer to the type indicated. Returns the required buffer length for reads on bpf files. [Provided for compatibility only; on DIGITAL UNIX this may be ignored.] Sets the buffer length for reads on bpf files. If the requested buffer size cannot be accom- modated, the closest allowable size will be set and returned in the ar- gument. A read call will result in EIO if it is passed a buffer that is not this size. [Provided for compatibility only; on DIGITAL UNIX this command has no effect, and reads may specify any buffer size large enough to hold at least one packet.] Returns the type of the data link layer underlying the attached interface. EINVAL is returned if no in- terface has been specified. The device types are defined in <net/bpf.h>. Forces the interface into promiscuous mode. All packets, not just those destined for the local host, are processed. Since more than one file can be listening on a given interface, on some operating systems a listener that opened its interface non-promiscuously may re- ceive packets promiscuously. This problem can be remedied with an ap- propriate filter. [This problem does not occur on DIGITAL UNIX sys- tems, but by assuming that it might happen you will make your programs more portable.] The interface remains in promiscuous mode until all files lis- tening promiscuously are closed. Flushes the buffer of incoming packets, and resets the statistics that are returned by BIOCGSTATS. Returns the name of the hardware interface that file is listening on. The name is returned in the if_name field of ifr. All other fields are undefined. Sets the hardware in- terface associate with the file. This command must be performed before any packets can be read. The device is indicated by name using the if_name field of the ifreq. Additionally, performs the actions of BIOCFLUSH. Set or get the read timeout parame- ter. The timeval specifies the length of time to wait before timing out on a read request. This parameter is initialized to zero by open(2), indicating no timeout. [See the description of EIOCSRTIMEOUT in packetfilter(7) for more details on timeout values.] Returns the following structure of packet statistics: struct bpf_stat { u_int bs_recv; u_int bs_drop; }; The fields are: The number of packets received by the descriptor since opened or reset (including any buffered since the last read call). The number of packets which were accepted by the filter but dropped by the kernel because of buffer overflows (i.e., because the application's reads are not keeping up with the packet traffic). Enable or disable ``immediate mode'', based on the truth value of the argument. When immediate mode is enabled, reads return immediately upon packet reception. Otherwise, a read will block until either the kernel buffer be- comes full or a timeout occurs. The default for a new file is off. [On DIGITAL UNIX systems, this command has no effect. ``Immediate mode'' is always in effect; a read will never block if there is a received packet available.] Sets the filter pro- gram used by the kernel to discard uninteresting packets. An array of instructions and its length is passed in using the fol- lowing structure: struct bpf_program { int bf_len; struct bpf_insn *bf_insns; }; The filter program is pointed to by the bf_insns field while its length in units of `struct bpf_insn' is given by the bf_len field. Also, the actions of BIOCFLUSH are performed. See section FILTER MACHINE for an explanation of the filter lan- guage. In addition, the SIOCGIFADDR ioctl may be applied to packet fil- ter file descriptors. BPF HEADER By default, the DIGITAL UNIX Packet Filter does not prepend a header to each packet, while the BSD Packet Filter does. To request that the BPF header be prepended to each packet returned by read(2), use the EIOCM- BIS ioctl command to set the ENBPFHDR mode bit (see packetfilter(7) for details on the use of EIOCMBIS). If the ENBPFHDR and ENTSTAMP mode bits are simultaneously set, the ENBPFHDR takes precedence. If the ENBPFHDR mode bit is set, batch mode (see the description of ENBATCH in packetfilter(7)) is enabled, and the following structure is prepended to each packet returned by read(2): struct bpf_hdr { struct timeval bh_tstamp; u_int bh_caplen; u_int bh_datalen; u_short bh_hdrlen; }; The fields, whose values are stored in host byte order, and are: The time at which the packet was processed by the packet filter. The length of the captured portion of the packet. This is the minimum of the truncation amount specified by the filter and the length of the packet. [On DIGITAL UNIX systems, the truncation amount specified by the filter is ignored, and the one specified by EIOCTRUNCATE (see pack- etfilter(7)) is used.] The length of the packet off the wire. This value is independent of the truncation amount specified by the filter. The length of the BPF header, which may not be equal to sizeof(struct bpf_hdr). The bh_hdrlen field exists to account for padding between the header and the link level protocol. The purpose here is to guarantee proper alignment of the packet data structures, which is required on align- ment-sensitive architectures and improves performance on many other ar- chitectures. The packet filter insures that the bpf_hdr and the net- work layer header will be word-aligned. Suitable precautions must be taken when accessing the link layer protocol fields on alignment re- stricted machines. (This isn't a problem on an Ethernet, since the type field is a short falling on an even offset, and the addresses are probably accessed in a bytewise fashion). Additionally, individual packets are padded so that each BPF header starts on a word boundary. This requires that an application has some knowledge of how to get from packet to packet. The macro BPF_WORDALIGN is defined in <net/bpf.h> to facilitate this process. It rounds up its argument to the nearest word aligned value (where a word is BPF_ALIGN- MENT bytes wide). For example, if `p' points to the start of a packet (i.e., the start of the prepended BPF header), this expression will advance it to the next packet (BPF header): p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) For the alignment mechanisms to work properly, the buffer passed to read(2) must itself be word aligned. malloc(3) will always return an aligned buffer. FILTER MACHINE A filter program is an array of instructions, with all branches for- wardly directed, terminated by a return instruction. Each instruction performs some action on the pseudo-machine state, which consists of an accumulator, index register, scratch memory store, and implicit program counter. The following structure defines the instruction format: struct bpf_insn { u_short code; u_char jt; u_char jf; int k; }; The k field is used in different ways by differ- ent instructions, and the jt and jf fields are used as offsets by the branch instructions. The opcodes are encoded in a semi-hierarchical fashion. There are eight classes of instructions: BPF_LD, BPF_LDX, BPF_ST, BPF_STX, BPF_ALU, BPF_JMP, BPF_RET, and BPF_MISC. Various other mode and operator bits are or'd with the class bits to give the actual instructions. The classes and modes are defined in <net/bpf.h>. Below is given the semantics for each defined BPF instruction. We use the convention that A is the accumulator, X is the index register, P[] packet data, and M[] scratch memory store. P[i:n] gives the data at byte offset ``i'' in the packet, interpreted as a word (n=4), unsigned halfword (n=2), or unsigned byte (n=1). M[i] gives the i'th word in the scratch memory store, which is only addressed in word units. The memory store is indexed from 0 to BPF_MEMWORDS-1. k, jt, and jf are the corresponding fields in the instruction definition. ``len'' refers to the length of the packet. These instructions copy a value into the accumulator. The type of the source operand is specified by an ``ad- dressing mode'' and can be a constant (BPF_IMM), packet data at a fixed offset (BPF_ABS), packet data at a variable offset (BPF_IND), the packet length (BPF_LEN), or a word in the scratch memory store (BPF_MEM). For BPF_IND and BPF_ABS, the data size must be specified as a word (BPF_W), halfword (BPF_H), or byte (BPF_B). The semantics of all the recognized BPF_LD instructions followings: A <- P[k:4] A <- P[k:2] A <- P[k:1] A <- P[X+k:4] A <- P[X+k:2] A <- P[X+k:1] A <- len A <- k A <- M[k] These instructions load a value into the index register. Note that the addressing modes are more restricted than those of the accumulator loads, but they include BPF_MSH, a hack for efficiently loading the IP header length. X <- k X <- M[k] X <- len X <- 4*(P[k:1]&0xf) This instruction stores the accumulator into the scratch memory. We do not need an addressing mode since there is only one pos- sibility for the destination. M[k] <- A This instruction stores the index register in the scratch memory store. M[k] <- X The alu instruc- tions perform operations between the accumulator and index register or constant, and store the result back in the accumulator. For binary op- erations, a source mode is required (BPF_K or BPF_X). A <- A + k A <- A - k A <- A * k A <- A / k A <- A & k A <- A | k A <- A << k A <- A >> k A <- A + X A <- A - X A <- A * X A <- A / X A <- A & X A <- A | X A <- A << X A <- A >> X A <- -A The jump instructions alter flow of con- trol. Conditional jumps compare the accumulator against a constant (BPF_K) or the index register (BPF_X). If the result is true (or non- zero), the true branch is taken, otherwise the false branch is taken. Jump offsets are encoded in 8 bits so the longest jump is 256 instruc- tions. However, the jump always (BPF_JA) opcode uses the 32 bit k field as the offset, allowing arbitrarily distant destinations. All conditionals use unsigned comparison conventions. pc += k pc += (A > k) ? jt : jf pc += (A >= k) ? jt : jf pc += (A == k) ? jt : jf pc += (A & k) ? jt : jf pc += (A > X) ? jt : jf pc += (A >= X) ? jt : jf pc += (A == X) ? jt : jf pc += (A & X) ? jt : jf The return instructions ter- minate the filter program and specify the amount of packet to accept (i.e., they return the truncation amount). A return value of zero in- dicates that the packet should be ignored. The return value is either a constant (BPF_K) or the accumulator (BPF_A). accept A bytes accept k bytes [On DIGITAL UNIX systems, the entire packet is accepted if and only if the return value is non-zero; the truncation amount is con- trolled using EIOCTRUNCATE.] The miscellaneous category was created for anything that doesn't fit into the above classes, and for any new instructions that might need to be added. Currently, these are the register transfer instructions that copy the index register to the ac- cumulator or vice versa. X <- A A <- X The BPF interface provides the following macros to facilitate array initializers: RESTRICTIONS If BPF headers are used, data link protocols with variable length head- ers are not properly supported. EXAMPLES The following filter is taken from the Reverse ARP Daemon. It accepts only Reverse ARP requests. struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1), BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + sizeof(struct ether_header)), BPF_STMT(BPF_RET+BPF_K, 0), }; This filter accepts only IP packets between host 128.3.112.15 and 128.3.112.35. struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 26), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; Finally, this filter returns only TCP finger packets. We must parse the IP header to reach the TCP header. The BPF_JSET instruction checks that the IP fragment offset is 0 so we are sure that we have a TCP header. struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; INCOMPATIBILITIES The BSD Packet Filter Extensions for the DIGITAL UNIX Packet Filter are intended to provide nearly complete source-level compatibility with the BSD Packet Filter (BPF), but in some details this is not possible. To summarize the significant differences: In BPF, pseudo-devices are named /dev/bpf0, /dev/bpf1, and so on. Applications open them directly. On DIGITAL UNIX systems, pseudo-devices are named /dev/pf/pfilt0, /dev/pf/pfilt1, and so on. In BPF, the BPF header is always prepended to packets. On DIGITAL UNIX this behavior must be specifically re- quested by setting the ENBPFHDR mode bit. In BPF, the number of packet bytes returned by the kernel is specified by the return value from the BPF filter program. This can thus vary from packet to packet (since a BPF filter program may have more than one return statement). On DIGI- TAL UNIX the size returned by a BPF filter program is ignored, and the number of returned packet bytes is set using EIOCTRUNCATE. This means that it cannot vary from packet to packet. By default, DIGITAL UNIX returns the entire packet, which means that programs not using EIOC- TRUNCATE will probably operate correctly, but perhaps not efficiently. In BPF, packet filter applications see packets to or from their own host. On DIGITAL UNIX packet filter applications do not see packets to or from their own host, unless the ENCOPYALL mode bit is set. In BPF, the number of queued packets is limited to what will fit in one page (after truncation). On DIGITAL UNIX the limit on the number of queued packets defaults to 2. This limit may be increased using EIOCSETW. Not doing so may result in many lost packets. RELATED INFORMATION Commands: pfconfig(8) pfstat(1) Files: packetfilter(7) delim off bpf(7)