xref: /freebsd/share/man/man9/bpf.9 (revision 4b9d6057)
1.\" Copyright (c) 2004 FreeBSD Inc.
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.Dd May 11, 2012
26.Dt BPF 9
27.Os
28.\"
29.Sh NAME
30.Nm bpf
31.Nd "Berkeley Packet Filter"
32.\"
33.Sh SYNOPSIS
34.In net/bpf.h
35.\"
36.Ft void
37.Fn bpfattach "struct ifnet *ifp" "u_int dlt" "u_int hdrlen"
38.Ft void
39.Fo bpfattach2
40.Fa "struct ifnet *ifp" "u_int dlt" "u_int hdrlen" "struct bpf_if **driverp"
41.Fc
42.Ft void
43.Fn bpfdetach "struct ifnet *ifp"
44.Ft void
45.Fn bpf_tap "struct ifnet *ifp" "u_char *pkt" "u_int *pktlen"
46.Ft void
47.Fn bpf_mtap "struct ifnet *ifp" "struct mbuf *m"
48.Ft void
49.Fn bpf_mtap2 "struct bpf_if *bp" "void *data" "u_int dlen" "struct mbuf *m"
50.Ft u_int
51.Fo bpf_filter
52.Fa "const struct bpf_insn *pc " "u_char *pkt" "u_int wirelen" "u_int buflen"
53.Fc
54.Ft int
55.Fn bpf_validate "const struct bpf_insn *fcode" "int flen"
56.\"
57.Sh DESCRIPTION
58The Berkeley Packet Filter provides a raw interface,
59that is protocol independent,
60to data link layers.
61It allows all packets on the network,
62even those destined for other hosts,
63to be passed from a network interface to user programs.
64Each program may specify a filter,
65in the form of a
66.Nm
67filter machine program.
68The
69.Xr bpf 4
70manual page
71describes the interface used by user programs.
72This manual page describes the functions used by interfaces to pass packets to
73.Nm
74and the functions for testing and running
75.Nm
76filter machine programs.
77.Pp
78The
79.Fn bpfattach
80function
81attaches a network interface to
82.Nm .
83The
84.Fa ifp
85argument
86is a pointer to the structure that defines the interface to be
87attached to an interface.
88The
89.Fa dlt
90argument
91is the data link-layer type:
92.Dv DLT_NULL
93(no link-layer encapsulation),
94.Dv DLT_EN10MB
95(Ethernet),
96.Dv DLT_IEEE802_11
97(802.11 wireless networks),
98etc.
99The rest of the link layer types can be found in
100.In net/bpf.h .
101The
102.Fa hdrlen
103argument
104is the fixed size of the link header;
105variable length headers are not yet supported.
106The
107.Nm
108system will hold a pointer to
109.Fa ifp->if_bpf .
110This variable will set to a
111.Pf non- Dv NULL
112value when
113.Nm
114requires packets from this interface to be tapped using the functions below.
115.Pp
116The
117.Fn bpfattach2
118function
119allows multiple
120.Nm
121instances to be attached to a single interface,
122by registering an explicit
123.Fa if_bpf
124rather than using
125.Fa ifp->if_bpf .
126It is then possible to run
127.Xr tcpdump 1
128on the interface for any data link-layer types attached.
129.Pp
130The
131.Fn bpfdetach
132function detaches a
133.Nm
134instance from an interface,
135specified by
136.Fa ifp .
137The
138.Fn bpfdetach
139function
140should be called once for each
141.Nm
142instance attached.
143.Pp
144The
145.Fn bpf_tap
146function
147is used by an interface to pass the packet to
148.Nm .
149The packet data (including link-header),
150pointed to by
151.Fa pkt ,
152is of length
153.Fa pktlen ,
154which must be a contiguous buffer.
155The
156.Fa ifp
157argument
158is a pointer to the structure that defines the interface to be tapped.
159The packet is parsed by each processes filter,
160and if accepted,
161it is buffered for the process to read.
162.Pp
163The
164.Fn bpf_mtap
165function is like
166.Fn bpf_tap
167except that it is used to tap packets that are in an
168.Vt mbuf
169chain,
170.Fa m .
171The
172.Fa ifp
173argument
174is a pointer to the structure that defines the interface to be tapped.
175Like
176.Fn bpf_tap ,
177.Fn bpf_mtap
178requires a link-header for whatever data link layer type is specified.
179Note that
180.Nm
181only reads from the
182.Vt mbuf
183chain,
184it does not free it or keep a pointer to it.
185This means that an
186.Vt mbuf
187containing the link-header
188can be prepended to the chain if necessary.
189A cleaner interface to achieve this is provided by
190.Fn bpf_mtap2 .
191.Pp
192The
193.Fn bpf_mtap2
194function
195allows the user to pass a link-header
196.Fa data ,
197of length
198.Fa dlen ,
199independent of the
200.Vt mbuf
201.Fa m ,
202containing the packet.
203This simplifies the passing of some link-headers.
204.Pp
205The
206.Fn bpf_filter
207function
208executes the filter program starting at
209.Fa pc
210on the packet
211.Fa pkt .
212The
213.Fa wirelen
214argument
215is the length of the original packet and
216.Fa buflen
217is the amount of data present.
218The
219.Fa buflen
220value of 0 is special; it indicates that the
221.Fa pkt
222is actually a pointer to an mbuf chain
223.Pq Vt "struct mbuf *" .
224.Pp
225The
226.Fn bpf_validate
227function
228checks that the filter code
229.Fa fcode ,
230of length
231.Fa flen ,
232is valid.
233.\"
234.Sh RETURN VALUES
235The
236.Fn bpf_filter
237function returns \-1
238(cast to an unsigned integer)
239if there is no filter.
240Otherwise, it returns the result of the filter program.
241.Pp
242The
243.Fn bpf_validate
244function
245returns 0 when the program is not a valid filter program.
246.\"
247.Sh EVENT HANDLERS
248.Nm
249invokes
250.Fa bpf_track
251.Xr EVENTHANDLER 9
252event each time listener attaches to or detaches from an interface.
253Pointer to
254.Pq Vt "struct ifnet *"
255is passed as the first argument, interface
256.Fa dlt
257follows.
258Last argument indicates listener is attached (1) or detached (0).
259Note that handler is invoked with
260.Nm
261global lock held, which implies restriction on sleeping and calling
262.Nm
263subsystem inside
264.Xr EVENTHANDLER 9
265dispatcher.
266Note that handler is not called for write-only listeners.
267.\"
268.Sh SEE ALSO
269.Xr tcpdump 1 ,
270.Xr bpf 4 ,
271.Xr EVENTHANDLER 9
272.\"
273.Sh HISTORY
274The Enet packet filter was created in 1980 by Mike Accetta and
275Rick Rashid at Carnegie-Mellon University.
276Jeffrey Mogul,
277at Stanford,
278ported the code to
279.Bx
280and continued its development from 1983 on.
281Since then,
282it has evolved into the Ultrix Packet Filter at
283.Tn DEC ,
284a
285.Tn STREAMS
286.Tn NIT
287module under
288.Tn SunOS
2894.1, and
290.Tn BPF .
291.\"
292.Sh AUTHORS
293.An -nosplit
294.An Steven McCanne ,
295of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990.
296Much of the design is due to
297.An Van Jacobson .
298This manpage was written by
299.An Orla McGann .
300