1.\" $NetBSD: pfil.9,v 1.13 2000/02/20 01:03:13 darrenr 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 August 4, 1996 30.Dt PFIL 9 31.Os 32.Sh NAME 33.Nm pfil , 34.Nm pfil_hook_get , 35.Nm pfil_add_hook , 36.Nm pfil_remove_hook 37.Nd packet filter interface 38.Sh SYNOPSIS 39.Fd #include <sys/param.h> 40.Fd #include <sys/mbuf.h> 41.Fd #include <net/if.h> 42.Fd #include <net/pfil.h> 43.Ft struct packet_filter_hook * 44.Fn pfil_hook_get "int" "struct pfil_head *" 45.Ft void 46.Fn pfil_add_hook "int (*func)()" "int flags" "struct pfil_head *" 47.Ft void 48.Fn pfil_remove_hook "int (*func)()" "int flags" "struct pfil_head *" 49.\"(void *, int, struct ifnet *, int, struct mbuf **) 50.Sh DESCRIPTION 51The 52.Nm 53interface allows a function to be called on every incoming or outgoing 54packets. The hooks for these are embedded in the 55.Fn ip_input 56and 57.Fn ip_output 58routines. The 59.Fn pfil_hook_get 60function returns the first member of a particular hook, either the in or out 61list. The 62.Fn pfil_add_hook 63function takes a function of the form below as it's first argument, and the 64flags for which lists to add the function to. The possible values for these 65flags are some combination of PFIL_IN and PFIL_OUT. The 66.Fn pfil_remove_hook 67removes a hook from the specified lists. 68.Pp 69The 70.Va func 71argument is a function with the following prototype. 72.Pp 73.Fn func "void *data" "int hlen" "struct ifnet *net" "int dir" "struct mbuf **m" 74.Pp 75The 76.Va data 77describes the packet. Currently, this may only be a pointer to a ip structure. The 78.Va net 79and 80.Va m 81arguments describe the network interface and the mbuf holding data for this 82packet. The 83.Va dir 84is the direction; 0 for incoming packets and 1 for outgoing packets. if the function 85returns non-zero, this signals an error and no further processing of this packet is 86performed. The function should set errno to indicate the nature of the error. 87It is the hook's responsibiliy to free the chain if the packet is being dropped. 88.Pp 89The 90.Nm 91interface is enabled in the kernel via the 92.Sy PFIL_HOOKS 93option. 94.Sh RETURN VALUES 95If successful 96.Fn pfil_hook_get 97returns the first member of the packet filter list, 98.Fn pfil_add_hook 99and 100.Fn pfil_remove_hook 101are expected to always succeed. 102.Sh HISTORY 103The 104.Nm 105interface first appeared in 106.Nx 1.3 . 107The 108.Nm 109input and output lists were originally implemented as 110.Fd <sys/queue.h> 111.Dv LIST 112structures; 113however this was changed in 114.Nx 1.4 115to 116.Dv TAILQ 117structures. This change was to allow the input and output filters to be 118processed in reverse order, to allow the same path to be taken, in or out 119of the kernel. 120.Pp 121The 122.Nm 123interface was changed in 1.4T to accept a 3rd parameter to both 124.Fn pfil_add_hook 125and 126.Fn pfil_remove_hook 127, introducing the capability of per-protocol filtering. This was done 128primarily in order to support filtering of IPv6. 129.Sh BUGS 130The current 131.Nm 132implementation will need changes to suit a threaded kernel model. 133.Sh SEE ALSO 134.Xr bpf 4 135