150 lines
5.1 KiB
Groff
150 lines
5.1 KiB
Groff
.\" $NetBSD: pfil.9,v 1.14 2000/11/11 01:22:37 thorpej 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.
|
|
.\" 3. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 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_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 dir" "struct pfil_head *head"
|
|
.Ft void
|
|
.Fn pfil_add_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *"
|
|
.Ft void
|
|
.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
|
|
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
|
|
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
|
|
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 HISTORY
|
|
The
|
|
.Nm
|
|
interface first appeared in
|
|
.Nx 1.3 .
|
|
The
|
|
.Nm
|
|
input and output lists were originally implemented as
|
|
.Fd <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
|
|
.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
|
|
implementation will need changes to suit a threaded kernel model.
|
|
.Sh SEE ALSO
|
|
.Xr bpf 4
|