share/man/man9/pfil.9

   1 .\"     $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 wiz 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 .\" $FreeBSD$
  30 .\"
  31 .Dd September 29, 2004
  32 .Dt PFIL 9
  33 .Os
  34 .Sh NAME
  35 .Nm pfil ,
  36 .Nm pfil_head_register ,
  37 .Nm pfil_head_unregister ,
  38 .Nm pfil_head_get ,
  39 .Nm pfil_hook_get ,
  40 .Nm pfil_add_hook ,
  41 .Nm pfil_remove_hook ,
  42 .Nm pfil_run_hooks
  43 .Nd packet filter interface
  44 .Sh SYNOPSIS
  45 .In sys/param.h
  46 .In sys/mbuf.h
  47 .In net/if.h
  48 .In net/pfil.h
  49 .Ft int
  50 .Fn pfil_head_register "struct pfil_head *head"
  51 .Ft int
  52 .Fn pfil_head_unregister "struct pfil_head *head"
  53 .Ft "struct pfil_head *"
  54 .Fn pfil_head_get "int af" "u_long dlt"
  55 .Ft "struct packet_filter_hook *"
  56 .Fn pfil_hook_get "int dir" "struct pfil_head *head"
  57 .Ft void
  58 .Fn pfil_add_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *"
  59 .Ft void
  60 .Fn pfil_remove_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *"
  61 .Ft int
  62 .Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir" "struct inpcb *"
  63 .Ft int
  64 .Fn pfil_run_hooks "struct pfil_head *head" "struct mbuf **mp" "struct ifnet *" "int dir" "struct inpcb *"
  65 .Sh DESCRIPTION
  66 The
  67 .Nm
  68 framework allows for a specified function to be invoked for every
  69 incoming or outgoing packet for a particular network I/O stream.
  70 These hooks may be used to implement a firewall or perform packet
  71 transformations.
  72 .Pp
  73 Packet filtering points are registered with
  74 .Fn pfil_head_register .
  75 Filtering points are identified by a key
  76 .Pq Vt "void *"
  77 and a data link type
  78 .Pq Vt int
  79 in the
  80 .Vt pfil_head
  81 structure.
  82 Packet filters use the key and data link type to look up the filtering
  83 point with which they register themselves.
  84 The key is unique to the filtering point.
  85 The data link type is a
  86 .Xr bpf 4
  87 DLT constant indicating what kind of header is present on the packet
  88 at the filtering point.
  89 Filtering points may be unregistered with the
  90 .Fn pfil_head_unregister
  91 function.
  92 .Pp
  93 Packet filters register/unregister themselves with a filtering point
  94 with the
  95 .Fn pfil_add_hook
  96 and
  97 .Fn pfil_remove_hook
  98 functions, respectively.
  99 The head is looked up using the
 100 .Fn pfil_head_get
 101 function, which takes the key and data link type that the packet filter
 102 expects.
 103 Filters may provide an argument to be passed to the filter when
 104 invoked on a packet.
 105 .Pp
 106 When a filter is invoked, the packet appears just as if it
 107 .Dq came off the wire .
 108 That is, all protocol fields are in network byte order.
 109 The filter is called with its specified argument, the pointer to the
 110 pointer to the
 111 .Vt mbuf
 112 containing the packet, the pointer to the network
 113 interface that the packet is traversing, and the direction
 114 .Dv ( PFIL_IN
 115 or
 116 .Dv PFIL_OUT )
 117 that the packet is traveling.
 118 The filter may change which mbuf the
 119 .Vt "mbuf\ **"
 120 argument references.
 121 The filter returns an error (errno) if the packet processing is to stop, or 0
 122 if the processing is to continue.
 123 If the packet processing is to stop, it is the responsibility of the
 124 filter to free the packet.
 125 .Sh RETURN VALUES
 126 If successful,
 127 .Fn pfil_head_get
 128 returns the
 129 .Vt pfil_head
 130 structure for the given key/dlt.
 131 The
 132 .Fn pfil_add_hook
 133 and
 134 .Fn pfil_remove_hook
 135 functions
 136 return 0 if successful.
 137 If called with flag
 138 .Dv PFIL_WAITOK ,
 139 .Fn pfil_remove_hook
 140 is expected to always succeed.
 141 .Pp
 142 The
 143 .Fn pfil_head_unregister
 144 function
 145 might sleep!
 146 .Sh SEE ALSO
 147 .Xr bpf 4 ,
 148 .Xr if_bridge 4
 149 .Sh HISTORY
 150 The
 151 .Nm
 152 interface first appeared in
 153 .Nx 1.3 .
 154 The
 155 .Nm
 156 input and output lists were originally implemented as
 157 .In sys/queue.h
 158 .Dv LIST
 159 structures;
 160 however this was changed in
 161 .Nx 1.4
 162 to
 163 .Dv TAILQ
 164 structures.
 165 This change was to allow the input and output filters to be processed in
 166 reverse order, to allow the same path to be taken, in or out of the kernel.
 167 .Pp
 168 The
 169 .Nm
 170 interface was changed in 1.4T to accept a 3rd parameter to both
 171 .Fn pfil_add_hook
 172 and
 173 .Fn pfil_remove_hook ,
 174 introducing the capability of per-protocol filtering.
 175 This was done primarily in order to support filtering of IPv6.
 176 .Pp
 177 In 1.5K, the
 178 .Nm
 179 framework was changed to work with an arbitrary number of filtering points,
 180 as well as be less IP-centric.
 181 .Pp
 182 Fine-grained locking was added in
 183 .Fx 5.2 .
 184 .Sh BUGS
 185 The
 186 .Fn pfil_hook_get
 187 function
 188 is only safe for internal use.
 189 .Pp
 190 .Fx
 191 implements only hooks for
 192 .Dv AF_INET
 193 and
 194 .Dv AF_INET6 .
 195 Packets diverted through these hooks have data in
 196 host byte order contrary to the above statements.
 197 .Pp
 198 The
 199 .Xr if_bridge 4
 200 diverts
 201 .Dv AF_INET
 202 and
 203 .Dv AF_INET6
 204 traffic according to its sysctl settings, but contrary to the above
 205 statements, the data is provided in host byte order.
 206 .Pp
 207 When a
 208 .Vt pfil_head
 209 is being modified, no traffic is diverted
 210 (to avoid deadlock).
 211 This means that traffic may be dropped unconditionally for a short period
 212 of time.
 213 .Fn pfil_run_hooks
 214 will return
 215 .Er ENOBUFS
 216 to indicate this.