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.
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
79 Currently, only Ethernet,
83 drivers have been modified to interact with
86 Since packet data is in network byte order, applications should use the
88 macros to extract multi-byte values.
90 A packet can be sent out on the network by writing to a
93 The writes are unbuffered, meaning only one packet can be processed per write.
94 Currently, only writes to Ethernets and
100 command codes below are defined in
105 #include <sys/types.h>
106 #include <sys/time.h>
107 #include <sys/ioctl.h>
124 the following commands may be applied to any open
127 The (third) argument to
129 should be a pointer to the type indicated.
130 .Bl -tag -width BIOCGRTIMEOUT
133 Returns the required buffer length for reads on
138 Sets the buffer length for reads on
141 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.
164 This problem can be remedied with an appropriate filter.
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.
180 command must be performed before any packets can be read.
181 The device is indicated by name using the
186 Additionally, performs the actions of
190 .Pq Li "struct timeval"
191 Set or get the read timeout parameter.
193 specifies the length of time to wait before timing
194 out on a read request.
195 This parameter is initialized to zero by
197 indicating no timeout.
199 .Pq Li "struct bpf_stat"
200 Returns the following structure of packet statistics:
203 u_int bs_recv; /* number of packets received */
204 u_int bs_drop; /* number of packets dropped */
209 .Bl -hang -offset indent
211 the number of packets received by the descriptor since opened or reset
212 (including any buffered since the last read call);
215 the number of packets which were accepted by the filter but dropped by the
216 kernel because of buffer overflows
217 (i.e., the application's reads are not keeping up with the packet traffic).
223 based on the truth value of the argument.
224 When immediate mode is enabled, reads return immediately upon packet
226 Otherwise, a read will block until either the kernel buffer
227 becomes full or a timeout occurs.
228 This is useful for programs like
230 which must respond to messages in real time.
231 The default for a new file is off.
233 .Pq Li "struct bpf_program"
234 Sets the read filter program used by the kernel to discard uninteresting
236 An array of instructions and its length is passed in using
237 the following structure:
241 struct bpf_insn *bf_insns;
245 The filter program is pointed to by the
247 field while its length in units of
248 .Sq Li struct bpf_insn
257 for an explanation of the filter language.
259 .Pq Li "struct bpf_program"
260 Sets the write filter program used by the kernel to control what type of
261 packets can be written to the interface.
269 .Pq Li "struct bpf_version"
270 Returns the major and minor version numbers of the filter language currently
271 recognized by the kernel.
272 Before installing a filter, applications must check
273 that the current version is compatible with the running kernel.
274 Version numbers are compatible if the major numbers match and the application minor
275 is less than or equal to the kernel minor.
276 The kernel version number is returned in the following structure:
284 The current version numbers are given by
285 .Dv BPF_MAJOR_VERSION
287 .Dv BPF_MINOR_VERSION
290 An incompatible filter
291 may result in undefined behavior (most likely, an error returned by
293 or haphazard packet matching).
297 Set or get the status of the
300 Set to zero if the link level source address should be filled in automatically
301 by the interface output routine.
302 Set to one if the link level source
303 address will be written, as provided, to the wire.
304 This flag is initialized to zero by default.
308 These commands are obsolete but left for compatibility.
314 Set or get the flag determining whether locally generated packets on the
315 interface should be returned by BPF.
316 Set to zero to see only incoming packets on the interface.
317 Set to one to see packets originating locally and remotely on the interface.
318 This flag is initialized to one by default.
319 .It Dv BIOCSDIRECTION
320 .It Dv BIOCGDIRECTION
322 Set or get the setting determining whether incoming, outgoing, or all packets
323 on the interface should be returned by BPF.
326 to see only incoming packets on the interface.
329 to see packets originating locally and remotely on the interface.
332 to see only outgoing packets on the interface.
333 This setting is initialized to
338 Set packet feedback mode.
339 This allows injected packets to be fed back as input to the interface when
340 output via the interface is successful.
343 direction is set, injected outgoing packet is not returned by BPF to avoid
344 duplication. This flag is initialized to zero by default.
346 Set the locked flag on the
349 This prevents the execution of
350 ioctl commands which could change the underlying operating parameters of
354 The following structure is prepended to each packet returned by
358 struct timeval bh_tstamp; /* time stamp */
359 u_long bh_caplen; /* length of captured portion */
360 u_long bh_datalen; /* original length of packet */
361 u_short bh_hdrlen; /* length of bpf header (this struct
362 plus alignment padding */
366 The fields, whose values are stored in host order, and are:
368 .Bl -tag -compact -width bh_datalen
370 The time at which the packet was processed by the packet filter.
372 The length of the captured portion of the packet.
373 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.
398 must be taken when accessing the link layer protocol fields on alignment
400 (This is not a problem on an Ethernet, since
401 the type field is a short falling on an even offset,
402 and the addresses are probably accessed in a bytewise fashion).
404 Additionally, individual packets are padded so that each starts
406 This requires that an application
407 has some knowledge of how to get from packet to packet.
414 It rounds up its argument to the nearest word aligned value (where a word is
420 points to the start of a packet, this expression
421 will advance it to the next packet:
422 .Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen)
424 For the alignment mechanisms to work properly, the
427 must itself be word aligned.
431 will always return an aligned buffer.
433 A filter program is an array of instructions, with all branches forwardly
434 directed, terminated by a
437 Each instruction performs some action on the pseudo-machine state,
438 which consists of an accumulator, index register, scratch memory store,
439 and implicit program counter.
441 The following structure defines the instruction format:
453 field is used in different ways by different instructions,
458 fields are used as offsets
459 by the branch instructions.
460 The opcodes are encoded in a semi-hierarchical fashion.
461 There are eight classes of instructions:
471 Various other mode and
472 operator bits are or'd into the class to give the actual instructions.
473 The classes and modes are defined in
476 Below are the semantics for each defined
479 We use the convention that A is the accumulator, X is the index register,
480 P[] packet data, and M[] scratch memory store.
481 P[i:n] gives the data at byte offset
484 interpreted as a word (n=4),
485 unsigned halfword (n=2), or unsigned byte (n=1).
486 M[i] gives the i'th word in the scratch memory store, which is only
487 addressed in word units.
488 The memory store is indexed from 0 to
495 are the corresponding fields in the
496 instruction definition.
498 refers to the length of the packet.
500 .Bl -tag -width BPF_STXx
502 These instructions copy a value into the accumulator.
503 The type of the source operand is specified by an
505 and can be a constant
507 packet data at a fixed offset
509 packet data at a variable offset
513 or a word in the scratch memory store
519 the data size must be specified as a word
525 The semantics of all the recognized
530 BPF_LD+BPF_W+BPF_ABS A <- P[k:4]
531 BPF_LD+BPF_H+BPF_ABS A <- P[k:2]
532 BPF_LD+BPF_B+BPF_ABS A <- P[k:1]
533 BPF_LD+BPF_W+BPF_IND A <- P[X+k:4]
534 BPF_LD+BPF_H+BPF_IND A <- P[X+k:2]
535 BPF_LD+BPF_B+BPF_IND A <- P[X+k:1]
536 BPF_LD+BPF_W+BPF_LEN A <- len
537 BPF_LD+BPF_IMM A <- k
538 BPF_LD+BPF_MEM A <- M[k]
541 These instructions load a value into the index register.
543 the addressing modes are more restrictive than those of the accumulator loads,
546 a hack for efficiently loading the IP header length.
549 BPF_LDX+BPF_W+BPF_IMM X <- k
550 BPF_LDX+BPF_W+BPF_MEM X <- M[k]
551 BPF_LDX+BPF_W+BPF_LEN X <- len
552 BPF_LDX+BPF_B+BPF_MSH X <- 4*(P[k:1]&0xf)
555 This instruction stores the accumulator into the scratch memory.
556 We do not need an addressing mode since there is only one possibility
563 This instruction stores the index register in the scratch memory store.
569 The alu instructions perform operations between the accumulator and
570 index register or constant, and store the result back in the accumulator.
571 For binary operations, a source mode is required
577 BPF_ALU+BPF_ADD+BPF_K A <- A + k
578 BPF_ALU+BPF_SUB+BPF_K A <- A - k
579 BPF_ALU+BPF_MUL+BPF_K A <- A * k
580 BPF_ALU+BPF_DIV+BPF_K A <- A / k
581 BPF_ALU+BPF_AND+BPF_K A <- A & k
582 BPF_ALU+BPF_OR+BPF_K A <- A | k
583 BPF_ALU+BPF_LSH+BPF_K A <- A << k
584 BPF_ALU+BPF_RSH+BPF_K A <- A >> k
585 BPF_ALU+BPF_ADD+BPF_X A <- A + X
586 BPF_ALU+BPF_SUB+BPF_X A <- A - X
587 BPF_ALU+BPF_MUL+BPF_X A <- A * X
588 BPF_ALU+BPF_DIV+BPF_X A <- A / X
589 BPF_ALU+BPF_AND+BPF_X A <- A & X
590 BPF_ALU+BPF_OR+BPF_X A <- A | X
591 BPF_ALU+BPF_LSH+BPF_X A <- A << X
592 BPF_ALU+BPF_RSH+BPF_X A <- A >> X
593 BPF_ALU+BPF_NEG A <- -A
596 The jump instructions alter flow of control.
598 compare the accumulator against a constant
600 or the index register
602 If the result is true (or non-zero),
603 the true branch is taken, otherwise the false branch is taken.
604 Jump offsets are encoded in 8 bits so the longest jump is 256 instructions.
605 However, the jump always
607 opcode uses the 32 bit
609 field as the offset, allowing arbitrarily distant destinations.
610 All conditionals use unsigned comparison conventions.
613 BPF_JMP+BPF_JA pc += k
614 BPF_JMP+BPF_JGT+BPF_K pc += (A > k) ? jt : jf
615 BPF_JMP+BPF_JGE+BPF_K pc += (A >= k) ? jt : jf
616 BPF_JMP+BPF_JEQ+BPF_K pc += (A == k) ? jt : jf
617 BPF_JMP+BPF_JSET+BPF_K pc += (A & k) ? jt : jf
618 BPF_JMP+BPF_JGT+BPF_X pc += (A > X) ? jt : jf
619 BPF_JMP+BPF_JGE+BPF_X pc += (A >= X) ? jt : jf
620 BPF_JMP+BPF_JEQ+BPF_X pc += (A == X) ? jt : jf
621 BPF_JMP+BPF_JSET+BPF_X pc += (A & X) ? jt : jf
624 The return instructions terminate the filter program and specify the amount
625 of packet to accept (i.e., they return the truncation amount).
626 A return value of zero indicates that the packet should be ignored.
627 The return value is either a constant
633 BPF_RET+BPF_A accept A bytes
634 BPF_RET+BPF_K accept k bytes
637 The miscellaneous category was created for anything that does not
638 fit into the above classes, and for any new instructions that might need to
640 Currently, these are the register transfer instructions
641 that copy the index register to the accumulator or vice versa.
644 BPF_MISC+BPF_TAX X <- A
645 BPF_MISC+BPF_TXA A <- X
651 interface provides the following macros to facilitate
653 .Fn BPF_STMT opcode operand
655 .Fn BPF_JUMP opcode operand true_offset false_offset .
657 .Bl -tag -compact -width /dev/bpfXXX
658 .It Pa /dev/bpf Ns Sy n
659 the packet filter device
662 The following filter is taken from the Reverse ARP Daemon.
663 It accepts only Reverse ARP requests.
665 struct bpf_insn insns[] = {
666 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
667 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3),
668 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
669 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1),
670 BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) +
671 sizeof(struct ether_header)),
672 BPF_STMT(BPF_RET+BPF_K, 0),
676 This filter accepts only IP packets between host 128.3.112.15 and
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, 8),
682 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26),
683 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2),
684 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
685 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4),
686 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3),
687 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
688 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1),
689 BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
690 BPF_STMT(BPF_RET+BPF_K, 0),
694 Finally, this filter returns only TCP finger packets.
695 We must parse the IP header to reach the TCP header.
699 checks that the IP fragment offset is 0 so we are sure
700 that we have a TCP header.
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_IP, 0, 10),
705 BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23),
706 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8),
707 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
708 BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0),
709 BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14),
710 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14),
711 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0),
712 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16),
713 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1),
714 BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
715 BPF_STMT(BPF_RET+BPF_K, 0),
727 .%T "An efficient, extensible, and portable network monitor"
730 The Enet packet filter was created in 1980 by Mike Accetta and
731 Rick Rashid at Carnegie-Mellon University.
733 Stanford, ported the code to
735 and continued its development from
737 Since then, it has evolved into the Ultrix Packet Filter at
749 of Lawrence Berkeley Laboratory, implemented BPF in
751 Much of the design is due to
754 The read buffer must be of a fixed size (returned by the
758 A file that does not request promiscuous mode may receive promiscuously
759 received packets as a side effect of another file requesting this
760 mode on the same hardware interface.
761 This could be fixed in the kernel with additional processing overhead.
762 However, we favor the model where
763 all files must assume that the interface is promiscuous, and if
764 so desired, must utilize a filter to reject foreign packets.
766 Data link protocols with variable length headers are not currently supported.
773 settings have been observed to work incorrectly on some interface
774 types, including those with hardware loopback rather than software loopback,
775 and point-to-point interfaces.
776 They appear to function correctly on a
777 broad range of Ethernet-style interfaces.