1 .\" Copyright (c) 1990 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that: (1) source code distributions
6 .\" retain the above copyright notice and this paragraph in its entirety, (2)
7 .\" distributions including binary code include the above copyright notice and
8 .\" this paragraph in its entirety in the documentation or other materials
9 .\" provided with the distribution, and (3) all advertising materials mentioning
10 .\" features or use of this software display the following acknowledgement:
11 .\" ``This product includes software developed by the University of California,
12 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
13 .\" the University nor the names of its contributors may be used to endorse
14 .\" or promote products derived from this software without specific prior
15 .\" written permission.
16 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
17 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
18 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
20 .\" This document is derived in part from the enet man page (enet.4)
21 .\" distributed with 4.3BSD Unix.
23 .\" $FreeBSD: src/share/man/man4/bpf.4,v 1.21.2.10 2001/08/17 13:08:37 ru Exp $
30 .Nd Berkeley Packet Filter
34 The Berkeley Packet Filter
35 provides a raw interface to data link layers in a protocol
37 All packets on the network, even those destined for other hosts,
38 are accessible through this mechanism.
40 The packet filter appears as a character special device,
44 After opening the device, the file descriptor must be bound to a
45 specific network interface with the
48 A given interface can be shared be multiple listeners, and the filter
49 underlying each descriptor will see an identical packet stream.
51 A separate device file is required for each minor device.
52 If a file is in use, the open will fail and
57 Associated with each open instance of a
59 file is a user-settable packet filter.
60 Whenever a packet is received by an interface,
61 all file descriptors listening on that interface apply their filter.
62 Each descriptor that accepts the packet receives its own copy.
64 Reads from these files return the next group of packets
65 that have matched the filter.
66 To improve performance, the buffer passed to read must be
67 the same size as the buffers used internally by
69 This size is returned by the
71 ioctl (see below), and
74 Note that an individual packet larger than this size is necessarily
77 The packet filter will support any link level protocol that has fixed length
78 headers. Currently, only Ethernet,
82 drivers have been modified to interact with
85 Since packet data is in network byte order, applications should use the
87 macros to extract multi-byte values.
89 A packet can be sent out on the network by writing to a
91 file descriptor. The writes are unbuffered, meaning only one
92 packet can be processed per write.
93 Currently, only writes to Ethernets and
97 When the last minor device is opened, an additional minor device is
98 created on demand. The maximum number of devices that can be created is
99 controlled by the sysctl debug.bpf_maxdevices.
103 command codes below are defined in
108 #include <sys/types.h>
109 #include <sys/time.h>
110 #include <sys/ioctl.h>
125 the following commands may be applied to any open
128 The (third) argument to
130 should be a pointer to the type indicated.
131 .Bl -tag -width BIOCGRTIMEOUT
134 Returns the required buffer length for reads on
139 Sets the buffer length for reads on
141 files. The buffer must be set before the file is attached to an interface
144 If the requested buffer size cannot be accommodated, the closest
145 allowable size will be set and returned in the argument.
146 A read call will result in
148 if it is passed a buffer that is not this size.
151 Returns the type of the data link layer underlying the attached interface.
153 is returned if no interface has been specified.
154 The device types, prefixed with
159 Forces the interface into promiscuous mode.
160 All packets, not just those destined for the local host, are processed.
161 Since more than one file can be listening on a given interface,
162 a listener that opened its interface non-promiscuously may receive
163 packets promiscuously. This problem can be remedied with an
166 Flushes the buffer of incoming packets,
167 and resets the statistics that are returned by BIOCGSTATS.
169 .Pq Li "struct ifreq"
170 Returns the name of the hardware interface that the file is listening on.
171 The name is returned in the ifr_name field of
175 All other fields are undefined.
177 .Pq Li "struct ifreq"
178 Sets the hardware interface associate with the file. This
179 command must be performed before any packets can be read.
180 The device is indicated by name using the
185 Additionally, performs the actions of
189 .Pq Li "struct timeval"
190 Set or get the read timeout parameter.
192 specifies the length of time to wait before timing
193 out on a read request.
194 This parameter is initialized to zero by
196 indicating no timeout.
198 .Pq Li "struct bpf_stat"
199 Returns the following structure of packet statistics:
202 u_int bs_recv; /* number of packets received */
203 u_int bs_drop; /* number of packets dropped */
208 .Bl -hang -offset indent
210 the number of packets received by the descriptor since opened or reset
211 (including any buffered since the last read call);
214 the number of packets which were accepted by the filter but dropped by the
215 kernel because of buffer overflows
216 (i.e., the application's reads aren't keeping up with the packet traffic).
222 based on the truth value of the argument.
223 When immediate mode is enabled, reads return immediately upon packet
224 reception. Otherwise, a read will block until either the kernel buffer
225 becomes full or a timeout occurs.
226 This is useful for programs like
228 which must respond to messages in real time.
229 The default for a new file is off.
231 .Pq Li "struct bpf_program"
232 Sets the filter program used by the kernel to discard uninteresting
233 packets. An array of instructions and its length is passed in using
234 the following structure:
238 struct bpf_insn *bf_insns;
242 The filter program is pointed to by the
244 field while its length in units of
245 .Sq Li struct bpf_insn
254 for an explanation of the filter language.
256 .Pq Li "struct bpf_version"
257 Returns the major and minor version numbers of the filter language currently
258 recognized by the kernel. Before installing a filter, applications must check
259 that the current version is compatible with the running kernel. Version
260 numbers are compatible if the major numbers match and the application minor
261 is less than or equal to the kernel minor. The kernel version number is
262 returned in the following structure:
270 The current version numbers are given by
271 .Dv BPF_MAJOR_VERSION
273 .Dv BPF_MINOR_VERSION
276 An incompatible filter
277 may result in undefined behavior (most likely, an error returned by
279 or haphazard packet matching).
283 Set or get the status of the
286 Set to zero if the link level source address should be filled in automatically
287 by the interface output routine. Set to one if the link level source
288 address will be written, as provided, to the wire. This flag is initialized
293 Set or get the flag determining whether locally generated packets on the
294 interface should be returned by BPF. Set to zero to see only incoming
295 packets on the interface. Set to one to see packets originating
296 locally and remotely on the interface. This flag is initialized to one by
300 The following structure is prepended to each packet returned by
304 struct timeval bh_tstamp; /* time stamp */
305 u_long bh_caplen; /* length of captured portion */
306 u_long bh_datalen; /* original length of packet */
307 u_short bh_hdrlen; /* length of bpf header (this struct
308 plus alignment padding */
312 The fields, whose values are stored in host order, and are:
314 .Bl -tag -compact -width bh_datalen
316 The time at which the packet was processed by the packet filter.
318 The length of the captured portion of the packet. This is the minimum of
319 the truncation amount specified by the filter and the length of the packet.
321 The length of the packet off the wire.
322 This value is independent of the truncation amount specified by the filter.
326 header, which may not be equal to
327 .\" XXX - not really a function call
328 .Fn sizeof "struct bpf_hdr" .
333 field exists to account for
334 padding between the header and the link level protocol.
335 The purpose here is to guarantee proper alignment of the packet
336 data structures, which is required on alignment sensitive
337 architectures and improves performance on many other architectures.
338 The packet filter insures that the
340 and the network layer
341 header will be word aligned. Suitable precautions
342 must be taken when accessing the link layer protocol fields on alignment
343 restricted machines. (This isn't a problem on an Ethernet, since
344 the type field is a short falling on an even offset,
345 and the addresses are probably accessed in a bytewise fashion).
347 Additionally, individual packets are padded so that each starts
348 on a word boundary. This requires that an application
349 has some knowledge of how to get from packet to packet.
355 this process. It rounds up its argument
356 to the nearest word aligned value (where a word is
362 points to the start of a packet, this expression
363 will advance it to the next packet:
364 .Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen)
366 For the alignment mechanisms to work properly, the
369 must itself be word aligned.
373 will always return an aligned buffer.
375 A filter program is an array of instructions, with all branches forwardly
376 directed, terminated by a
379 Each instruction performs some action on the pseudo-machine state,
380 which consists of an accumulator, index register, scratch memory store,
381 and implicit program counter.
383 The following structure defines the instruction format:
395 field is used in different ways by different instructions,
400 fields are used as offsets
401 by the branch instructions.
402 The opcodes are encoded in a semi-hierarchical fashion.
403 There are eight classes of instructions:
413 Various other mode and
414 operator bits are or'd into the class to give the actual instructions.
415 The classes and modes are defined in
418 Below are the semantics for each defined
421 We use the convention that A is the accumulator, X is the index register,
422 P[] packet data, and M[] scratch memory store.
423 P[i:n] gives the data at byte offset
426 interpreted as a word (n=4),
427 unsigned halfword (n=2), or unsigned byte (n=1).
428 M[i] gives the i'th word in the scratch memory store, which is only
429 addressed in word units. The memory store is indexed from 0 to
436 are the corresponding fields in the
437 instruction definition.
439 refers to the length of the packet.
441 .Bl -tag -width BPF_STXx
443 These instructions copy a value into the accumulator. The type of the
444 source operand is specified by an
446 and can be a constant
448 packet data at a fixed offset
450 packet data at a variable offset
454 or a word in the scratch memory store
460 the data size must be specified as a word
466 The semantics of all the recognized
470 .Bl -tag -width "BPF_LD+BPF_W+BPF_IND" -compact
471 .It Li BPF_LD+BPF_W+BPF_ABS
473 .It Li BPF_LD+BPF_H+BPF_ABS
475 .It Li BPF_LD+BPF_B+BPF_ABS
477 .It Li BPF_LD+BPF_W+BPF_IND
479 .It Li BPF_LD+BPF_H+BPF_IND
481 .It Li BPF_LD+BPF_B+BPF_IND
483 .It Li BPF_LD+BPF_W+BPF_LEN
485 .It Li BPF_LD+BPF_IMM
487 .It Li BPF_LD+BPF_MEM
491 These instructions load a value into the index register. Note that
492 the addressing modes are more restrictive than those of the accumulator loads,
495 a hack for efficiently loading the IP header length.
497 .Bl -tag -width "BPF_LDX+BPF_W+BPF_MEM" -compact
498 .It Li BPF_LDX+BPF_W+BPF_IMM
500 .It Li BPF_LDX+BPF_W+BPF_MEM
502 .It Li BPF_LDX+BPF_W+BPF_LEN
504 .It Li BPF_LDX+BPF_B+BPF_MSH
508 This instruction stores the accumulator into the scratch memory.
509 We do not need an addressing mode since there is only one possibility
512 .Bl -tag -width "BPF_ST" -compact
517 This instruction stores the index register in the scratch memory store.
519 .Bl -tag -width "BPF_STX" -compact
524 The alu instructions perform operations between the accumulator and
525 index register or constant, and store the result back in the accumulator.
526 For binary operations, a source mode is required
531 .Bl -tag -width "BPF_ALU+BPF_MUL+BPF_K" -compact
532 .It Li BPF_ALU+BPF_ADD+BPF_K
534 .It Li BPF_ALU+BPF_SUB+BPF_K
536 .It Li BPF_ALU+BPF_MUL+BPF_K
538 .It Li BPF_ALU+BPF_DIV+BPF_K
540 .It Li BPF_ALU+BPF_AND+BPF_K
542 .It Li BPF_ALU+BPF_OR+BPF_K
544 .It Li BPF_ALU+BPF_LSH+BPF_K
546 .It Li BPF_ALU+BPF_RSH+BPF_K
548 .It Li BPF_ALU+BPF_ADD+BPF_X
550 .It Li BPF_ALU+BPF_SUB+BPF_X
552 .It Li BPF_ALU+BPF_MUL+BPF_X
554 .It Li BPF_ALU+BPF_DIV+BPF_X
556 .It Li BPF_ALU+BPF_AND+BPF_X
558 .It Li BPF_ALU+BPF_OR+BPF_X
560 .It Li BPF_ALU+BPF_LSH+BPF_X
562 .It Li BPF_ALU+BPF_RSH+BPF_X
564 .It Li BPF_ALU+BPF_NEG
568 The jump instructions alter flow of control. Conditional jumps
569 compare the accumulator against a constant
571 or the index register
573 If the result is true (or non-zero),
574 the true branch is taken, otherwise the false branch is taken.
575 Jump offsets are encoded in 8 bits so the longest jump is 256 instructions.
576 However, the jump always
578 opcode uses the 32 bit
580 field as the offset, allowing arbitrarily distant destinations.
581 All conditionals use unsigned comparison conventions.
583 .Bl -tag -width "BPF_JMP+BPF_KSET+BPF_X" -compact
584 .It Li BPF_JMP+BPF_JA
586 .It Li BPF_JMP+BPF_JGT+BPF_K
587 pc += (A > k) ? jt : jf
588 .It Li BPF_JMP+BPF_JGE+BPF_K
589 pc += (A >= k) ? jt : jf
590 .It Li BPF_JMP+BPF_JEQ+BPF_K
591 pc += (A == k) ? jt : jf
592 .It Li BPF_JMP+BPF_JSET+BPF_K
593 pc += (A & k) ? jt : jf
594 .It Li BPF_JMP+BPF_JGT+BPF_X
595 pc += (A > X) ? jt : jf
596 .It Li BPF_JMP+BPF_JGE+BPF_X
597 pc += (A >= X) ? jt : jf
598 .It Li BPF_JMP+BPF_JEQ+BPF_X
599 pc += (A == X) ? jt : jf
600 .It Li BPF_JMP+BPF_JSET+BPF_X
601 pc += (A & X) ? jt : jf
604 The return instructions terminate the filter program and specify the amount
605 of packet to accept (i.e., they return the truncation amount). A return
606 value of zero indicates that the packet should be ignored.
607 The return value is either a constant
612 .Bl -tag -width "BPF_RET+BPF_K" -compact
619 The miscellaneous category was created for anything that doesn't
620 fit into the above classes, and for any new instructions that might need to
621 be added. Currently, these are the register transfer instructions
622 that copy the index register to the accumulator or vice versa.
624 .Bl -tag -width "BPF_MISC+BPF_TAX" -compact
625 .It Li BPF_MISC+BPF_TAX
627 .It Li BPF_MISC+BPF_TXA
634 interface provides the following macros to facilitate
636 .Fn BPF_STMT opcode operand
638 .Fn BPF_JUMP opcode operand true_offset false_offset .
640 The following filter is taken from the Reverse ARP Daemon. It accepts
641 only Reverse ARP requests.
643 struct bpf_insn insns[] = {
644 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
645 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3),
646 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
647 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1),
648 BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) +
649 sizeof(struct ether_header)),
650 BPF_STMT(BPF_RET+BPF_K, 0),
654 This filter accepts only IP packets between host 128.3.112.15 and
657 struct bpf_insn insns[] = {
658 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
659 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8),
660 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26),
661 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2),
662 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
663 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4),
664 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3),
665 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
666 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1),
667 BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
668 BPF_STMT(BPF_RET+BPF_K, 0),
672 Finally, this filter returns only TCP finger packets. We must parse
673 the IP header to reach the TCP header. The
676 checks that the IP fragment offset is 0 so we are sure
677 that we have a TCP header.
679 struct bpf_insn insns[] = {
680 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
681 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10),
682 BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23),
683 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8),
684 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
685 BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0),
686 BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14),
687 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14),
688 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0),
689 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16),
690 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1),
691 BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
692 BPF_STMT(BPF_RET+BPF_K, 0),
703 .%T "An efficient, extensible, and portable network monitor"
706 .Bl -tag -compact -width /dev/bpfXXX
707 .It Pa /dev/bpf Ns Sy n
708 the packet filter device
711 The read buffer must be of a fixed size (returned by the
715 A file that does not request promiscuous mode may receive promiscuously
716 received packets as a side effect of another file requesting this
717 mode on the same hardware interface. This could be fixed in the kernel
718 with additional processing overhead. However, we favor the model where
719 all files must assume that the interface is promiscuous, and if
720 so desired, must utilize a filter to reject foreign packets.
722 Data link protocols with variable length headers are not currently supported.
724 The Enet packet filter was created in 1980 by Mike Accetta and
725 Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at
726 Stanford, ported the code to
728 and continued its development from
729 1983 on. Since then, it has evolved into the Ultrix Packet Filter
742 of Lawrence Berkeley Laboratory, implemented BPF in
743 Summer 1990. Much of the design is due to