217 lines
6.0 KiB
Groff
217 lines
6.0 KiB
Groff
.\" $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 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.
|
|
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd September 8, 2003
|
|
.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
|
|
.In sys/param.h
|
|
.In sys/mbuf.h
|
|
.In net/if.h
|
|
.In 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 pfil_head *"
|
|
.Fn pfil_head_get "int af" "u_long dlt"
|
|
.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.
|
|
.Pp
|
|
Packet filtering points are registered with
|
|
.Fn pfil_head_register .
|
|
Filtering points are identified by a key
|
|
.Pq Vt "void *"
|
|
and a data link type
|
|
.Pq Vt int
|
|
in the
|
|
.Vt 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
|
|
.Vt mbuf
|
|
containing the packet, the pointer to the network
|
|
interface that the packet is traversing, and the direction
|
|
.Dv ( PFIL_IN
|
|
or
|
|
.Dv PFIL_OUT )
|
|
that the packet is traveling.
|
|
The filter may change which mbuf the
|
|
.Vt "mbuf\ **"
|
|
argument references.
|
|
The filter returns an error (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
|
|
.Dv PFIL_HOOKS
|
|
option.
|
|
.Sh RETURN VALUES
|
|
If successful,
|
|
.Fn pfil_head_get
|
|
returns the
|
|
.Vt pfil_head
|
|
structure for the given key/dlt.
|
|
The
|
|
.Fn pfil_add_hook
|
|
and
|
|
.Fn pfil_remove_hook
|
|
functions
|
|
return 0 if successful.
|
|
If called with flag
|
|
.Dv PFIL_WAITOK ,
|
|
.Fn pfil_remove_hook
|
|
is expected to always succeed.
|
|
.Pp
|
|
The
|
|
.Fn pfil_head_unregister
|
|
function
|
|
might sleep!
|
|
.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
|
|
Fine-grained locking was added in
|
|
.Fx 5.2 .
|
|
.Sh BUGS
|
|
The
|
|
.Fn pfil_hook_get
|
|
function
|
|
is only safe for internal use.
|
|
.Pp
|
|
.Fx
|
|
implements only hooks for
|
|
.Dv AF_INET
|
|
and
|
|
.Dv AF_INET6 .
|
|
Packets diverted through these hooks have data in
|
|
host byte order contrary to the above statements.
|
|
.Pp
|
|
The
|
|
.Xr bridge 4
|
|
diverts inbound
|
|
.Dv AF_INET
|
|
traffic, but contrary to the above
|
|
statements, the data is provided in host byte order.
|
|
.Pp
|
|
When a
|
|
.Vt pfil_head
|
|
is being modified, no traffic is diverted
|
|
(to avoid deadlock).
|
|
This means that unwanted traffic may flow for a short period
|
|
of time.
|
|
.Sh SEE ALSO
|
|
.Xr bpf 4 ,
|
|
.Xr bridge 4
|