share/man/man9/pfil.9

   1 .\"     $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2019 Gleb Smirnoff <glebius@FreeBSD.org>
   4 .\" Copyright (c) 1996 Matthew R. Green
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. The name of the author may not be used to endorse or promote products
  16 .\"    derived from this software without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  23 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  24 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  25 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  26 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd January 28, 2019
  33 .Dt PFIL 9
  34 .Os
  35 .Sh NAME
  36 .Nm pfil ,
  37 .Nm pfil_head_register ,
  38 .Nm pfil_head_unregister ,
  39 .Nm pfil_link ,
  40 .Nm pfil_run_hooks
  41 .Nd packet filter interface
  42 .Sh SYNOPSIS
  43 .In sys/param.h
  44 .In sys/mbuf.h
  45 .In net/pfil.h
  46 .Ft pfil_head_t
  47 .Fn pfil_head_register "struct pfil_head_args *args"
  48 .Ft void
  49 .Fn pfil_head_unregister "struct pfil_head_t *head"
  50 .Ft pfil_hook_t
  51 .Fn pfil_add_hook "struct pfil_hook_args *"
  52 .Ft void
  53 .Fn pfil_remove_hook "pfil_hook_t"
  54 .Ft int
  55 .Fn pfil_link "struct pfil_link_args *args"
  56 .Ft int
  57 .Fn pfil_run_hooks "phil_head_t *" "pfil_packet_t" "struct ifnet *" "int" "struct inpcb *"
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 framework allows for a specified function or a list of functions
  62 to be invoked for every incoming or outgoing packet for a particular
  63 network I/O stream.
  64 These hooks may be used to implement a firewall or perform packet
  65 transformations.
  66 .Pp
  67 Packet filtering points, for historical reasons named
  68 .Em heads ,
  69 are registered with
  70 .Fn pfil_head_register .
  71 The function is supplied with special versioned
  72 .Vt struct pfil_head_args
  73 structure that specifies type and features of the head as well as
  74 human readable name.
  75 If the filtering point to be ever destroyed, the subsystem that
  76 created it must unregister it with call to
  77 .Fn pfil_head_unregister .
  78 .Pp
  79 Packet filtering systems may register arbitrary number of filters,
  80 for historical reasons named
  81 .Em hooks .
  82 To register a new hook
  83 .Fn pfil_add_hook
  84 with special versioned
  85 .Vt struct pfil_hook_args
  86 structure is called.
  87 The structure specifies type and features of the hook, pointer to
  88 the actual filtering function and user readable name of the filtering
  89 module and ruleset name.
  90 Later hooks can be removed with
  91 .Fn pfil_remove_hook
  92 functions.
  93 .Pp
  94 To connect existing
  95 .Em hook
  96 to an existing
  97 .Em head
  98 function
  99 .Fn pfil_link
 100 shall be used.
 101 The function is supplied with versioned
 102 .Vt struct pfil_link_args
 103 structure that specifies either literal names of hook and head or
 104 pointers to them.
 105 Typically
 106 .Fn pfil_link
 107 is called by filtering modules to autoregister their default ruleset
 108 and default filtering points.
 109 It also serves on the kernel side of
 110 .Xr ioctl 2
 111 when user changes
 112 .Nm
 113 configuration with help of
 114 .Xr pfilctl 8
 115 utility.
 116 .Pp
 117 For every packet traveling through a
 118 .Em head
 119 the latter shall invoke
 120 .Fn pfil_run_hooks .
 121 The function can accept either
 122 .Vt struct mbuf *
 123 pointer or a
 124 .Vt void *
 125 pointer and length.
 126 In case if a hooked filtering module cannot understand
 127 .Vt void *
 128 pointer
 129 .Nm
 130 will provide it with a fake one.
 131 All calls to
 132 .Fn pfil_run_hooks
 133 are performed in network
 134 .Xr epoch 9 .
 135 .Sh HEADS (filtering points)
 136 By default kernel creates the following heads:
 137 .Bl -tag -width "ethernet"
 138 .It inet
 139 IPv4 packets.
 140 .It inet6
 141 IPv6 packets.
 142 .It ethernet
 143 Link-layer packets.
 144 .El
 145 .Pp
 146 Default rulesets are automatically linked to these heads to preserve
 147 historical behavavior.
 148 .Sh SEE ALSO
 149 .Xr ipfilter 4 ,
 150 .Xr ipfw 4 ,
 151 .Xr pf 4 ,
 152 .Xr pfilctl 8
 153 .Sh HISTORY
 154 The
 155 .Nm
 156 interface first appeared in
 157 .Nx 1.3 .
 158 The
 159 .Nm
 160 interface was imported into
 161 .Fx 5.2 .
 162 In
 163 .Fx 13.0
 164 the interface was significantly rewritten.