.\" $NetBSD: accept_filter.9,v 1.5 2009/04/10 18:15:26 wiz Exp $
.\"
.\" Copyright (c) 2000 Alfred Perlstein
.\"
.\" 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 DEVELOPERS ``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 DEVELOPERS 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: src/share/man/man9/accept_filter.9,v 1.13 2004/06/16 08:33:57 ru Exp $
.\" "
.Dd November 12, 2008
.Dt ACCEPT_FILTER 9
.Os
.Sh NAME
.Nm accept_filter ,
.Nm accept_filt_add ,
.Nm accept_filt_del ,
.Nm accept_filt_generic_mod_event ,
.Nm accept_filt_get
.Nd filter incoming connections
.Sh SYNOPSIS
.Fd #define ACCEPT_FILTER_MOD
.In sys/param.h
.In sys/kernel.h
.In sys/sysctl.h
.In sys/signalvar.h
.In sys/socketvar.h
.In netinet/accept_filter.h
.Ft int
.Fn accept_filt_add "struct accept_filter *filt"
.Ft int
.Fn accept_filt_del "char *name"
.Ft int
.Fn accept_filt_generic_mod_event "module_t mod" "int event" "void *data"
.Ft struct accept_filter *
.Fn accept_filt_get "char *name"
.Sh DESCRIPTION
Accept filters allow an application to request
that the kernel pre-process incoming connections.
This manual page describes the kernel interface for accept filters.
User applications request accept filters via the
.Xr setsockopt 2
system call, passing in an
.Fa optname
of
.Dv SO_ACCEPTFILTER .
.Sh IMPLEMENTATION NOTES
A module that wants to be an accept filter
must provide a
.Vt "struct accept_filter"
to the system:
.Bd -literal
struct accept_filter {
	char	accf_name[16];
	void	(*accf_callback)(struct socket *so, void *arg, int waitflag);
	void *	(*accf_create)(struct socket *so, char *arg);
	void	(*accf_destroy)(struct socket *so);
	SLIST_ENTRY(accept_filter) accf_next;	/* next on the list */
};
.Ed
.Pp
The module should register it with the function
.Fn accept_filt_add ,
passing a pointer to a
.Vt "struct accept_filter" ,
allocated with
.Xr malloc 9 .
.Pp
The accept filters currently provided with
.Nx
.Xr ( accf_data 9
and
.Xr accf_http 9 )
are implemented as pseudo-devices, but an accept filter may use any
supported means of initializing and registering itself at system startup
or later, including the module framework if supported
by the running kernel.
.Pp
The fields of
.Vt "struct accept_filter"
are as follows:
.Bl -tag -width ".Va accf_callback"
.It Va accf_name
Name of the filter;
this is how it will be accessed from userland.
.It Va accf_callback
The callback that the kernel will do
once the connection is established.
It is the same as a socket upcall
and will be called when the connection is established
and whenever new data arrives on the socket,
unless the callback modifies the socket's flags.
.It Va accf_create
Called whenever a
.Xr setsockopt 2
installs the filter onto
a listening socket.
.It Va accf_destroy
Called whenever the user removes the accept filter on the socket.
.El
.Pp
The
.Fn accept_filt_del
function
passed the same string used in
.Va accept_filter.accf_name
during registration with
.Fn accept_filt_add ,
the kernel will then disallow and further userland use of the filter.
.Pp
The
.Fn accept_filt_get
function is used internally to locate which accept filter to use via the
.Xr setsockopt 2
system call.
.Pp
The
.Fn accept_filt_generic_mod_event
function can be used by accept filters which are loadable kernel modules
to add and delete themselves.
.Sh SEE ALSO
.Xr setsockopt 2 ,
.Xr accf_data 9 ,
.Xr accf_http 9 ,
.Xr malloc 9
.Sh HISTORY
The accept filter mechanism was introduced in
.Fx 4.0 .
It was ported to
.Nx
by Coyote Point Systems, Inc. and appeared in
.Nx 5.0 .
.Sh AUTHORS
This manual page was written by
.An -nosplit
.An Alfred Perlstein ,
.An Sheldon Hearn ,
and
.An Jeroen Ruigrok van der Werven .
.Pp
The accept filter concept was pioneered by
.An David Filo
at Yahoo!\&
and refined to be a loadable module system by
.An Alfred Perlstein .