From dcf80e02de8c0bd3fb2c889c824f0fadce40d3ff Mon Sep 17 00:00:00 2001 From: thorpej Date: Sat, 11 Nov 2000 01:22:37 +0000 Subject: [PATCH] Update for the new pfil framework. --- share/man/man9/pfil.9 | 111 ++++++++++++++++++++++++------------------ 1 file changed, 63 insertions(+), 48 deletions(-) diff --git a/share/man/man9/pfil.9 b/share/man/man9/pfil.9 index 8d08ac6602a0..d267bdac339c 100644 --- a/share/man/man9/pfil.9 +++ b/share/man/man9/pfil.9 @@ -1,4 +1,4 @@ -.\" $NetBSD: pfil.9,v 1.13 2000/02/20 01:03:13 darrenr Exp $ +.\" $NetBSD: pfil.9,v 1.14 2000/11/11 01:22:37 thorpej Exp $ .\" .\" Copyright (c) 1996 Matthew R. Green .\" All rights reserved. @@ -26,79 +26,87 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 4, 1996 +.Dd November 10, 2000 .Dt PFIL 9 .Os .Sh NAME .Nm pfil , +.Nm pfil_head_register , +.Nm pfil_head_unregister , +.Nm pfil_head_get , .Nm pfil_hook_get , .Nm pfil_add_hook , -.Nm pfil_remove_hook +.Nm pfil_remove_hook , +.Nm pfil_run_hooks .Nd packet filter interface .Sh SYNOPSIS .Fd #include .Fd #include .Fd #include .Fd #include +.Ft int +.Fn pfil_head_register "struct pfil_head *head" +.Ft int +.Fn pfil_head_unregister "struct pfil_head *head" .Ft struct packet_filter_hook * -.Fn pfil_hook_get "int" "struct pfil_head *" +.Fn pfil_hook_get "int dir" "struct pfil_head *head" .Ft void -.Fn pfil_add_hook "int (*func)()" "int flags" "struct pfil_head *" +.Fn pfil_add_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" .Ft void -.Fn pfil_remove_hook "int (*func)()" "int flags" "struct pfil_head *" -.\"(void *, int, struct ifnet *, int, struct mbuf **) +.Fn pfil_remove_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" +.Ft int +.Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir" +.Ft int +.Fn pfil_run_hooks "struct pfil_head *head" "struct mbuf **mp" "struct ifnet *" "int dir" .Sh DESCRIPTION The .Nm -interface allows a function to be called on every incoming or outgoing -packets. The hooks for these are embedded in the -.Fn ip_input -and -.Fn ip_output -routines. The -.Fn pfil_hook_get -function returns the first member of a particular hook, either the in or out -list. The +framework allows for a specified function to be invoked for every +incoming or outgoing packet for a particular network I/O stream. These +hooks may be used to implement a firewall or perform packet transformations. +.Nm +Packet filtering points are registered with +.Fn pfil_head_register . +Filtering points are identified by a key (void *) and a data link type +(int) in the +.Em pfil_head +structure. Packet filters use the key and data link type to look up +the filtering point with which they register themselves. The key is +unique to the filtering point. The data link type is a +.Xr bpf 4 +DLT constant indicating what kind of header is present on the packet +at the filtering point. +Filtering points may be unregistered with the +.Fn pfil_head_unregister +function. +.Pp +Packet filters register/unregister themselves with a filtering point +with the .Fn pfil_add_hook -function takes a function of the form below as it's first argument, and the -flags for which lists to add the function to. The possible values for these -flags are some combination of PFIL_IN and PFIL_OUT. The -.Fn pfil_remove_hook -removes a hook from the specified lists. -.Pp -The -.Va func -argument is a function with the following prototype. -.Pp -.Fn func "void *data" "int hlen" "struct ifnet *net" "int dir" "struct mbuf **m" -.Pp -The -.Va data -describes the packet. Currently, this may only be a pointer to a ip structure. The -.Va net and -.Va m -arguments describe the network interface and the mbuf holding data for this -packet. The -.Va dir -is the direction; 0 for incoming packets and 1 for outgoing packets. if the function -returns non-zero, this signals an error and no further processing of this packet is -performed. The function should set errno to indicate the nature of the error. -It is the hook's responsibiliy to free the chain if the packet is being dropped. +.Fn pfil_remove_hook +functions, respectively. The head is looked up using the +.Fn pfil_head_get +function, which takes the key and data link type that the packet filter +expects. Filters may provide an argument to be passed to the filter +when invoked on a packet. +.Pp +When a filter is invoked, the packet appears just as if it +.Dq came off the wire . +That is, all protocol fields are in network byte order. The filter is +called with its specified argument, the pointer to the pointer to the +mbuf containing the packet, the pointer to the network interface that +the packet is traversing, and the direction (PFIL_IN or PFIL_OUT) that +the packet is traveling. The filter may change which mbuf the mbuf ** +argument references. The filter returns an errno if the packet processing +is to stop, or 0 if the processing is to continue. If the packet processing +is to stop, it is the responsibility of the filter to free the packet. .Pp The .Nm interface is enabled in the kernel via the .Sy PFIL_HOOKS option. -.Sh RETURN VALUES -If successful -.Fn pfil_hook_get -returns the first member of the packet filter list, -.Fn pfil_add_hook -and -.Fn pfil_remove_hook -are expected to always succeed. .Sh HISTORY The .Nm @@ -126,6 +134,13 @@ and .Fn pfil_remove_hook , introducing the capability of per-protocol filtering. This was done primarily in order to support filtering of IPv6. +.Pp +In +.Nx 1.5K , +the +.Nm +framework was changed to work with an arbitrary number of filtering points, +as well as be less IP-centric. .Sh BUGS The current .Nm