1Sun Jan 26 20:23:52 PST 1992
2
3This directory contains the files necessary to install the
4Berkeley Packet Filter (BPF) in a BSD (or BSD-like) kernel.
5BPF is derived from the Stanford/CMU enet packet filter that was
6distributed with 4.3BSD. We have made no efforts to keep the two
7interfaces compatible.
8
9BPF has been tested on hp300's running BSD Tahoe/Reno, Sparcstations
10running SunOS 4.1, Sparcstations running BSD Reno, and Sun 3's running
11SunOS 3.5. We have configured it into the BSD Lance ethernet driver,
12the Sun LANCE and Intel drivers, and our (soon to be released) SLIP driver
13(BSD, SunOS 3.5 and 4.1). The modified BSD driver is included in this
14distribution, however, the Sun drivers cannot be made available. If
15you have SunOS source, you can apply the context diff in
16sunif/if_le.c-sunos4.1-diff to the 4.1 lance driver (net/if_le.c).
17
18There are patches for various flavors of loopback interface in
19{net,netinet}/if_loop.c*.
20
21Note that there have been quite a few changes since the version released
22with tcpdump-2.0. If you have modified drivers, you will need to update
23them. In particalar, the calling sequence for bpfattach() has changed.
24
25Follow these steps to install bpf into a new kernel:
26
27(1) Add the following line to your config file. The parameter
28 is an upper bound for two things: the number of simultaneuous open
29 files, and the number of hardware interfaces attached to BPF.
30
31pseudo-device bpfilter 16
32
33 Add these lines to conf/files:
34
35net/bpf.c optional bpfilter
36net/bpf_filter.c optional bpfilter
37
38(2) Copy these files into /sys/net:
39
40bpf/net/bpf.c
41bpf/net/bpf_filter.c
42bpf/net/bpf.h
43bpf/net/bpfcodes.h
44bpf/net/bpfdesc.h
45
46(3) Install bpf.h and bpfcodes.h in /usr/include/net.
47
48(4) Add an entry for BPF in the character device switch, `cdevsw',
49 defined in /sys/{machine}/conf.c (where {machine} can be sun,
50 hp300, etc.) This array contains entry points to the device
51 driver routines so the kernel can map major device file numbers
52 to the appropriate functions. You need to add bpfopen(), bpfclose(),
53 bpfread(), bpfwrite(), bpfioctl(), and bpfselect().
54
55 Create the special device files /dev/bpf0, /dev/bpf1, etc.
56 Make sure the major device number correpsonds to the entry in
57 cdevsw; the minor device number should be the same as the
58 trailing digit of the file name.
59
60 Access to the packet interface is controlled by the permissions
61 on the device files. We recommend that access be restricted to
62 group `wheel'. For example,
63
64 /etc/mknod /dev/bpf0 c {major dev} 0
65 /etc/mknod /dev/bpf1 c {major dev} 1
66 /etc/mknod /dev/bpf2 c {major dev} 2
67 ...
68 chmod 640 /dev/bpf*
69 chgrp wheel /dev/bpf*
70
71 The highest allowable minor device number corresponds to the
72 number given in the "pseudo-device" config line (less one).
73
74(5) Modify the link level device drivers to interact with BPF.
75 hpdev/if_le.c is an example driver for a LANCE Ethernet
76 interface on an hp300 series machine. [If this is your
77 setup, go to (6).]
78
79 If you're starting from scratch, this is not too difficult.
80 All the BPF mods to hpdev/if_le.c are encapsulated with
81 `#ifdef NBPFILTER > 0', so they're easy to spot. You need to:
82
83 a) Add includes for bpfilter.h and ../net/bpf.h.
84
85 b) Add a caddr_t to the softc. This is the magic cookie
86 that tells bpf_tap() who is talking to it.
87
88 c) Modify the attach routine to set up some device parameters
89 [see hpdev/if_le.c:leattach()] and call bpfattach().
90
91 d) Make sure the driver can handle promiscuous operation,
92 and that the routine ifpromisc() exists. Ifpromisc()
93 takes an ifp and a flag saying whether to enter or leave
94 promiscuous operation. It should reference count the
95 calls and take actions only the last `off' or first `on'.
96 The action it should take is setting/clearing the IFF_PROMISC
97 bit, and calling the driver's SIOCIFFLAGS ioctl. The
98 driver should inspect the IFF_PROMISC bit and do the right
99 thing.
100
101 d) Add calls to bpf_tap() at the following places:
102
103 i. Right after the device interrupts and the packet is
104 in contiguous interface memory. This is before
105 the packet has been copied in to mbufs.
106
107 ii. Right before the packet is transmitted.
108 This is after the packet has been copied out of mbufs.
109
110 If the packet never exists in contiguous memory
111 (some interfaces can follow chains), you need to
112 call bpf_mtap instead.
113
114 To minimize the cost of the filter when there are no
115 listeners, bpf_tap() is only called when the magic
116 cookie in the driver's softc is nonzero. (BPF will
117 set and clear it.)
118
119 Because BPF can force an interface into promiscuous mode,
120 you want to check that incoming packets are destined for
121 this host or are broadcast/multicast. If neither is the
122 case, the packet should be tossed (after calling bpf_tap()).
123 This check only needs to be done when there are listeners.
124
125(6) BPF calls the routine ifpromisc() to put an interface into
126 promiscuous mode. SunOS 4.1 provides this routine; we have
127 provided our versions for SunOS 3.5 and BSD in the files
128 bpf/net/if-sunos3.c and bpf/net/if-bsd.c. Merge this code
129 into net/if.c. Additionally, the `if_pcount' integer field
130 must be added to the `struct ifnet' in net/if.h.
131
132(7) That's it. Run config, make depend, and make, and you're ready to go.
133
134
135All the code in these directories is subject to the standard Berkeley
136network software copyright:
137
138 Copyright (c) 1990, 1991, 1992 The Regents of the University of California.
139 All rights reserved.
140
141 Redistribution and use in source and binary forms, with or without
142 modification, are permitted provided that: (1) source code distributions
143 retain the above copyright notice and this paragraph in its entirety, (2)
144 distributions including binary code include the above copyright notice and
145 this paragraph in its entirety in the documentation or other materials
146 provided with the distribution, and (3) all advertising materials mentioning
147 features or use of this software display the following acknowledgement:
148 ``This product includes software developed by the University of California,
149 Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
150 the University nor the names of its contributors may be used to endorse
151 or promote products derived from this software without specific prior
152 written permission.
153 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
154 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
155 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
156
157
158
159