1.\" $NetBSD: pfil.9,v 1.17 2002/02/13 08:18:48 ross Exp $ 2.\" 3.\" Copyright (c) 1996 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 24.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd November 10, 2000 30.Dt PFIL 9 31.Os 32.Sh NAME 33.Nm pfil , 34.Nm pfil_head_register , 35.Nm pfil_head_unregister , 36.Nm pfil_head_get , 37.Nm pfil_hook_get , 38.Nm pfil_add_hook , 39.Nm pfil_remove_hook , 40.Nm pfil_run_hooks 41.Nd packet filter interface 42.Sh SYNOPSIS 43.Fd #include \*[Lt]sys/param.h\*[Gt] 44.Fd #include \*[Lt]sys/mbuf.h\*[Gt] 45.Fd #include \*[Lt]net/if.h\*[Gt] 46.Fd #include \*[Lt]net/pfil.h\*[Gt] 47.Ft int 48.Fn pfil_head_register "struct pfil_head *head" 49.Ft int 50.Fn pfil_head_unregister "struct pfil_head *head" 51.Ft struct packet_filter_hook * 52.Fn pfil_hook_get "int dir" "struct pfil_head *head" 53.Ft void 54.Fn pfil_add_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" 55.Ft void 56.Fn pfil_remove_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" 57.Ft int 58.Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir" 59.Ft int 60.Fn pfil_run_hooks "struct pfil_head *head" "struct mbuf **mp" "struct ifnet *" "int dir" 61.Sh DESCRIPTION 62The 63.Nm 64framework allows for a specified function to be invoked for every 65incoming or outgoing packet for a particular network I/O stream. These 66hooks may be used to implement a firewall or perform packet transformations. 67.Nm 68Packet filtering points are registered with 69.Fn pfil_head_register . 70Filtering points are identified by a key (void *) and a data link type 71(int) in the 72.Em pfil_head 73structure. Packet filters use the key and data link type to look up 74the filtering point with which they register themselves. The key is 75unique to the filtering point. The data link type is a 76.Xr bpf 4 77DLT constant indicating what kind of header is present on the packet 78at the filtering point. 79Filtering points may be unregistered with the 80.Fn pfil_head_unregister 81function. 82.Pp 83Packet filters register/unregister themselves with a filtering point 84with the 85.Fn pfil_add_hook 86and 87.Fn pfil_remove_hook 88functions, respectively. The head is looked up using the 89.Fn pfil_head_get 90function, which takes the key and data link type that the packet filter 91expects. Filters may provide an argument to be passed to the filter 92when invoked on a packet. 93.Pp 94When a filter is invoked, the packet appears just as if it 95.Dq came off the wire . 96That is, all protocol fields are in network byte order. The filter is 97called with its specified argument, the pointer to the pointer to the 98mbuf containing the packet, the pointer to the network interface that 99the packet is traversing, and the direction (PFIL_IN or PFIL_OUT) that 100the packet is traveling. The filter may change which mbuf the mbuf ** 101argument references. The filter returns an errno if the packet processing 102is to stop, or 0 if the processing is to continue. If the packet processing 103is to stop, it is the responsibility of the filter to free the packet. 104.Pp 105The 106.Nm 107interface is enabled in the kernel via the 108.Sy PFIL_HOOKS 109option. 110.Sh SEE ALSO 111.Xr bpf 4 112.Sh HISTORY 113The 114.Nm 115interface first appeared in 116.Nx 1.3 . 117The 118.Nm 119input and output lists were originally implemented as 120.Fd \*[Lt]sys/queue.h\*[Gt] 121.Dv LIST 122structures; 123however this was changed in 124.Nx 1.4 125to 126.Dv TAILQ 127structures. This change was to allow the input and output filters to be 128processed in reverse order, to allow the same path to be taken, in or out 129of the kernel. 130.Pp 131The 132.Nm 133interface was changed in 1.4T to accept a 3rd parameter to both 134.Fn pfil_add_hook 135and 136.Fn pfil_remove_hook 137, introducing the capability of per-protocol filtering. This was done 138primarily in order to support filtering of IPv6. 139.Pp 140In 141.Nx 1.5K , 142the 143.Nm 144framework was changed to work with an arbitrary number of filtering points, 145as well as be less IP-centric. 146.Sh BUGS 147The current 148.Nm 149implementation will need changes to suit a threaded kernel model. 150