[src/trunk]: src/share/man/man9 Update for the new pfil framework.

[thorpej <thorpej%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e52fa7ee2b37
branches:  trunk
changeset: 499095:e52fa7ee2b37
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Sat Nov 11 01:22:37 2000 +0000

description:
Update for the new pfil framework.

diffstat:

 share/man/man9/pfil.9 |  111 ++++++++++++++++++++++++++++---------------------
 1 files changed, 63 insertions(+), 48 deletions(-)

diffs (158 lines):

diff -r 928b0c2800b2 -r e52fa7ee2b37 share/man/man9/pfil.9
--- a/share/man/man9/pfil.9     Sat Nov 11 00:55:51 2000 +0000
+++ b/share/man/man9/pfil.9     Sat Nov 11 01:22:37 2000 +0000
@@ -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 <sys/param.h>
 .Fd #include <sys/mbuf.h> 
 .Fd #include <net/if.h>
 .Fd #include <net/pfil.h>
+.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
-.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.
+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
-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"
+Packet filters register/unregister themselves with a filtering point
+with the
+.Fn pfil_add_hook
+and
+.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
-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.
+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 @@
 .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