| blob | 1db19a9720c49e05b8894dfd0ec4e4b58d1c88de |
1 .\" Copyright (c) 2007 Seccuris Inc.
2 .\" All rights reserved.
3 .\"
4 .\" This sofware was developed by Robert N. M. Watson under contract to
5 .\" Seccuris Inc.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\" Copyright (c) 1990 The Regents of the University of California.
29 .\" All rights reserved.
30 .\"
31 .\" Redistribution and use in source and binary forms, with or without
32 .\" modification, are permitted provided that: (1) source code distributions
33 .\" retain the above copyright notice and this paragraph in its entirety, (2)
34 .\" distributions including binary code include the above copyright notice and
35 .\" this paragraph in its entirety in the documentation or other materials
36 .\" provided with the distribution, and (3) all advertising materials mentioning
37 .\" features or use of this software display the following acknowledgement:
38 .\" ``This product includes software developed by the University of California,
39 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
40 .\" the University nor the names of its contributors may be used to endorse
41 .\" or promote products derived from this software without specific prior
42 .\" written permission.
43 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
44 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
45 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
46 .\"
47 .\" This document is derived in part from the enet man page (enet.4)
48 .\" distributed with 4.3BSD Unix.
49 .\"
50 .\" $FreeBSD$
51 .\"
52 .Dd February 26, 2007
53 .Dt BPF 4
54 .Os
55 .Sh NAME
56 .Nm bpf
57 .Nd Berkeley Packet Filter
58 .Sh SYNOPSIS
59 .Cd device bpf
60 .Sh DESCRIPTION
61 The Berkeley Packet Filter
62 provides a raw interface to data link layers in a protocol
63 independent fashion.
64 All packets on the network, even those destined for other hosts,
65 are accessible through this mechanism.
66 .Pp
67 The packet filter appears as a character special device,
68 .Pa /dev/bpf .
69 After opening the device, the file descriptor must be bound to a
70 specific network interface with the
71 .Dv BIOCSETIF
72 ioctl.
73 A given interface can be shared by multiple listeners, and the filter
74 underlying each descriptor will see an identical packet stream.
75 .Pp
76 A separate device file is required for each minor device.
77 If a file is in use, the open will fail and
78 .Va errno
79 will be set to
80 .Er EBUSY .
81 .Pp
82 Associated with each open instance of a
83 .Nm
84 file is a user-settable packet filter.
85 Whenever a packet is received by an interface,
86 all file descriptors listening on that interface apply their filter.
87 Each descriptor that accepts the packet receives its own copy.
88 .Pp
89 The packet filter will support any link level protocol that has fixed length
90 headers.
91 Currently, only Ethernet,
92 .Tn SLIP ,
93 and
94 .Tn PPP
95 drivers have been modified to interact with
96 .Nm .
97 .Pp
98 Since packet data is in network byte order, applications should use the
99 .Xr byteorder 3
100 macros to extract multi-byte values.
101 .Pp
102 A packet can be sent out on the network by writing to a
103 .Nm
104 file descriptor.
105 The writes are unbuffered, meaning only one packet can be processed per write.
106 Currently, only writes to Ethernets and
107 .Tn SLIP
108 links are supported.
109 .Sh BUFFER MODES
110 .Nm
111 devices deliver packet data to the application via memory buffers provided by
112 the application.
113 The buffer mode is set using the
114 .Dv BIOCSETBUFMODE
115 ioctl, and read using the
116 .Dv BIOCGETBUFMODE
117 ioctl.
118 .Ss Buffered read mode
119 By default,
120 .Nm
121 devices operate in the
122 .Dv BPF_BUFMODE_BUFFER
123 mode, in which packet data is copied explicitly from kernel to user memory
124 using the
125 .Xr read 2
126 system call.
127 The user process will declare a fixed buffer size that will be used both for
128 sizing internal buffers and for all
129 .Xr read 2
130 operations on the file.
131 This size is queried using the
132 .Dv BIOCGBLEN
133 ioctl, and is set using the
134 .Dv BIOCSBLEN
135 ioctl.
136 Note that an individual packet larger than the buffer size is necessarily
137 truncated.
138 .Ss Zero-copy buffer mode
139 .Nm
140 devices may also operate in the
141 .Dv BPF_BUFMODE_ZEROCOPY
142 mode, in which packet data is written directly into two user memory buffers
143 by the kernel, avoiding both system call and copying overhead.
144 Buffers are of fixed (and equal) size, page-aligned, and an even multiple of
145 the page size.
146 The maximum zero-copy buffer size is returned by the
147 .Dv BIOCGETZMAX
148 ioctl.
149 Note that an individual packet larger than the buffer size is necessarily
150 truncated.
151 .Pp
152 The user process registers two memory buffers using the
153 .Dv BIOCSETZBUF
154 ioctl, which accepts a
155 .Vt struct bpf_zbuf
156 pointer as an argument:
157 .Bd -literal
158 struct bpf_zbuf {
159 void *bz_bufa;
160 void *bz_bufb;
161 size_t bz_buflen;
162 };
163 .Ed
164 .Pp
165 .Vt bz_bufa
166 is a pointer to the userspace address of the first buffer that will be
167 filled, and
168 .Vt bz_bufb
169 is a pointer to the second buffer.
170 .Nm
171 will then cycle between the two buffers as they fill and are acknowledged.
172 .Pp
173 Each buffer begins with a fixed-length header to hold synchronization and
174 data length information for the buffer:
175 .Bd -literal
176 struct bpf_zbuf_header {
177 volatile u_int bzh_kernel_gen; /* Kernel generation number. */
178 volatile u_int bzh_kernel_len; /* Length of data in the buffer. */
179 volatile u_int bzh_user_gen; /* User generation number. */
180 /* ...padding for future use... */
181 };
182 .Ed
183 .Pp
184 The header structure of each buffer, including all padding, should be zeroed
185 before it is configured using
186 .Dv BIOCSETZBUF .
187 Remaining space in the buffer will be used by the kernel to store packet
188 data, laid out in the same format as with buffered read mode.
189 .Pp
190 The kernel and the user process follow a simple acknowledgement protocol via
191 the buffer header to synchronize access to the buffer: when the header
192 generation numbers,
193 .Vt bzh_kernel_gen
194 and
195 .Vt bzh_user_gen ,
196 hold the same value, the kernel owns the buffer, and when they differ,
197 userspace owns the buffer.
198 .Pp
199 While the kernel owns the buffer, the contents are unstable and may change
200 asynchronously; while the user process owns the buffer, its contents are
201 stable and will not be changed until the buffer has been acknowledged.
202 .Pp
203 Initializing the buffer headers to all 0's before registering the buffer has
204 the effect of assigning initial ownership of both buffers to the kernel.
205 The kernel signals that a buffer has been assigned to userspace by modifying
206 .Vt bzh_kernel_gen ,
207 and userspace acknowledges the buffer and returns it to the kernel by setting
208 the value of
209 .Vt bzh_user_gen
210 to the value of
211 .Vt bzh_kernel_gen .
212 .Pp
213 In order to avoid caching and memory re-ordering effects, the user process
214 must use atomic operations and memory barriers when checking for and
215 acknowledging buffers:
216 .Bd -literal
217 #include <machine/atomic.h>
219 /*
220 * Return ownership of a buffer to the kernel for reuse.
221 */
222 static void
223 buffer_acknowledge(struct bpf_zbuf_header *bzh)
224 {
226 atomic_store_rel_int(&bzh->bzh_user_gen, bzh->bzh_kernel_gen);
227 }
229 /*
230 * Check whether a buffer has been assigned to userspace by the kernel.
231 * Return true if userspace owns the buffer, and false otherwise.
232 */
233 static int
234 buffer_check(struct bpf_zbuf_header *bzh)
235 {
237 return (bzh->bzh_user_gen !=
238 atomic_load_acq_int(&bzh->bzh_kernel_gen));
239 }
240 .Ed
241 .Pp
242 The user process may force the assignment of the next buffer, if any data
243 is pending, to userspace using the
244 .Dv BIOCROTZBUF
245 ioctl.
246 This allows the user process to retrieve data in a partially filled buffer
247 before the buffer is full, such as following a timeout; the process must
248 recheck for buffer ownership using the header generation numbers, as the
249 buffer will not be assigned to userspace if no data was present.
250 .Pp
251 As in the buffered read mode,
252 .Xr kqueue 2 ,
253 .Xr poll 2 ,
254 and
255 .Xr select 2
256 may be used to sleep awaiting the availbility of a completed buffer.
257 They will return a readable file descriptor when ownership of the next buffer
258 is assigned to user space.
259 .Pp
260 In the current implementation, the kernel may assign zero, one, or both
261 buffers to the user process; however, an earlier implementation maintained
262 the invariant that at most one buffer could be assigned to the user process
263 at a time.
264 In order to both ensure progress and high performance, user processes should
265 acknowledge a completely processed buffer as quickly as possible, returning
266 it for reuse, and not block waiting on a second buffer while holding another
267 buffer.
268 .Sh IOCTLS
269 The
270 .Xr ioctl 2
271 command codes below are defined in
272 .In net/bpf.h .
273 All commands require
274 these includes:
275 .Bd -literal
276 #include <sys/types.h>
277 #include <sys/time.h>
278 #include <sys/ioctl.h>
279 #include <net/bpf.h>
280 .Ed
281 .Pp
282 Additionally,
283 .Dv BIOCGETIF
284 and
285 .Dv BIOCSETIF
286 require
287 .In sys/socket.h
288 and
289 .In net/if.h .
290 .Pp
291 In addition to
292 .Dv FIONREAD
293 and
294 .Dv SIOCGIFADDR ,
295 the following commands may be applied to any open
296 .Nm
297 file.
298 The (third) argument to
299 .Xr ioctl 2
300 should be a pointer to the type indicated.
301 .Bl -tag -width BIOCGETBUFMODE
302 .It Dv BIOCGBLEN
303 .Pq Li u_int
304 Returns the required buffer length for reads on
305 .Nm
306 files.
307 .It Dv BIOCSBLEN
308 .Pq Li u_int
309 Sets the buffer length for reads on
310 .Nm
311 files.
312 The buffer must be set before the file is attached to an interface
313 with
314 .Dv BIOCSETIF .
315 If the requested buffer size cannot be accommodated, the closest
316 allowable size will be set and returned in the argument.
317 A read call will result in
318 .Er EIO
319 if it is passed a buffer that is not this size.
320 .It Dv BIOCGDLT
321 .Pq Li u_int
322 Returns the type of the data link layer underlying the attached interface.
323 .Er EINVAL
324 is returned if no interface has been specified.
325 The device types, prefixed with
326 .Dq Li DLT_ ,
327 are defined in
328 .In net/bpf.h .
329 .It Dv BIOCPROMISC
330 Forces the interface into promiscuous mode.
331 All packets, not just those destined for the local host, are processed.
332 Since more than one file can be listening on a given interface,
333 a listener that opened its interface non-promiscuously may receive
334 packets promiscuously.
335 This problem can be remedied with an appropriate filter.
336 .It Dv BIOCFLUSH
337 Flushes the buffer of incoming packets,
338 and resets the statistics that are returned by BIOCGSTATS.
339 .It Dv BIOCGETIF
340 .Pq Li "struct ifreq"
341 Returns the name of the hardware interface that the file is listening on.
342 The name is returned in the ifr_name field of
343 the
344 .Li ifreq
345 structure.
346 All other fields are undefined.
347 .It Dv BIOCSETIF
348 .Pq Li "struct ifreq"
349 Sets the hardware interface associate with the file.
350 This
351 command must be performed before any packets can be read.
352 The device is indicated by name using the
353 .Li ifr_name
354 field of the
355 .Li ifreq
356 structure.
357 Additionally, performs the actions of
358 .Dv BIOCFLUSH .
359 .It Dv BIOCSRTIMEOUT
360 .It Dv BIOCGRTIMEOUT
361 .Pq Li "struct timeval"
362 Set or get the read timeout parameter.
363 The argument
364 specifies the length of time to wait before timing
365 out on a read request.
366 This parameter is initialized to zero by
367 .Xr open 2 ,
368 indicating no timeout.
369 .It Dv BIOCGSTATS
370 .Pq Li "struct bpf_stat"
371 Returns the following structure of packet statistics:
372 .Bd -literal
373 struct bpf_stat {
374 u_int bs_recv; /* number of packets received */
375 u_int bs_drop; /* number of packets dropped */
376 };
377 .Ed
378 .Pp
379 The fields are:
380 .Bl -hang -offset indent
381 .It Li bs_recv
382 the number of packets received by the descriptor since opened or reset
383 (including any buffered since the last read call);
384 and
385 .It Li bs_drop
386 the number of packets which were accepted by the filter but dropped by the
387 kernel because of buffer overflows
388 (i.e., the application's reads are not keeping up with the packet traffic).
389 .El
390 .It Dv BIOCIMMEDIATE
391 .Pq Li u_int
392 Enable or disable
393 .Dq immediate mode ,
394 based on the truth value of the argument.
395 When immediate mode is enabled, reads return immediately upon packet
396 reception.
397 Otherwise, a read will block until either the kernel buffer
398 becomes full or a timeout occurs.
399 This is useful for programs like
400 .Xr rarpd 8
401 which must respond to messages in real time.
402 The default for a new file is off.
403 .It Dv BIOCSETF
404 .It Dv BIOCSETFNR
405 .Pq Li "struct bpf_program"
406 Sets the read filter program used by the kernel to discard uninteresting
407 packets.
408 An array of instructions and its length is passed in using
409 the following structure:
410 .Bd -literal
411 struct bpf_program {
412 int bf_len;
413 struct bpf_insn *bf_insns;
414 };
415 .Ed
416 .Pp
417 The filter program is pointed to by the
418 .Li bf_insns
419 field while its length in units of
420 .Sq Li struct bpf_insn
421 is given by the
422 .Li bf_len
423 field.
424 See section
425 .Sx "FILTER MACHINE"
426 for an explanation of the filter language.
427 The only difference between
428 .Dv BIOCSETF
429 and
430 .Dv BIOCSETFNR
431 is
432 .Dv BIOCSETF
433 performs the actions of
434 .Dv BIOCFLUSH
435 while
436 .Dv BIOCSETFNR
437 does not.
438 .It Dv BIOCSETWF
439 .Pq Li "struct bpf_program"
440 Sets the write filter program used by the kernel to control what type of
441 packets can be written to the interface.
442 See the
443 .Dv BIOCSETF
444 command for more
445 information on the
446 .Nm
447 filter program.
448 .It Dv BIOCVERSION
449 .Pq Li "struct bpf_version"
450 Returns the major and minor version numbers of the filter language currently
451 recognized by the kernel.
452 Before installing a filter, applications must check
453 that the current version is compatible with the running kernel.
454 Version numbers are compatible if the major numbers match and the application minor
455 is less than or equal to the kernel minor.
456 The kernel version number is returned in the following structure:
457 .Bd -literal
458 struct bpf_version {
459 u_short bv_major;
460 u_short bv_minor;
461 };
462 .Ed
463 .Pp
464 The current version numbers are given by
465 .Dv BPF_MAJOR_VERSION
466 and
467 .Dv BPF_MINOR_VERSION
468 from
469 .In net/bpf.h .
470 An incompatible filter
471 may result in undefined behavior (most likely, an error returned by
472 .Fn ioctl
473 or haphazard packet matching).
474 .It Dv BIOCSHDRCMPLT
475 .It Dv BIOCGHDRCMPLT
476 .Pq Li u_int
477 Set or get the status of the
478 .Dq header complete
479 flag.
480 Set to zero if the link level source address should be filled in automatically
481 by the interface output routine.
482 Set to one if the link level source
483 address will be written, as provided, to the wire.
484 This flag is initialized to zero by default.
485 .It Dv BIOCSSEESENT
486 .It Dv BIOCGSEESENT
487 .Pq Li u_int
488 These commands are obsolete but left for compatibility.
489 Use
490 .Dv BIOCSDIRECTION
491 and
492 .Dv BIOCGDIRECTION
493 instead.
494 Set or get the flag determining whether locally generated packets on the
495 interface should be returned by BPF.
496 Set to zero to see only incoming packets on the interface.
497 Set to one to see packets originating locally and remotely on the interface.
498 This flag is initialized to one by default.
499 .It Dv BIOCSDIRECTION
500 .It Dv BIOCGDIRECTION
501 .Pq Li u_int
502 Set or get the setting determining whether incoming, outgoing, or all packets
503 on the interface should be returned by BPF.
504 Set to
505 .Dv BPF_D_IN
506 to see only incoming packets on the interface.
507 Set to
508 .Dv BPF_D_INOUT
509 to see packets originating locally and remotely on the interface.
510 Set to
511 .Dv BPF_D_OUT
512 to see only outgoing packets on the interface.
513 This setting is initialized to
514 .Dv BPF_D_INOUT
515 by default.
516 .It Dv BIOCFEEDBACK
517 .Pq Li u_int
518 Set packet feedback mode.
519 This allows injected packets to be fed back as input to the interface when
520 output via the interface is successful.
521 When
522 .Dv BPF_D_INOUT
523 direction is set, injected outgoing packet is not returned by BPF to avoid
524 duplication. This flag is initialized to zero by default.
525 .It Dv BIOCLOCK
526 Set the locked flag on the
527 .Nm
528 descriptor.
529 This prevents the execution of
530 ioctl commands which could change the underlying operating parameters of
531 the device.
532 .It Dv BIOCGETBUFMODE
533 .It Dv BIOCSETBUFMODE
534 .Pq Li u_int
535 Get or set the current
536 .Nm
537 buffering mode; possible values are
538 .Dv BPF_BUFMODE_BUFFER ,
539 buffered read mode, and
540 .Dv BPF_BUFMODE_ZBUF ,
541 zero-copy buffer mode.
542 .It Dv BIOCSETZBUF
543 .Pq Li struct bpf_zbuf
544 Set the current zero-copy buffer locations; buffer locations may be
545 set only once zero-copy buffer mode has been selected, and prior to attaching
546 to an interface.
547 Buffers must be of identical size, page-aligned, and an integer multiple of
548 pages in size.
549 The three fields
550 .Vt bz_bufa ,
551 .Vt bz_bufb ,
552 and
553 .Vt bz_buflen
554 must be filled out.
555 If buffers have already been set for this device, the ioctl will fail.
556 .It Dv BIOCGETZMAX
557 .Pq Li size_t
558 Get the largest individual zero-copy buffer size allowed.
559 As two buffers are used in zero-copy buffer mode, the limit (in practice) is
560 twice the returned size.
561 As zero-copy buffers consume kernel address space, conservative selection of
562 buffer size is suggested, especially when there are multiple
563 .Nm
564 descriptors in use on 32-bit systems.
565 .It Dv BIOCROTZBUF
566 Force ownership of the next buffer to be assigned to userspace, if any data
567 present in the buffer.
568 If no data is present, the buffer will remain owned by the kernel.
569 This allows consumers of zero-copy buffering to implement timeouts and
570 retrieve partially filled buffers.
571 In order to handle the case where no data is present in the buffer and
572 therefore ownership is not assigned, the user process must check
573 .Vt bzh_kernel_gen
574 against
575 .Vt bzh_user_gen .
576 .El
577 .Sh BPF HEADER
578 The following structure is prepended to each packet returned by
579 .Xr read 2
580 or via a zero-copy buffer:
581 .Bd -literal
582 struct bpf_hdr {
583 struct timeval bh_tstamp; /* time stamp */
584 u_long bh_caplen; /* length of captured portion */
585 u_long bh_datalen; /* original length of packet */
586 u_short bh_hdrlen; /* length of bpf header (this struct
587 plus alignment padding */
588 };
589 .Ed
590 .Pp
591 The fields, whose values are stored in host order, and are:
592 .Pp
593 .Bl -tag -compact -width bh_datalen
594 .It Li bh_tstamp
595 The time at which the packet was processed by the packet filter.
596 .It Li bh_caplen
597 The length of the captured portion of the packet.
598 This is the minimum of
599 the truncation amount specified by the filter and the length of the packet.
600 .It Li bh_datalen
601 The length of the packet off the wire.
602 This value is independent of the truncation amount specified by the filter.
603 .It Li bh_hdrlen
604 The length of the
605 .Nm
606 header, which may not be equal to
607 .\" XXX - not really a function call
608 .Fn sizeof "struct bpf_hdr" .
609 .El
610 .Pp
611 The
612 .Li bh_hdrlen
613 field exists to account for
614 padding between the header and the link level protocol.
615 The purpose here is to guarantee proper alignment of the packet
616 data structures, which is required on alignment sensitive
617 architectures and improves performance on many other architectures.
618 The packet filter insures that the
619 .Li bpf_hdr
620 and the network layer
621 header will be word aligned.
622 Suitable precautions
623 must be taken when accessing the link layer protocol fields on alignment
624 restricted machines.
625 (This is not a problem on an Ethernet, since
626 the type field is a short falling on an even offset,
627 and the addresses are probably accessed in a bytewise fashion).
628 .Pp
629 Additionally, individual packets are padded so that each starts
630 on a word boundary.
631 This requires that an application
632 has some knowledge of how to get from packet to packet.
633 The macro
634 .Dv BPF_WORDALIGN
635 is defined in
636 .In net/bpf.h
637 to facilitate
638 this process.
639 It rounds up its argument to the nearest word aligned value (where a word is
640 .Dv BPF_ALIGNMENT
641 bytes wide).
642 .Pp
643 For example, if
644 .Sq Li p
645 points to the start of a packet, this expression
646 will advance it to the next packet:
647 .Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen)
648 .Pp
649 For the alignment mechanisms to work properly, the
650 buffer passed to
651 .Xr read 2
652 must itself be word aligned.
653 The
654 .Xr malloc 3
655 function
656 will always return an aligned buffer.
657 .Sh FILTER MACHINE
658 A filter program is an array of instructions, with all branches forwardly
659 directed, terminated by a
660 .Em return
661 instruction.
662 Each instruction performs some action on the pseudo-machine state,
663 which consists of an accumulator, index register, scratch memory store,
664 and implicit program counter.
665 .Pp
666 The following structure defines the instruction format:
667 .Bd -literal
668 struct bpf_insn {
669 u_short code;
670 u_char jt;
671 u_char jf;
672 u_long k;
673 };
674 .Ed
675 .Pp
676 The
677 .Li k
678 field is used in different ways by different instructions,
679 and the
680 .Li jt
681 and
682 .Li jf
683 fields are used as offsets
684 by the branch instructions.
685 The opcodes are encoded in a semi-hierarchical fashion.
686 There are eight classes of instructions:
687 .Dv BPF_LD ,
688 .Dv BPF_LDX ,
689 .Dv BPF_ST ,
690 .Dv BPF_STX ,
691 .Dv BPF_ALU ,
692 .Dv BPF_JMP ,
693 .Dv BPF_RET ,
694 and
695 .Dv BPF_MISC .
696 Various other mode and
697 operator bits are or'd into the class to give the actual instructions.
698 The classes and modes are defined in
699 .In net/bpf.h .
700 .Pp
701 Below are the semantics for each defined
702 .Nm
703 instruction.
704 We use the convention that A is the accumulator, X is the index register,
705 P[] packet data, and M[] scratch memory store.
706 P[i:n] gives the data at byte offset
707 .Dq i
708 in the packet,
709 interpreted as a word (n=4),
710 unsigned halfword (n=2), or unsigned byte (n=1).
711 M[i] gives the i'th word in the scratch memory store, which is only
712 addressed in word units.
713 The memory store is indexed from 0 to
714 .Dv BPF_MEMWORDS
715 - 1.
716 .Li k ,
717 .Li jt ,
718 and
719 .Li jf
720 are the corresponding fields in the
721 instruction definition.
722 .Dq len
723 refers to the length of the packet.
724 .Pp
725 .Bl -tag -width BPF_STXx
726 .It Dv BPF_LD
727 These instructions copy a value into the accumulator.
728 The type of the source operand is specified by an
729 .Dq addressing mode
730 and can be a constant
731 .Pq Dv BPF_IMM ,
732 packet data at a fixed offset
733 .Pq Dv BPF_ABS ,
734 packet data at a variable offset
735 .Pq Dv BPF_IND ,
736 the packet length
737 .Pq Dv BPF_LEN ,
738 or a word in the scratch memory store
739 .Pq Dv BPF_MEM .
740 For
741 .Dv BPF_IND
742 and
743 .Dv BPF_ABS ,
744 the data size must be specified as a word
745 .Pq Dv BPF_W ,
746 halfword
747 .Pq Dv BPF_H ,
748 or byte
749 .Pq Dv BPF_B .
750 The semantics of all the recognized
751 .Dv BPF_LD
752 instructions follow.
753 .Pp
754 .Bd -literal
755 BPF_LD+BPF_W+BPF_ABS A <- P[k:4]
756 BPF_LD+BPF_H+BPF_ABS A <- P[k:2]
757 BPF_LD+BPF_B+BPF_ABS A <- P[k:1]
758 BPF_LD+BPF_W+BPF_IND A <- P[X+k:4]
759 BPF_LD+BPF_H+BPF_IND A <- P[X+k:2]
760 BPF_LD+BPF_B+BPF_IND A <- P[X+k:1]
761 BPF_LD+BPF_W+BPF_LEN A <- len
762 BPF_LD+BPF_IMM A <- k
763 BPF_LD+BPF_MEM A <- M[k]
764 .Ed
765 .It Dv BPF_LDX
766 These instructions load a value into the index register.
767 Note that
768 the addressing modes are more restrictive than those of the accumulator loads,
769 but they include
770 .Dv BPF_MSH ,
771 a hack for efficiently loading the IP header length.
772 .Pp
773 .Bd -literal
774 BPF_LDX+BPF_W+BPF_IMM X <- k
775 BPF_LDX+BPF_W+BPF_MEM X <- M[k]
776 BPF_LDX+BPF_W+BPF_LEN X <- len
777 BPF_LDX+BPF_B+BPF_MSH X <- 4*(P[k:1]&0xf)
778 .Ed
779 .It Dv BPF_ST
780 This instruction stores the accumulator into the scratch memory.
781 We do not need an addressing mode since there is only one possibility
782 for the destination.
783 .Pp
784 .Bd -literal
785 BPF_ST M[k] <- A
786 .Ed
787 .It Dv BPF_STX
788 This instruction stores the index register in the scratch memory store.
789 .Pp
790 .Bd -literal
791 BPF_STX M[k] <- X
792 .Ed
793 .It Dv BPF_ALU
794 The alu instructions perform operations between the accumulator and
795 index register or constant, and store the result back in the accumulator.
796 For binary operations, a source mode is required
797 .Dv ( BPF_K
798 or
799 .Dv BPF_X ) .
800 .Pp
801 .Bd -literal
802 BPF_ALU+BPF_ADD+BPF_K A <- A + k
803 BPF_ALU+BPF_SUB+BPF_K A <- A - k
804 BPF_ALU+BPF_MUL+BPF_K A <- A * k
805 BPF_ALU+BPF_DIV+BPF_K A <- A / k
806 BPF_ALU+BPF_AND+BPF_K A <- A & k
807 BPF_ALU+BPF_OR+BPF_K A <- A | k
808 BPF_ALU+BPF_LSH+BPF_K A <- A << k
809 BPF_ALU+BPF_RSH+BPF_K A <- A >> k
810 BPF_ALU+BPF_ADD+BPF_X A <- A + X
811 BPF_ALU+BPF_SUB+BPF_X A <- A - X
812 BPF_ALU+BPF_MUL+BPF_X A <- A * X
813 BPF_ALU+BPF_DIV+BPF_X A <- A / X
814 BPF_ALU+BPF_AND+BPF_X A <- A & X
815 BPF_ALU+BPF_OR+BPF_X A <- A | X
816 BPF_ALU+BPF_LSH+BPF_X A <- A << X
817 BPF_ALU+BPF_RSH+BPF_X A <- A >> X
818 BPF_ALU+BPF_NEG A <- -A
819 .Ed
820 .It Dv BPF_JMP
821 The jump instructions alter flow of control.
822 Conditional jumps
823 compare the accumulator against a constant
824 .Pq Dv BPF_K
825 or the index register
826 .Pq Dv BPF_X .
827 If the result is true (or non-zero),
828 the true branch is taken, otherwise the false branch is taken.
829 Jump offsets are encoded in 8 bits so the longest jump is 256 instructions.
830 However, the jump always
831 .Pq Dv BPF_JA
832 opcode uses the 32 bit
833 .Li k
834 field as the offset, allowing arbitrarily distant destinations.
835 All conditionals use unsigned comparison conventions.
836 .Pp
837 .Bd -literal
838 BPF_JMP+BPF_JA pc += k
839 BPF_JMP+BPF_JGT+BPF_K pc += (A > k) ? jt : jf
840 BPF_JMP+BPF_JGE+BPF_K pc += (A >= k) ? jt : jf
841 BPF_JMP+BPF_JEQ+BPF_K pc += (A == k) ? jt : jf
842 BPF_JMP+BPF_JSET+BPF_K pc += (A & k) ? jt : jf
843 BPF_JMP+BPF_JGT+BPF_X pc += (A > X) ? jt : jf
844 BPF_JMP+BPF_JGE+BPF_X pc += (A >= X) ? jt : jf
845 BPF_JMP+BPF_JEQ+BPF_X pc += (A == X) ? jt : jf
846 BPF_JMP+BPF_JSET+BPF_X pc += (A & X) ? jt : jf
847 .Ed
848 .It Dv BPF_RET
849 The return instructions terminate the filter program and specify the amount
850 of packet to accept (i.e., they return the truncation amount).
851 A return value of zero indicates that the packet should be ignored.
852 The return value is either a constant
853 .Pq Dv BPF_K
854 or the accumulator
855 .Pq Dv BPF_A .
856 .Pp
857 .Bd -literal
858 BPF_RET+BPF_A accept A bytes
859 BPF_RET+BPF_K accept k bytes
860 .Ed
861 .It Dv BPF_MISC
862 The miscellaneous category was created for anything that does not
863 fit into the above classes, and for any new instructions that might need to
864 be added.
865 Currently, these are the register transfer instructions
866 that copy the index register to the accumulator or vice versa.
867 .Pp
868 .Bd -literal
869 BPF_MISC+BPF_TAX X <- A
870 BPF_MISC+BPF_TXA A <- X
871 .Ed
872 .El
873 .Pp
874 The
875 .Nm
876 interface provides the following macros to facilitate
877 array initializers:
878 .Fn BPF_STMT opcode operand
879 and
880 .Fn BPF_JUMP opcode operand true_offset false_offset .
881 .Sh FILES
882 .Bl -tag -compact -width /dev/bpf
883 .It Pa /dev/bpf
884 the packet filter device
885 .El
886 .Sh EXAMPLES
887 The following filter is taken from the Reverse ARP Daemon.
888 It accepts only Reverse ARP requests.
889 .Bd -literal
890 struct bpf_insn insns[] = {
891 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
892 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3),
893 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
894 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1),
895 BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) +
896 sizeof(struct ether_header)),
897 BPF_STMT(BPF_RET+BPF_K, 0),
898 };
899 .Ed
900 .Pp
901 This filter accepts only IP packets between host 128.3.112.15 and
902 128.3.112.35.
903 .Bd -literal
904 struct bpf_insn insns[] = {
905 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
906 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8),
907 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26),
908 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2),
909 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
910 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4),
911 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3),
912 BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30),
913 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1),
914 BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
915 BPF_STMT(BPF_RET+BPF_K, 0),
916 };
917 .Ed
918 .Pp
919 Finally, this filter returns only TCP finger packets.
920 We must parse the IP header to reach the TCP header.
921 The
922 .Dv BPF_JSET
923 instruction
924 checks that the IP fragment offset is 0 so we are sure
925 that we have a TCP header.
926 .Bd -literal
927 struct bpf_insn insns[] = {
928 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12),
929 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10),
930 BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23),
931 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8),
932 BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20),
933 BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0),
934 BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14),
935 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14),
936 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0),
937 BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16),
938 BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1),
939 BPF_STMT(BPF_RET+BPF_K, (u_int)-1),
940 BPF_STMT(BPF_RET+BPF_K, 0),
941 };
942 .Ed
943 .Sh SEE ALSO
944 .Xr tcpdump 1 ,
945 .Xr ioctl 2 ,
946 .Xr kqueue 2 ,
947 .Xr poll 2 ,
948 .Xr select 2 ,
949 .Xr byteorder 3 ,
950 .Xr ng_bpf 4 ,
951 .Xr bpf 9
952 .Rs
953 .%A McCanne, S.
954 .%A Jacobson V.
955 .%T "An efficient, extensible, and portable network monitor"
956 .Re
957 .Sh HISTORY
958 The Enet packet filter was created in 1980 by Mike Accetta and
959 Rick Rashid at Carnegie-Mellon University.
960 Jeffrey Mogul, at
961 Stanford, ported the code to
962 .Bx
963 and continued its development from
964 1983 on.
965 Since then, it has evolved into the Ultrix Packet Filter at
966 .Tn DEC ,
967 a
968 .Tn STREAMS
969 .Tn NIT
970 module under
971 .Tn SunOS 4.1 ,
972 and
973 .Tn BPF .
974 .Sh AUTHORS
975 .An -nosplit
976 .An Steven McCanne ,
977 of Lawrence Berkeley Laboratory, implemented BPF in
978 Summer 1990.
979 Much of the design is due to
980 .An Van Jacobson .
981 .Pp
982 Support for zero-copy buffers was added by
983 .An Robert N. M. Watson
984 under contract to Seccuris Inc.
985 .Sh BUGS
986 The read buffer must be of a fixed size (returned by the
987 .Dv BIOCGBLEN
988 ioctl).
989 .Pp
990 A file that does not request promiscuous mode may receive promiscuously
991 received packets as a side effect of another file requesting this
992 mode on the same hardware interface.
993 This could be fixed in the kernel with additional processing overhead.
994 However, we favor the model where
995 all files must assume that the interface is promiscuous, and if
996 so desired, must utilize a filter to reject foreign packets.
997 .Pp
998 Data link protocols with variable length headers are not currently supported.
999 .Pp
1000 The
1001 .Dv SEESENT ,
1002 .Dv DIRECTION ,
1003 and
1004 .Dv FEEDBACK
1005 settings have been observed to work incorrectly on some interface
1006 types, including those with hardware loopback rather than software loopback,
1007 and point-to-point interfaces.
1008 They appear to function correctly on a
1009 broad range of Ethernet-style interfaces.