xref: /dragonfly/share/man/man9/pfil.9 (revision 3f5e28f4)
1.\"	$NetBSD: pfil.9,v 1.24 2004/01/01 15:24:35 wiz Exp $
2.\" $DragonFly: src/share/man/man9/pfil.9,v 1.3 2006/10/19 18:44:00 swildner Exp $
3.\"
4.\" Copyright (c) 1996 Matthew R. Green
5.\" All rights reserved.
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.\" 3. The name of the author may not be used to endorse or promote products
16.\"    derived from this software without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
25.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
26.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.Dd September 26, 2005
31.Dt PFIL 9
32.Os
33.Sh NAME
34.Nm pfil ,
35.Nm pfil_head_register ,
36.Nm pfil_head_unregister ,
37.Nm pfil_head_get ,
38.Nm pfil_hook_get ,
39.Nm pfil_add_hook ,
40.Nm pfil_remove_hook ,
41.Nm pfil_run_hooks
42.Nd packet filter interface
43.Sh SYNOPSIS
44.In sys/param.h
45.In sys/mbuf.h
46.In net/if.h
47.In net/pfil.h
48.Ft int
49.Fn pfil_head_register "struct pfil_head *ph"
50.Ft int
51.Fn pfil_head_unregister "struct pfil_head *pfh"
52.Ft struct pfil_head *
53.Fn pfil_head_get "int type" "u_long val"
54.Ft struct packet_filter_hook *
55.Fn pfil_hook_get "int dir" "struct pfil_head *ph"
56.Ft void
57.Fn pfil_add_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *ph"
58.Ft void
59.Fn pfil_remove_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *ph"
60.Ft int
61.Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir"
62.Ft int
63.Fn pfil_run_hooks "struct pfil_head *ph" "struct mbuf **mp" "struct ifnet *ifp" "int dir"
64.Sh DESCRIPTION
65The
66.Nm
67framework allows for a specified function to be invoked for every
68incoming or outgoing packet for a particular network I/O stream.
69These hooks may be used to implement a firewall or perform packet
70transformations.
71.Pp
72Packet filtering points are registered with
73.Fn pfil_head_register .
74Filtering points are identified by a key (void *) and a data link type
75(int) in the
76.Em pfil_head
77structure.
78Packet filters use the key and data link type to look up the filtering
79point with which they register themselves.
80The key is unique to the filtering point.
81The data link type is a
82.Xr bpf 4
83DLT constant indicating what kind of header is present on the packet
84at the filtering point.
85Filtering points may be unregistered with the
86.Fn pfil_head_unregister
87function.
88.Pp
89Packet filters register/unregister themselves with a filtering point
90with the
91.Fn pfil_add_hook
92and
93.Fn pfil_remove_hook
94functions, respectively.
95The head is looked up using the
96.Fn pfil_head_get
97function, which takes the key and data link type that the packet filter
98expects.
99Filters may provide an argument to be passed to the filter when
100invoked on a packet.
101.Pp
102When a filter is invoked, the packet appears just as if it
103.Dq came off the wire .
104That is, all protocol fields are in network byte order.
105The filter is called with its specified argument, the pointer to the
106pointer to the mbuf containing the packet, the pointer to the network
107interface that the packet is traversing, and the direction
108.Dv ( PFIL_IN
109or
110.Dv PFIL_OUT ,
111see also below) that the packet is traveling.
112The filter may change which mbuf the mbuf ** argument references.
113The filter returns an errno if the packet processing is to stop, or 0
114if the processing is to continue.
115If the packet processing is to stop, it is the responsibility of the
116filter to free the packet.
117.Pp
118The
119.Em flags
120parameter, used in the
121.Fn pfil_add_hook
122and
123.Fn pfil_remove_hook
124functions, indicates when the filter should be called.
125The flags are:
126.Bl -tag -offset indent -width PFIL_WAITOK -compact
127.It PFIL_IN
128call me on incoming packets
129.It PFIL_OUT
130call me on outgoing packets
131.It PFIL_ALL
132call me on all of the above
133.It PFIL_WAITOK
134OK to call kmalloc with M_WAITOK.
135.El
136.Pp
137The
138.Nm
139interface is enabled in the kernel via the
140.Sy PFIL_HOOKS
141option.
142.Sh SEE ALSO
143.Xr bpf 4
144.Sh HISTORY
145The
146.Nm
147interface first appeared in
148.Nx 1.3 .
149The
150.Nm
151input and output lists were originally implemented as
152.In sys/queue.h
153.Dv LIST
154structures;
155however this was changed in
156.Nx 1.4
157to
158.Dv TAILQ
159structures.
160This change was to allow the input and output filters to be processed in
161reverse order, to allow the same path to be taken, in or out of the kernel.
162.Pp
163The
164.Nm
165interface was changed in 1.4T to accept a 3rd parameter to both
166.Fn pfil_add_hook
167and
168.Fn pfil_remove_hook ,
169introducing the capability of per-protocol filtering.
170This was done primarily in order to support filtering of IPv6.
171.Pp
172In 1.5K, the
173.Nm
174framework was changed to work with an arbitrary number of filtering points,
175as well as be less IP-centric.
176.Pp
177The
178.Nm
179interface was imported from
180.Nx
181into
182.Dx 1.0 .
183.Sh AUTHORS
184The
185.Nm
186interface was designed and implemented by Matthew R. Green, with help
187from Darren Reed, Jason R. Thorpe and Charles M. Hannum.
188Darren Reed added support for IPv6 in addition to IPv4.
189Jason R. Thorpe added support for multiple hooks and other clean up.
190.Sh BUGS
191The current
192.Nm
193implementation will need changes to suit a threaded kernel model.
194