diff options
Diffstat (limited to 'static/netbsd/man9/pfil.9')
| -rw-r--r-- | static/netbsd/man9/pfil.9 | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/static/netbsd/man9/pfil.9 b/static/netbsd/man9/pfil.9 new file mode 100644 index 00000000..36a46e3f --- /dev/null +++ b/static/netbsd/man9/pfil.9 @@ -0,0 +1,267 @@ +.\" $NetBSD: pfil.9,v 1.40 2022/01/15 17:54:01 wiz Exp $ +.\" +.\" Copyright (c) 1996 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 15, 2022 +.Dt PFIL 9 +.Os +.Sh NAME +.Nm pfil , +.Nm pfil_head_create , +.Nm pfil_head_destroy , +.Nm pfil_head_get , +.Nm pfil_hook_get , +.Nm pfil_add_hook , +.Nm pfil_remove_hook , +.Nm pfil_run_hooks , +.Nm pfil_add_ihook , +.Nm pfil_remove_ihook , +.Nm pfil_run_addrhooks , +.Nm pfil_run_ifhooks +.Nd packet filter interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/mbuf.h +.In net/if.h +.In net/pfil.h +.Ft pfil_head_t * +.Fn pfil_head_create "int type" "void *key" +.Ft int +.Fn pfil_head_destroy "pfil_head_t *ph" +.Ft pfil_head_t * +.Fn pfil_head_get "int type" "void *key" +.Ft struct packet_filter_hook * +.Fn pfil_hook_get "int dir" "pfil_head_t *ph" +.Ft int +.Fn pfil_add_hook "pfil_func_t func" "void *arg" "int flags" "pfil_head_t *ph" +.Ft int +.Fn pfil_remove_hook "pfil_func_t func" "void *arg" "int flags" "pfil_head_t *ph" +.Ft int +.Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir" +.Ft int +.Fn pfil_run_hooks "pfil_head_t *ph" "struct mbuf **mp" "struct ifnet *ifp" "int dir" +.Ft int +.Fn pfil_add_ihook "pfil_ifunc_t ifunc" "void *arg" "int flags" "pfil_head_t *ph" +.Ft int +.Fn pfil_remove_ihook "pfil_ifunc_t ifunc" "void *arg" "int flags" "pfil_head_t *ph" +.Ft void +.Fn (*ifunc) "void *arg" "unsigned long cmd" "void *ptr" +.Ft void +.Fn pfil_run_addrhooks "pfil_head_t *ph" "unsigned long" "struct ifaddr *ifa" +.Ft void +.Fn pfil_run_ifhooks "pfil_head_t *ph" "unsigned long" "struct ifnet *ifp" +.Sh DESCRIPTION +The +.Nm +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. +.Pp +Packet filtering points are created with +.Fn pfil_head_create . +Filtering points are identified by a +data link +.Vt ( int ) +.Fa type +and a +.Vt ( void * ) +.Fa key . +If a packet filtering point already exists for that data link +.Fa type +and +.Fa key +then the +.Fn pfil_head_create +function returns +.Dv NULL . +Packet filters use the +.Fn pfil_head_get +function specifying the data link +.Fa type +and the +.Fa key +to look up the filtering point with which they register themselves. +The +.Fa key +is unique to the filtering point. +The data link +.Fa type +is a +.Xr bpf 4 +.Dv DLT_ Ns Ar type +constant indicating what kind of header is present on the packet +at the filtering point. +Filtering points may be destroyed with the +.Fn pfil_head_destroy +function. +.Pp +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 data link +.Fa type +and the +.Fa key +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 (either +.Dv PFIL_IN +or +.Dv PFIL_OUT , +see also below) that the packet is traveling. +The filter may change which mbuf the +.Vt "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 +.Fa flags +parameter, used in the +.Fn pfil_add_hook +and +.Fn pfil_remove_hook +functions, indicates when the filter should be called. +The flags are: +.Pp +.Bl -tag -offset indent -width ".Dv PFIL_ALL" -compact +.It Dv PFIL_IN +call me on incoming packets +.It Dv PFIL_OUT +call me on outgoing packets +.It Dv PFIL_ALL +call me on all of the above +.El +.Pp +By the same token, event handlers register/unregister themselves +with the +.Fn pfil_add_ihook +and +.Fn pfil_remove_ihook +functions, respectively. +The event handler is called with its specified argument, the event id +(either +.Dv PFIL_IFNET_ATTACH +or +.Dv PFIL_IFNET_DETACH , +see also below) or ioctl number, and the pointer +to the network interface or the pointer to the ifaddr. +.Pp +The +.Fa flags +parameter, used in the +.Fn pfil_add_ihook +and +.Fn pfil_remove_ihook +functions, indicates when the filter should be called. +The flags are: +.Pp +.Bl -tag -offset indent -width ".Dv PFIL_IFADDR" -compact +.It Dv PFIL_IFADDR +call me on interface reconfig +.Fa ( cmd +is ioctl #) +.It Dv PFIL_IFNET +call me on interface attach/detach +.Fa ( cmd +is either +.Dv PFIL_IFNET_ATTACH +or +.Dv PFIL_IFNET_DETACH ) +.El +.Sh SEE ALSO +.Xr bpf 4 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 1.3 . +The +.Nm +input and output lists were originally implemented as +.In sys/queue.h +.Dv LIST +structures; +however this was changed in +.Nx 1.4 +to +.Dv TAILQ +structures. +This change was to allow the input and output filters to be processed in +reverse order, to allow the same path to be taken, in or out of the kernel. +.Pp +The +.Nm +interface was changed in 1.4T to accept a 3rd parameter to both +.Fn pfil_add_hook +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 1.5K, the +.Nm +framework was changed to work with an arbitrary number of filtering points, +as well as be less IP-centric. +.Pp +.Fn pfil_add_ihook +and +.Fn pfil_remove_ihook +were added in +.Nx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +interface was designed and implemented by +.An Matthew R. Green , +with help from +.An Darren Reed , +.An Jason R. Thorpe , +and +.An Charles M. Hannum . +.An Darren Reed +added support for IPv6 in addition to IPv4. +.An Jason R. Thorpe +added support for multiple hooks and other clean up. +.Sh BUGS +The current +.Nm +implementation will need changes to suit a threaded kernel model. |