share/man/man9/pfil.9

   1 .\" Copyright (c) 1996 Matthew R. Green
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. The name of the author may not be used to endorse or promote products
  13 .\"    derived from this software without specific prior written permission.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  20 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  21 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  22 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  23 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .Dd August 4, 1996
  29 .Dt PFIL 9
  30 .Os
  31 .Sh NAME
  32 .Nm pfil ,
  33 .Nm pfil_hook_get ,
  34 .Nm pfil_add_hook ,
  35 .Nm pfil_remove_hook
  36 .Nd packet filter interface
  37 .Sh SYNOPSIS
  38 .Fd #include <sys/param.h>
  39 .Fd #include <sys/mbuf.h>
  40 .Fd #include <net/if.h>
  41 .Fd #include <net/pfil.h>
  42 .Ft struct packet_filter_hook *
  43 .Fn pfil_hook_get "int" "struct pfil_head *"
  44 .Ft void
  45 .Fn pfil_add_hook "int (*func)()" "int flags" "struct pfil_head *"
  46 .Ft void
  47 .Fn pfil_remove_hook "int (*func)()" "int flags" "struct pfil_head *"
  48 .\"(void *, int, struct ifnet *, int, struct mbuf **)
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 interface allows a function to be called on every incoming or outgoing
  53 packets.  The hooks for these are embedded in the
  54 .Fn ip_input
  55 and
  56 .Fn ip_output
  57 routines.  The
  58 .Fn pfil_hook_get
  59 function returns the first member of a particular hook, either the in or out
  60 list.  The
  61 .Fn pfil_add_hook
  62 function takes a function of the form below as it's first argument, and the
  63 flags for which lists to add the function to.  The possible values for these
  64 flags are some combination of PFIL_IN and PFIL_OUT.  The
  65 .Fn pfil_remove_hook
  66 removes a hook from the specified lists.
  67 .Pp
  68 The
  69 .Va func
  70 argument is a function with the following prototype.
  71 .Pp
  72 .Fn func "void *data" "int hlen" "struct ifnet *net" "int dir" "struct mbuf **m"
  73 .Pp
  74 The
  75 .Va data
  76 describes the packet.  Currently, this may only be a pointer to a ip structure.  The
  77 .Va net
  78 and
  79 .Va m
  80 arguments describe the network interface and the mbuf holding data for this
  81 packet.  The
  82 .Va dir
  83 is the direction; 0 for incoming packets and 1 for outgoing packets.  if the function
  84 returns non-zero, this signals an error and no further processing of this packet is
  85 performed.  The function should set errno to indicate the nature of the error.
  86 It is the hook's responsibiliy to free the chain if the packet is being dropped.
  87 .Pp
  88 The
  89 .Nm
  90 interface is enabled in the kernel via the
  91 .Sy PFIL_HOOKS
  92 option.
  93 .Sh RETURN VALUES
  94 If successful
  95 .Fn pfil_hook_get
  96 returns the first member of the packet filter list,
  97 .Fn pfil_add_hook
  98 and
  99 .Fn pfil_remove_hook
 100 are expected to always succeed.
 101 .Sh HISTORY
 102 The
 103 .Nm
 104 interface first appeared in
 105 .Nx 1.3 .
 106 The
 107 .Nm
 108 input and output lists were originally implemented as
 109 .Pa Aq sys/queue.h
 110 .Dv LIST
 111 structures;
 112 however this was changed in
 113 .Nx 1.4
 114 to
 115 .Dv TAILQ
 116 structures.  This change was to allow the input and output filters to be
 117 processed in reverse order, to allow the same path to be taken, in or out
 118 of the kernel.
 119 .Pp
 120 The
 121 .Nm
 122 interface was changed in 1.4T to accept a 3rd parameter to both
 123 .Fn pfil_add_hook
 124 and
 125 .Fn pfil_remove_hook ,
 126 introducing the capability of per-protocol filtering.  This was done
 127 primarily in order to support filtering of IPv6.
 128 .Sh BUGS
 129 The current
 130 .Nm
 131 implementation will need changes to suit a threaded kernel model.
 132 .Sh SEE ALSO
 133 .Xr bpf 4