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.11 2002/04/07 04:57:13 dd 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 by 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
99 command codes below are defined in
104 #include <sys/types.h>
105 #include <sys/time.h>
106 #include <sys/ioctl.h>
123 the following commands may be applied to any open
126 The (third) argument to
128 should be a pointer to the type indicated.
129 .Bl -tag -width ".Dv BIOCGRTIMEOUT"
132 Returns the required buffer length for reads on
137 Sets the buffer length for reads on
139 files. The buffer must be set before the file is attached to an interface
142 If the requested buffer size cannot be accommodated, the closest
143 allowable size will be set and returned in the argument.
144 A read call will result in
146 if it is passed a buffer that is not this size.
149 Returns the type of the data link layer underlying the attached interface.
151 is returned if no interface has been specified.
152 The device types, prefixed with
157 Forces the interface into promiscuous mode.
158 All packets, not just those destined for the local host, are processed.
159 Since more than one file can be listening on a given interface,
160 a listener that opened its interface non-promiscuously may receive
161 packets promiscuously. This problem can be remedied with an
164 Flushes the buffer of incoming packets,
165 and resets the statistics that are returned by
168 .Pq Li "struct ifreq"
169 Returns the name of the hardware interface that the file is listening on.
170 The name is returned in the ifr_name field of
174 All other fields are undefined.
176 This ioctl is designed to prevent the security issues associated
179 descriptor in unprivileged programs.
180 Even with dropped privileges, an open
182 descriptor can be abused by a rogue program to listen on any interface
183 on the system, send packets on these interfaces if the descriptor was
184 opened read-write and send signals to arbitrary processes using the
185 signaling mechanism of
191 ioctl prevents this abuse.
192 The allowable ioctls are
209 Use of any other ioctl is denied with error
211 Once a descriptor is locked, it is not possible to unlock it.
212 A process with root privileges is not affected by the lock.
214 A privileged program can open a
216 device, drop privileges, set the interface, filters and modes on the
217 descriptor, and lock it.
218 Once the descriptor is locked, the system is safe
219 from further abuse through the descriptor.
220 Locking a descriptor does not prevent writes.
221 If the application does not need to send packets through
223 it can open the device read-only to prevent writing.
224 If sending packets is necessary, a write-filter can be set before locking the
225 descriptor to prevent arbitrary packets from being sent out.
227 .Pq Li "struct ifreq"
228 Sets the hardware interface associated with the file.
229 This command must be performed before any packets can be read.
230 The device is indicated by name using the
235 Additionally, performs the actions of
238 .Pq Li "struct bpf_program *"
239 Sets the write filter program used by the kernel to filter the packets
240 written to the descriptor before the packets are sent out on the
244 .Pq Li "struct timeval"
245 Set or get the read timeout parameter.
247 specifies the length of time to wait before timing
248 out on a read request.
249 This parameter is initialized to zero by
251 indicating no timeout.
253 .Pq Li "struct bpf_stat"
254 Returns the following structure of packet statistics:
257 u_int bs_recv; /* number of packets received */
258 u_int bs_drop; /* number of packets dropped */
263 .Bl -hang -offset indent
265 the number of packets received by the descriptor since opened or reset
266 (including any buffered since the last read call);
269 the number of packets which were accepted by the filter but dropped by the
270 kernel because of buffer overflows
271 (i.e., the application's reads aren't keeping up with the packet traffic).
277 based on the truth value of the argument.
278 When immediate mode is enabled, reads return immediately upon packet
279 reception. Otherwise, a read will block until either the kernel buffer
280 becomes full or a timeout occurs.
281 This is useful for programs like
283 which must respond to messages in real time.
284 The default for a new file is off.
286 .Pq Li "struct bpf_program"
287 Sets the read filter program used by the kernel to discard uninteresting
288 packets. An array of instructions and its length is passed in using
289 the following structure:
293 struct bpf_insn *bf_insns;
297 The filter program is pointed to by the
299 field while its length in units of
300 .Sq Li struct bpf_insn
309 for an explanation of the filter language.
311 .Pq Li "struct bpf_version"
312 Returns the major and minor version numbers of the filter language currently
313 recognized by the kernel. Before installing a filter, applications must check
314 that the current version is compatible with the running kernel. Version
315 numbers are compatible if the major numbers match and the application minor
316 is less than or equal to the kernel minor. The kernel version number is
317 returned in the following structure:
325 The current version numbers are given by
326 .Dv BPF_MAJOR_VERSION
328 .Dv BPF_MINOR_VERSION
331 An incompatible filter
332 may result in undefined behavior (most likely, an error returned by
334 or haphazard packet matching).
338 Set or get the status of the
341 Set to zero if the link level source address should be filled in automatically
342 by the interface output routine. Set to one if the link level source
343 address will be written, as provided, to the wire. This flag is initialized
348 Set or get the flag determining whether locally generated packets on the
349 interface should be returned by BPF. Set to zero to see only incoming
350 packets on the interface. Set to one to see packets originating
351 locally and remotely on the interface. This flag is initialized to one by
355 The following structure is prepended to each packet returned by
359 struct timeval bh_tstamp; /* time stamp */
360 u_long bh_caplen; /* length of captured portion */
361 u_long bh_datalen; /* original length of packet */
362 u_short bh_hdrlen; /* length of bpf header (this struct
363 plus alignment padding */
367 The fields, whose values are stored in host order, and are:
369 .Bl -tag -compact -width bh_datalen
371 The time at which the packet was processed by the packet filter.
373 The length of the captured portion of the packet. This is the minimum of
374 the truncation amount specified by the filter and the length of the packet.
376 The length of the packet off the wire.
377 This value is independent of the truncation amount specified by the filter.
381 header, which may not be equal to
382 .\" XXX - not really a function call
383 .Fn sizeof "struct bpf_hdr" .
388 field exists to account for
389 padding between the header and the link level protocol.
390 The purpose here is to guarantee proper alignment of the packet
391 data structures, which is required on alignment sensitive
392 architectures and improves performance on many other architectures.
393 The packet filter insures that the
395 and the network layer
396 header will be word aligned. Suitable precautions
397 must be taken when accessing the link layer protocol fields on alignment
398 restricted machines. (This isn't a problem on an Ethernet, since
399 the type field is a short falling on an even offset,
400 and the addresses are probably accessed in a bytewise fashion).
402 Additionally, individual packets are padded so that each starts
403 on a word boundary. This requires that an application
404 has some knowledge of how to get from packet to packet.
410 this process. It rounds up its argument
411 to the nearest word aligned value (where a word is
417 points to the start of a packet, this expression
418 will advance it to the next packet:
419 .Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen)
421 For the alignment mechanisms to work properly, the
424 must itself be word aligned.
428 will always return an aligned buffer.
430 A filter program is an array of instructions, with all branches forwardly
431 directed, terminated by a
434 Each instruction performs some action on the pseudo-machine state,
435 which consists of an accumulator, index register, scratch memory store,
436 and implicit program counter.
438 The following structure defines the instruction format:
450 field is used in different ways by different instructions,
455 fields are used as offsets
456 by the branch instructions.
457 The opcodes are encoded in a semi-hierarchical fashion.
458 There are eight classes of instructions:
468 Various other mode and
469 operator bits are or'd into the class to give the actual instructions.
470 The classes and modes are defined in
473 Below are the semantics for each defined
476 We use the convention that A is the accumulator, X is the index register,
477 P[] packet data, and M[] scratch memory store.
478 P[i:n] gives the data at byte offset
481 interpreted as a word (n=4),
482 unsigned halfword (n=2), or unsigned byte (n=1).
483 M[i] gives the i'th word in the scratch memory store, which is only
484 addressed in word units. The memory store is indexed from 0 to
491 are the corresponding fields in the
492 instruction definition.
494 refers to the length of the packet.
495 .Bl -tag -width BPF_STXx
497 These instructions copy a value into the accumulator. The type of the
498 source operand is specified by an
500 and can be a constant
502 packet data at a fixed offset
504 packet data at a variable offset
508 or a word in the scratch memory store
514 the data size must be specified as a word
520 The semantics of all the recognized
524 .Bl -tag -width "BPF_LD+BPF_W+BPF_IND" -compact
525 .It Li BPF_LD+BPF_W+BPF_ABS
527 .It Li BPF_LD+BPF_H+BPF_ABS
529 .It Li BPF_LD+BPF_B+BPF_ABS
531 .It Li BPF_LD+BPF_W+BPF_IND
533 .It Li BPF_LD+BPF_H+BPF_IND
535 .It Li BPF_LD+BPF_B+BPF_IND
537 .It Li BPF_LD+BPF_W+BPF_LEN
539 .It Li BPF_LD+BPF_IMM
541 .It Li BPF_LD+BPF_MEM
545 These instructions load a value into the index register. Note that
546 the addressing modes are more restrictive than those of the accumulator loads,
549 a hack for efficiently loading the IP header length.
551 .Bl -tag -width "BPF_LDX+BPF_W+BPF_MEM" -compact
552 .It Li BPF_LDX+BPF_W+BPF_IMM
554 .It Li BPF_LDX+BPF_W+BPF_MEM
556 .It Li BPF_LDX+BPF_W+BPF_LEN
558 .It Li BPF_LDX+BPF_B+BPF_MSH
562 This instruction stores the accumulator into the scratch memory.
563 We do not need an addressing mode since there is only one possibility
566 .Bl -tag -width "BPF_ST" -compact
571 This instruction stores the index register in the scratch memory store.
573 .Bl -tag -width "BPF_STX" -compact
578 The alu instructions perform operations between the accumulator and
579 index register or constant, and store the result back in the accumulator.
580 For binary operations, a source mode is required
585 .Bl -tag -width "BPF_ALU+BPF_MUL+BPF_K" -compact
586 .It Li BPF_ALU+BPF_ADD+BPF_K
588 .It Li BPF_ALU+BPF_SUB+BPF_K
590 .It Li BPF_ALU+BPF_MUL+BPF_K
592 .It Li BPF_ALU+BPF_DIV+BPF_K
594 .It Li BPF_ALU+BPF_AND+BPF_K
596 .It Li BPF_ALU+BPF_OR+BPF_K
598 .It Li BPF_ALU+BPF_LSH+BPF_K
600 .It Li BPF_ALU+BPF_RSH+BPF_K
602 .It Li BPF_ALU+BPF_ADD+BPF_X
604 .It Li BPF_ALU+BPF_SUB+BPF_X
606 .It Li BPF_ALU+BPF_MUL+BPF_X
608 .It Li BPF_ALU+BPF_DIV+BPF_X
610 .It Li BPF_ALU+BPF_AND+BPF_X
612 .It Li BPF_ALU+BPF_OR+BPF_X
614 .It Li BPF_ALU+BPF_LSH+BPF_X
616 .It Li BPF_ALU+BPF_RSH+BPF_X
618 .It Li BPF_ALU+BPF_NEG
622 The jump instructions alter flow of control. Conditional jumps
623 compare the accumulator against a constant
625 or the index register
627 If the result is true (or non-zero),
628 the true branch is taken, otherwise the false branch is taken.
629 Jump offsets are encoded in 8 bits so the longest jump is 256 instructions.
630 However, the jump always
632 opcode uses the 32 bit
634 field as the offset, allowing arbitrarily distant destinations.
635 All conditionals use unsigned comparison conventions.
637 .Bl -tag -width "BPF_JMP+BPF_KSET+BPF_X" -compact
638 .It Li BPF_JMP+BPF_JA
640 .It Li BPF_JMP+BPF_JGT+BPF_K
641 pc += (A > k) ? jt : jf
642 .It Li BPF_JMP+BPF_JGE+BPF_K
643 pc += (A >= k) ? jt : jf
644 .It Li BPF_JMP+BPF_JEQ+BPF_K
645 pc += (A == k) ? jt : jf
646 .It Li BPF_JMP+BPF_JSET+BPF_K
647 pc += (A & k) ? jt : jf
648 .It Li BPF_JMP+BPF_JGT+BPF_X
649 pc += (A > X) ? jt : jf
650 .It Li BPF_JMP+BPF_JGE+BPF_X
651 pc += (A >= X) ? jt : jf
652 .It Li BPF_JMP+BPF_JEQ+BPF_X
653 pc += (A == X) ? jt : jf
654 .It Li BPF_JMP+BPF_JSET+BPF_X
655 pc += (A & X) ? jt : jf
658 The return instructions terminate the filter program and specify the amount
659 of packet to accept (i.e., they return the truncation amount). A return
660 value of zero indicates that the packet should be ignored.
661 The return value is either a constant
666 .Bl -tag -width "BPF_RET+BPF_K" -compact
673 The miscellaneous category was created for anything that doesn't
674 fit into the above classes, and for any new instructions that might need to
675 be added. Currently, these are the register transfer instructions
676 that copy the index register to the accumulator or vice versa.
678 .Bl -tag -width "BPF_MISC+BPF_TAX" -compact
679 .It Li BPF_MISC+BPF_TAX
681 .It Li BPF_MISC+BPF_TXA
688 interface provides the following macros to facilitate
690 .Fn BPF_STMT opcode operand
692 .Fn BPF_JUMP opcode operand true_offset false_offset .
694 .Bl -tag -compact -width /dev/bpfXXX
695 .It Pa /dev/bpf Ns Sy n
696 the packet filter device
699 The following filter is taken from the Reverse ARP Daemon. It accepts
700 only Reverse ARP requests.
702 struct bpf_insn insns[] = {
703 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
704 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3),
705 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
706 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1),
707 BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) +
708 sizeof(struct ether_header)),
709 BPF_STMT(BPF_RET+BPF_K, 0),
713 This filter accepts only IP packets between host 128.3.112.15 and
716 struct bpf_insn insns[] = {
717 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
718 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8),
719 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26),
720 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2),
721 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
722 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4),
723 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3),
724 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
725 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1),
726 BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
727 BPF_STMT(BPF_RET+BPF_K, 0),
731 Finally, this filter returns only TCP finger packets. We must parse
732 the IP header to reach the TCP header. The
735 checks that the IP fragment offset is 0 so we are sure
736 that we have a TCP header.
738 struct bpf_insn insns[] = {
739 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
740 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10),
741 BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23),
742 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8),
743 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
744 BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0),
745 BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14),
746 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14),
747 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0),
748 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16),
749 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1),
750 BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
751 BPF_STMT(BPF_RET+BPF_K, 0),
762 .%T "An efficient, extensible, and portable network monitor"
765 The Enet packet filter was created in 1980 by Mike Accetta and
766 Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at
767 Stanford, ported the code to
769 and continued its development from
770 1983 on. Since then, it has evolved into the Ultrix Packet Filter
783 of Lawrence Berkeley Laboratory, implemented BPF in
784 Summer 1990. Much of the design is due to
787 The read buffer must be of a fixed size (returned by the
791 A file that does not request promiscuous mode may receive promiscuously
792 received packets as a side effect of another file requesting this
793 mode on the same hardware interface. This could be fixed in the kernel
794 with additional processing overhead. However, we favor the model where
795 all files must assume that the interface is promiscuous, and if
796 so desired, must utilize a filter to reject foreign packets.
798 Data link protocols with variable length headers are not currently supported.