Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
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. | |
19 | .\" | |
20 | .\" This document is derived in part from the enet man page (enet.4) | |
21 | .\" distributed with 4.3BSD Unix. | |
22 | .\" | |
23 | .TH BPF 4 "23 May 1991" | |
24 | .SH NAME | |
25 | bpf \- Berkeley Packet Filter | |
26 | .SH SYNOPSIS | |
27 | .B "pseudo-device bpfilter 16" | |
28 | .SH DESCRIPTION | |
29 | The Berkeley Packet Filter | |
30 | provides a raw interface to data link layers in a protocol | |
31 | independent fashion. | |
32 | All packets on the network, even those destined for other hosts, | |
33 | are accessible through this mechanism. | |
34 | .PP | |
35 | The packet filter appears as a character special device, | |
36 | .I /dev/bpf0, /dev/bpf1, | |
37 | etc. | |
38 | After opening the device, the file descriptor must be bound to a | |
39 | specific network interface with the BIOSETIF ioctl. | |
40 | A given interface can be shared be multiple listeners, and the filter | |
41 | underlying each descriptor will see an identical packet stream. | |
42 | The total number of open | |
43 | files is limited to the value given in the kernel configuration; the | |
44 | example given in the SYNOPSIS above sets the limit to 16. | |
45 | .PP | |
46 | A separate device file is required for each minor device. | |
47 | If a file is in use, the open will fail and | |
48 | .I errno | |
49 | will be set to EBUSY. | |
50 | .PP | |
51 | Associated with each open instance of a | |
52 | .I bpf | |
53 | file is a user-settable packet filter. | |
54 | Whenever a packet is received by an interface, | |
55 | all file descriptors listening on that interface apply their filter. | |
56 | Each descriptor that accepts the packet receives its own copy. | |
57 | .PP | |
58 | Reads from these files return the next group of packets | |
59 | that have matched the filter. | |
60 | To improve performance, the buffer passed to read must be | |
61 | the same size as the buffers used internally by | |
62 | .I bpf. | |
63 | This size is returned by the BIOCGBLEN ioctl (see below), and under | |
64 | BSD, can be set with BIOCSBLEN. | |
65 | Note that an individual packet larger than this size is necessarily | |
66 | truncated. | |
67 | .PP | |
68 | The packet filter will support any link level protocol that has fixed length | |
69 | headers. Currently, only Ethernet, SLIP and PPP drivers have been | |
70 | modified to interact with | |
71 | .I bpf. | |
72 | .PP | |
73 | Since packet data is in network byte order, applications should use the | |
74 | .I byteorder(3n) | |
75 | macros to extract multi-byte values. | |
76 | .PP | |
77 | A packet can be sent out on the network by writing to a | |
78 | .I bpf | |
79 | file descriptor. The writes are unbuffered, meaning only one | |
80 | packet can be processed per write. | |
81 | Currently, only writes to Ethernets and SLIP links are supported. | |
82 | .SH IOCTLS | |
83 | The | |
84 | .I ioctl | |
85 | command codes below are defined in <net/bpf.h>. All commands require | |
86 | these includes: | |
87 | .ft B | |
88 | .nf | |
89 | ||
90 | #include <sys/types.h> | |
91 | #include <sys/time.h> | |
92 | #include <sys/ioctl.h> | |
93 | #include <net/bpf.h> | |
94 | ||
95 | .fi | |
96 | .ft R | |
97 | Additionally, BIOCGETIF and BIOCSETIF require \fB<net/if.h>\fR. | |
98 | ||
99 | In addition to FIONREAD and SIOCGIFADDR, the following commands | |
100 | may be applied to any open | |
101 | .I bpf | |
102 | file. | |
103 | The (third) argument to the | |
104 | .I ioctl | |
105 | should be a pointer to the type indicated. | |
106 | .TP 10 | |
107 | .B BIOCGBLEN (u_int) | |
108 | Returns the required buffer length for reads on | |
109 | .I bpf | |
110 | files. | |
111 | .TP 10 | |
112 | .B BIOCSBLEN (u_int) | |
113 | Sets the buffer length for reads on | |
114 | .I bpf | |
115 | files. The buffer must be set before the file is attached to an interface | |
116 | with BIOCSETIF. | |
117 | If the requested buffer size cannot be accomodated, the closest | |
118 | allowable size will be set and returned in the argument. | |
119 | A read call will result in EIO if it is passed a buffer that is not this size. | |
120 | .TP 10 | |
121 | .B BIOCGDLT (u_int) | |
122 | Returns the type of the data link layer underyling the attached interface. | |
123 | EINVAL is returned if no interface has been specified. | |
124 | The device types, prefixed with ``DLT_'', are defined in <net/bpf.h>. | |
125 | .TP 10 | |
126 | .B BIOCPROMISC | |
127 | Forces the interface into promiscuous mode. | |
128 | All packets, not just those destined for the local host, are processed. | |
129 | Since more than one file can be listening on a given interface, | |
130 | a listener that opened its interface non-promiscuously may receive | |
131 | packets promiscuously. This problem can be remedied with an | |
132 | appropriate filter. | |
133 | .IP | |
134 | The interface remains in promiscuous mode until all files listening | |
135 | promiscuously are closed. | |
136 | .TP 10 | |
137 | .B BIOCFLUSH | |
138 | Flushes the buffer of incoming packets, | |
139 | and resets the statistics that are returned by BIOCGSTATS. | |
140 | .TP 10 | |
141 | .B BIOCGETIF (struct ifreq) | |
142 | Returns the name of the hardware interface that the file is listening on. | |
143 | The name is returned in the if_name field of | |
144 | .I ifr. | |
145 | All other fields are undefined. | |
146 | .TP 10 | |
147 | .B BIOCSETIF (struct ifreq) | |
148 | Sets the hardware interface associate with the file. This | |
149 | command must be performed before any packets can be read. | |
150 | The device is indicated by name using the | |
151 | .I if_name | |
152 | field of the | |
153 | .I ifreq. | |
154 | Additionally, performs the actions of BIOCFLUSH. | |
155 | .TP 10 | |
156 | .B BIOCSRTIMEOUT, BIOCGRTIMEOUT (struct timeval) | |
157 | Set or get the read timeout parameter. | |
158 | The | |
159 | .I timeval | |
160 | specifies the length of time to wait before timing | |
161 | out on a read request. | |
162 | This parameter is initialized to zero by | |
163 | .IR open(2), | |
164 | indicating no timeout. | |
165 | .TP 10 | |
166 | .B BIOCGSTATS (struct bpf_stat) | |
167 | Returns the following structure of packet statistics: | |
168 | .ft B | |
169 | .nf | |
170 | ||
171 | struct bpf_stat { | |
172 | u_int bs_recv; | |
173 | u_int bs_drop; | |
174 | }; | |
175 | .fi | |
176 | .ft R | |
177 | .IP | |
178 | The fields are: | |
179 | .RS | |
180 | .TP 15 | |
181 | .I bs_recv | |
182 | the number of packets received by the descriptor since opened or reset | |
183 | (including any buffered since the last read call); | |
184 | and | |
185 | .TP | |
186 | .I bs_drop | |
187 | the number of packets which were accepted by the filter but dropped by the | |
188 | kernel because of buffer overflows | |
189 | (i.e., the application's reads aren't keeping up with the packet traffic). | |
190 | .RE | |
191 | .TP 10 | |
192 | .B BIOCIMMEDIATE (u_int) | |
193 | Enable or disable ``immediate mode'', based on the truth value of the argument. | |
194 | When immediate mode is enabled, reads return immediately upon packet | |
195 | reception. Otherwise, a read will block until either the kernel buffer | |
196 | becomes full or a timeout occurs. | |
197 | This is useful for programs like | |
198 | .I rarpd(8c), | |
199 | which must respond to messages in real time. | |
200 | The default for a new file is off. | |
201 | .TP 10 | |
202 | .B BIOCSETF (struct bpf_program) | |
203 | Sets the filter program used by the kernel to discard uninteresting | |
204 | packets. An array of instructions and its length is passed in using | |
205 | the following structure: | |
206 | .ft B | |
207 | .nf | |
208 | ||
209 | struct bpf_program { | |
210 | int bf_len; | |
211 | struct bpf_insn *bf_insns; | |
212 | }; | |
213 | .fi | |
214 | .ft R | |
215 | .IP | |
216 | The filter program is pointed to by the | |
217 | .I bf_insns | |
218 | field while its length in units of `struct bpf_insn' is given by the | |
219 | .I bf_len | |
220 | field. | |
221 | Also, the actions of BIOCFLUSH are performed. | |
222 | .IP | |
223 | See section \fBFILTER MACHINE\fP for an explanation of the filter language. | |
224 | .TP 10 | |
225 | .B BIOCVERSION (struct bpf_version) | |
226 | Returns the major and minor version numbers of the filter languange currently | |
227 | recognized by the kernel. Before installing a filter, applications must check | |
228 | that the current version is compatible with the running kernel. Version | |
229 | numbers are compatible if the major numbers match and the application minor | |
230 | is less than or equal to the kernel minor. The kernel version number is | |
231 | returned in the following structure: | |
232 | .ft B | |
233 | .nf | |
234 | ||
235 | struct bpf_version { | |
236 | u_short bv_major; | |
237 | u_short bv_minor; | |
238 | }; | |
239 | .fi | |
240 | .ft R | |
241 | .IP | |
242 | The current version numbers are given by | |
243 | .B BPF_MAJOR_VERSION | |
244 | and | |
245 | .B BPF_MINOR_VERSION | |
246 | from <net/bpf.h>. | |
247 | An incompatible filter | |
248 | may result in undefined behavior (most likely, an error returned by | |
249 | .I ioctl() | |
250 | or haphazard packet matching). | |
251 | .SH BPF HEADER | |
252 | The following structure is prepended to each packet returned by | |
253 | .I read(2): | |
254 | .in 15 | |
255 | .ft B | |
256 | .nf | |
257 | ||
258 | struct bpf_hdr { | |
259 | struct timeval bh_tstamp; | |
260 | u_long bh_caplen; | |
261 | u_long bh_datalen; | |
262 | u_short bh_hdrlen; | |
263 | }; | |
264 | .fi | |
265 | .ft R | |
266 | .in -15 | |
267 | .PP | |
268 | The fields, whose values are stored in host order, and are: | |
269 | .TP 15 | |
270 | .I bh_tstamp | |
271 | The time at which the packet was processed by the packet filter. | |
272 | .TP | |
273 | .I bh_caplen | |
274 | The length of the captured portion of the packet. This is the minimum of | |
275 | the truncation amount specified by the filter and the length of the packet. | |
276 | .TP | |
277 | .I bh_datalen | |
278 | The length of the packet off the wire. | |
279 | This value is independent of the truncation amount specified by the filter. | |
280 | .TP | |
281 | .I bh_hdrlen | |
282 | The length of the BPF header, which may not be equal to | |
283 | .I sizeof(struct bpf_hdr). | |
284 | .RE | |
285 | .PP | |
286 | The | |
287 | .I bh_hdrlen | |
288 | field exists to account for | |
289 | padding between the header and the link level protocol. | |
290 | The purpose here is to guarantee proper alignment of the packet | |
291 | data structures, which is required on alignment sensitive | |
292 | architectures and and improves performance on many other architectures. | |
293 | The packet filter insures that the | |
294 | .I bpf_hdr | |
295 | and the \fInetwork layer\fR header will be word aligned. Suitable precautions | |
296 | must be taken when accessing the link layer protocol fields on alignment | |
297 | restricted machines. (This isn't a problem on an Ethernet, since | |
298 | the type field is a short falling on an even offset, | |
299 | and the addresses are probably accessed in a bytewise fashion). | |
300 | .PP | |
301 | Additionally, individual packets are padded so that each starts | |
302 | on a word boundary. This requires that an application | |
303 | has some knowledge of how to get from packet to packet. | |
304 | The macro BPF_WORDALIGN is defined in <net/bpf.h> to facilitate | |
305 | this process. It rounds up its argument | |
306 | to the nearest word aligned value (where a word is BPF_ALIGNMENT bytes wide). | |
307 | .PP | |
308 | For example, if `p' points to the start of a packet, this expression | |
309 | will advance it to the next packet: | |
310 | .sp | |
311 | .RS | |
312 | .ce 1 | |
313 | .nf | |
314 | p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) | |
315 | .fi | |
316 | .RE | |
317 | .PP | |
318 | For the alignment mechanisms to work properly, the | |
319 | buffer passed to | |
320 | .I read(2) | |
321 | must itself be word aligned. | |
322 | .I malloc(3) | |
323 | will always return an aligned buffer. | |
324 | .ft R | |
325 | .SH FILTER MACHINE | |
326 | A filter program is an array of instructions, with all branches forwardly | |
327 | directed, terminated by a \fBreturn\fP instruction. | |
328 | Each instruction performs some action on the pseudo-machine state, | |
329 | which consists of an accumulator, index register, scratch memory store, | |
330 | and implicit program counter. | |
331 | ||
332 | The following structure defines the instruction format: | |
333 | .RS | |
334 | .ft B | |
335 | .nf | |
336 | ||
337 | struct bpf_insn { | |
338 | u_short code; | |
339 | u_char jt; | |
340 | u_char jf; | |
341 | long k; | |
342 | }; | |
343 | .fi | |
344 | .ft R | |
345 | .RE | |
346 | ||
347 | The \fIk\fP field is used in differnet ways by different insutructions, | |
348 | and the \fIjt\fP and \fIjf\fP fields are used as offsets | |
349 | by the branch intructions. | |
350 | The opcodes are encoded in a semi-hierarchical fashion. | |
351 | There are eight classes of intructions: BPF_LD, BPF_LDX, BPF_ST, BPF_STX, | |
352 | BPF_ALU, BPF_JMP, BPF_RET, and BPF_MISC. Various other mode and | |
353 | operator bits are or'd into the class to give the actual instructions. | |
354 | The classes and modes are defined in <net/bpf.h>. | |
355 | ||
356 | Below are the semantics for each defined BPF instruction. | |
357 | We use the convention that A is the accumulator, X is the index register, | |
358 | P[] packet data, and M[] scratch memory store. | |
359 | P[i:n] gives the data at byte offset ``i'' in the packet, | |
360 | interpreted as a word (n=4), | |
361 | unsigned halfword (n=2), or unsigned byte (n=1). | |
362 | M[i] gives the i'th word in the scratch memory store, which is only | |
363 | addressed in word units. The memory store is indexed from 0 to BPF_MEMWORDS-1. | |
364 | \fIk\fP, \fIjt\fP, and \fIjf\fP are the corresponding fields in the | |
365 | instruction definition. ``len'' refers to the length of the packet. | |
366 | ||
367 | .TP 10 | |
368 | .B BPF_LD | |
369 | These instructions copy a value into the accumulator. The type of the | |
370 | source operand is specified by an ``addressing mode'' and can be | |
371 | a constant (\fBBPF_IMM\fP), packet data at a fixed offset (\fBBPF_ABS\fP), | |
372 | packet data at a variable offset (\fBBPF_IND\fP), the packet length | |
373 | (\fBBPF_LEN\fP), | |
374 | or a word in the scratch memory store (\fBBPF_MEM\fP). | |
375 | For \fBBPF_IND\fP and \fBBPF_ABS\fP, the data size must be specified as a word | |
376 | (\fBBPF_W\fP), halfword (\fBBPF_H\fP), or byte (\fBBPF_B\fP). | |
377 | The semantics of all the recognized BPF_LD instructions follow. | |
378 | ||
379 | .RS | |
380 | .TP 30 | |
381 | .B BPF_LD+BPF_W+BPF_ABS | |
382 | A <- P[k:4] | |
383 | .TP | |
384 | .B BPF_LD+BPF_H+BPF_ABS | |
385 | A <- P[k:2] | |
386 | .TP | |
387 | .B BPF_LD+BPF_B+BPF_ABS | |
388 | A <- P[k:1] | |
389 | .TP | |
390 | .B BPF_LD+BPF_W+BPF_IND | |
391 | A <- P[X+k:4] | |
392 | .TP | |
393 | .B BPF_LD+BPF_H+BPF_IND | |
394 | A <- P[X+k:2] | |
395 | .TP | |
396 | .B BPF_LD+BPF_B+BPF_IND | |
397 | A <- P[X+k:1] | |
398 | .TP | |
399 | .B BPF_LD+BPF_W+BPF_LEN | |
400 | A <- len | |
401 | .TP | |
402 | .B BPF_LD+BPF_IMM | |
403 | A <- k | |
404 | .TP | |
405 | .B BPF_LD+BPF_MEM | |
406 | A <- M[k] | |
407 | .RE | |
408 | ||
409 | .TP 10 | |
410 | .B BPF_LDX | |
411 | These instructions load a value into the index register. Note that | |
412 | the addressing modes are more retricted than those of the accumulator loads, | |
413 | but they include | |
414 | .B BPF_MSH, | |
415 | a hack for efficiently loading the IP header length. | |
416 | .RS | |
417 | .TP 30 | |
418 | .B BPF_LDX+BPF_W+BPF_IMM | |
419 | X <- k | |
420 | .TP | |
421 | .B BPF_LDX+BPF_W+BPF_MEM | |
422 | X <- M[k] | |
423 | .TP | |
424 | .B BPF_LDX+BPF_W+BPF_LEN | |
425 | X <- len | |
426 | .TP | |
427 | .B BPF_LDX+BPF_B+BPF_MSH | |
428 | X <- 4*(P[k:1]&0xf) | |
429 | .RE | |
430 | ||
431 | .TP 10 | |
432 | .B BPF_ST | |
433 | This instruction stores the accumulator into the scratch memory. | |
434 | We do not need an addressing mode since there is only one possibility | |
435 | for the destination. | |
436 | .RS | |
437 | .TP 30 | |
438 | .B BPF_ST | |
439 | M[k] <- A | |
440 | .RE | |
441 | ||
442 | .TP 10 | |
443 | .B BPF_STX | |
444 | This instruction stores the index register in the scratch memory store. | |
445 | .RS | |
446 | .TP 30 | |
447 | .B BPF_STX | |
448 | M[k] <- X | |
449 | .RE | |
450 | ||
451 | .TP 10 | |
452 | .B BPF_ALU | |
453 | The alu instructions perform operations between the accumulator and | |
454 | index register or constant, and store the result back in the accumulator. | |
455 | For binary operations, a source mode is required (\fBBPF_K\fP or | |
456 | \fBBPF_X\fP). | |
457 | .RS | |
458 | .TP 30 | |
459 | .B BPF_ALU+BPF_ADD+BPF_K | |
460 | A <- A + k | |
461 | .TP | |
462 | .B BPF_ALU+BPF_SUB+BPF_K | |
463 | A <- A - k | |
464 | .TP | |
465 | .B BPF_ALU+BPF_MUL+BPF_K | |
466 | A <- A * k | |
467 | .TP | |
468 | .B BPF_ALU+BPF_DIV+BPF_K | |
469 | A <- A / k | |
470 | .TP | |
471 | .B BPF_ALU+BPF_AND+BPF_K | |
472 | A <- A & k | |
473 | .TP | |
474 | .B BPF_ALU+BPF_OR+BPF_K | |
475 | A <- A | k | |
476 | .TP | |
477 | .B BPF_ALU+BPF_LSH+BPF_K | |
478 | A <- A << k | |
479 | .TP | |
480 | .B BPF_ALU+BPF_RSH+BPF_K | |
481 | A <- A >> k | |
482 | .TP | |
483 | .B BPF_ALU+BPF_ADD+BPF_X | |
484 | A <- A + X | |
485 | .TP | |
486 | .B BPF_ALU+BPF_SUB+BPF_X | |
487 | A <- A - X | |
488 | .TP | |
489 | .B BPF_ALU+BPF_MUL+BPF_X | |
490 | A <- A * X | |
491 | .TP | |
492 | .B BPF_ALU+BPF_DIV+BPF_X | |
493 | A <- A / X | |
494 | .TP | |
495 | .B BPF_ALU+BPF_AND+BPF_X | |
496 | A <- A & X | |
497 | .TP | |
498 | .B BPF_ALU+BPF_OR+BPF_X | |
499 | A <- A | X | |
500 | .TP | |
501 | .B BPF_ALU+BPF_LSH+BPF_X | |
502 | A <- A << X | |
503 | .TP | |
504 | .B BPF_ALU+BPF_RSH+BPF_X | |
505 | A <- A >> X | |
506 | .TP | |
507 | .B BPF_ALU+BPF_NEG | |
508 | A <- -A | |
509 | .RE | |
510 | ||
511 | .TP 10 | |
512 | .B BPF_JMP | |
513 | The jump instructions alter flow of control. Conditional jumps | |
514 | compare the accumulator against a constant (\fBBPF_K\fP) or | |
515 | the index register (\fBBPF_X\fP). If the result is true (or non-zero), | |
516 | the true branch is taken, otherwise the false branch is taken. | |
517 | Jump offsets are encoded in 8 bits so the longest jump is 256 instructions. | |
518 | However, the jump always (\fBBPF_JA\fP) opcode uses the 32 bit \fIk\fP | |
519 | field as the offset, allowing arbitrarily distant destinations. | |
520 | All conditionals use unsigned comparison conventions. | |
521 | .RS | |
522 | .TP 30 | |
523 | .B BPF_JMP+BPF_JA | |
524 | pc += k | |
525 | .TP | |
526 | .B BPF_JMP+BPF_JGT+BPF_K | |
527 | pc += (A > k) ? jt : jf | |
528 | .TP | |
529 | .B BPF_JMP+BPF_JGE+BPF_K | |
530 | pc += (A >= k) ? jt : jf | |
531 | .TP | |
532 | .B BPF_JMP+BPF_JEQ+BPF_K | |
533 | pc += (A == k) ? jt : jf | |
534 | .TP | |
535 | .B BPF_JMP+BPF_JSET+BPF_K | |
536 | pc += (A & k) ? jt : jf | |
537 | .TP | |
538 | .B BPF_JMP+BPF_JGT+BPF_X | |
539 | pc += (A > X) ? jt : jf | |
540 | .TP | |
541 | .B BPF_JMP+BPF_JGE+BPF_X | |
542 | pc += (A >= X) ? jt : jf | |
543 | .TP | |
544 | .B BPF_JMP+BPF_JEQ+BPF_X | |
545 | pc += (A == X) ? jt : jf | |
546 | .TP | |
547 | .B BPF_JMP+BPF_JSET+BPF_X | |
548 | pc += (A & X) ? jt : jf | |
549 | .RE | |
550 | .TP 10 | |
551 | .B BPF_RET | |
552 | The return instructions terminate the filter program and specify the amount | |
553 | of packet to accept (i.e., they return the truncation amount). A return | |
554 | value of zero indicates that the packet should be ignored. | |
555 | The return value is either a constant (\fBBPF_K\fP) or the accumulator | |
556 | (\fBBPF_A\fP). | |
557 | .RS | |
558 | .TP 30 | |
559 | .B BPF_RET+BPF_A | |
560 | accept A bytes | |
561 | .TP | |
562 | .B BPF_RET+BPF_K | |
563 | accept k bytes | |
564 | .RE | |
565 | .TP 10 | |
566 | .B BPF_MISC | |
567 | The miscellaneous category was created for anything that doesn't | |
568 | fit into the above classes, and for any new instructions that might need to | |
569 | be added. Currently, these are the register transfer intructions | |
570 | that copy the index register to the accumulator or vice versa. | |
571 | .RS | |
572 | .TP 30 | |
573 | .B BPF_MISC+BPF_TAX | |
574 | X <- A | |
575 | .TP | |
576 | .B BPF_MISC+BPF_TXA | |
577 | A <- X | |
578 | .RE | |
579 | .PP | |
580 | The BPF interface provides the following macros to facilitate | |
581 | array initializers: | |
582 | .RS | |
583 | \fBBPF_STMT\fI(opcode, operand)\fR | |
584 | .br | |
585 | and | |
586 | .br | |
587 | \fBBPF_JUMP\fI(opcode, operand, true_offset, false_offset)\fR | |
588 | .RE | |
589 | .PP | |
590 | .SH EXAMPLES | |
591 | The following filter is taken from the Reverse ARP Daemon. It accepts | |
592 | only Reverse ARP requests. | |
593 | .RS | |
594 | .nf | |
595 | ||
596 | struct bpf_insn insns[] = { | |
597 | BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), | |
598 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), | |
599 | BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), | |
600 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1), | |
601 | BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + | |
602 | sizeof(struct ether_header)), | |
603 | BPF_STMT(BPF_RET+BPF_K, 0), | |
604 | }; | |
605 | .fi | |
606 | .RE | |
607 | .PP | |
608 | This filter accepts only IP packets between host 128.3.112.15 and | |
609 | 128.3.112.35. | |
610 | .RS | |
611 | .nf | |
612 | ||
613 | struct bpf_insn insns[] = { | |
614 | BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), | |
615 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8), | |
616 | BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 26), | |
617 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), | |
618 | BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 30), | |
619 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), | |
620 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), | |
621 | BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 30), | |
622 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), | |
623 | BPF_STMT(BPF_RET+BPF_K, (u_int)-1), | |
624 | BPF_STMT(BPF_RET+BPF_K, 0), | |
625 | }; | |
626 | .fi | |
627 | .RE | |
628 | .PP | |
629 | Finally, this filter returns only TCP finger packets. We must parse | |
630 | the IP header to reach the TCP header. The \fBBPF_JSET\fP instruction | |
631 | checks that the IP fragment offset is 0 so we are sure | |
632 | that we have a TCP header. | |
633 | .RS | |
634 | .nf | |
635 | ||
636 | struct bpf_insn insns[] = { | |
637 | BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), | |
638 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), | |
639 | BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), | |
640 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), | |
641 | BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), | |
642 | BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), | |
643 | BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), | |
644 | BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), | |
645 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), | |
646 | BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), | |
647 | BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), | |
648 | BPF_STMT(BPF_RET+BPF_K, (u_int)-1), | |
649 | BPF_STMT(BPF_RET+BPF_K, 0), | |
650 | }; | |
651 | .fi | |
652 | .RE | |
653 | .SH SEE ALSO | |
654 | tcpdump(1) | |
655 | .LP | |
656 | McCanne, S., Jacobson V., | |
657 | .RI ` "An efficient, extensible, and portable network monitor" ' | |
658 | .SH FILES | |
659 | /dev/bpf0, /dev/bpf1, ... | |
660 | .SH BUGS | |
661 | The read buffer must be of a fixed size (returned by the BIOCGBLEN ioctl). | |
662 | .PP | |
663 | A file that does not request promiscuous mode may receive promiscuously | |
664 | received packets as a side effect of another file requesting this | |
665 | mode on the same hardware interface. This could be fixed in the kernel | |
666 | with additional processing overhead. However, we favor the model where | |
667 | all files must assume that the interface is promiscuous, and if | |
668 | so desired, must utilize a filter to reject foreign packets. | |
669 | .PP | |
670 | Data link protocols with variable length headers are not currently supported. | |
671 | .PP | |
672 | Under SunOS, if a BPF application reads more than 2^31 bytes of | |
673 | data, read will fail in EINVAL. You can either fix the bug in SunOS, | |
674 | or lseek to 0 when read fails for this reason. | |
675 | .SH HISTORY | |
676 | .PP | |
677 | The Enet packet filter was created in 1980 by Mike Accetta and | |
678 | Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at | |
679 | Stanford, ported the code to BSD and continued its development from | |
680 | 1983 on. Since then, it has evolved into the Ultrix Packet Filter | |
681 | at DEC, a STREAMS NIT module under SunOS 4.1, and BPF. | |
682 | .SH AUTHORS | |
683 | .PP | |
684 | Steven McCanne, of Lawrence Berkeley Laboratory, implemented BPF in | |
685 | Summer 1990. Much of the design is due to Van Jacobson. |