1.\" $NetBSD: accept_filter.9,v 1.5 2009/04/10 18:15:26 wiz Exp $ 2.\" 3.\" Copyright (c) 2000 Alfred Perlstein 4.\" 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.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $FreeBSD: src/share/man/man9/accept_filter.9,v 1.13 2004/06/16 08:33:57 ru Exp $ 28.\" " 29.Dd November 12, 2008 30.Dt ACCEPT_FILTER 9 31.Os 32.Sh NAME 33.Nm accept_filter , 34.Nm accept_filt_add , 35.Nm accept_filt_del , 36.Nm accept_filt_generic_mod_event , 37.Nm accept_filt_get 38.Nd filter incoming connections 39.Sh SYNOPSIS 40.Fd #define ACCEPT_FILTER_MOD 41.In sys/param.h 42.In sys/kernel.h 43.In sys/sysctl.h 44.In sys/signalvar.h 45.In sys/socketvar.h 46.In netinet/accept_filter.h 47.Ft int 48.Fn accept_filt_add "struct accept_filter *filt" 49.Ft int 50.Fn accept_filt_del "char *name" 51.Ft int 52.Fn accept_filt_generic_mod_event "module_t mod" "int event" "void *data" 53.Ft struct accept_filter * 54.Fn accept_filt_get "char *name" 55.Sh DESCRIPTION 56Accept filters allow an application to request 57that the kernel pre-process incoming connections. 58This manual page describes the kernel interface for accept filters. 59User applications request accept filters via the 60.Xr setsockopt 2 61system call, passing in an 62.Fa optname 63of 64.Dv SO_ACCEPTFILTER . 65.Sh IMPLEMENTATION NOTES 66A module that wants to be an accept filter 67must provide a 68.Vt "struct accept_filter" 69to the system: 70.Bd -literal 71struct accept_filter { 72 char accf_name[16]; 73 void (*accf_callback)(struct socket *so, void *arg, int waitflag); 74 void * (*accf_create)(struct socket *so, char *arg); 75 void (*accf_destroy)(struct socket *so); 76 SLIST_ENTRY(accept_filter) accf_next; /* next on the list */ 77}; 78.Ed 79.Pp 80The module should register it with the function 81.Fn accept_filt_add , 82passing a pointer to a 83.Vt "struct accept_filter" , 84allocated with 85.Xr malloc 9 . 86.Pp 87The accept filters currently provided with 88.Nx 89.Xr ( accf_data 9 90and 91.Xr accf_http 9 ) 92are implemented as pseudo-devices, but an accept filter may use any 93supported means of initializing and registering itself at system startup 94or later, including the module framework if supported 95by the running kernel. 96.Pp 97The fields of 98.Vt "struct accept_filter" 99are as follows: 100.Bl -tag -width ".Va accf_callback" 101.It Va accf_name 102Name of the filter; 103this is how it will be accessed from userland. 104.It Va accf_callback 105The callback that the kernel will do 106once the connection is established. 107It is the same as a socket upcall 108and will be called when the connection is established 109and whenever new data arrives on the socket, 110unless the callback modifies the socket's flags. 111.It Va accf_create 112Called whenever a 113.Xr setsockopt 2 114installs the filter onto 115a listening socket. 116.It Va accf_destroy 117Called whenever the user removes the accept filter on the socket. 118.El 119.Pp 120The 121.Fn accept_filt_del 122function 123passed the same string used in 124.Va accept_filter.accf_name 125during registration with 126.Fn accept_filt_add , 127the kernel will then disallow and further userland use of the filter. 128.Pp 129The 130.Fn accept_filt_get 131function is used internally to locate which accept filter to use via the 132.Xr setsockopt 2 133system call. 134.Pp 135The 136.Fn accept_filt_generic_mod_event 137function can be used by accept filters which are loadable kernel modules 138to add and delete themselves. 139.Sh SEE ALSO 140.Xr setsockopt 2 , 141.Xr accf_data 9 , 142.Xr accf_http 9 , 143.Xr malloc 9 144.Sh HISTORY 145The accept filter mechanism was introduced in 146.Fx 4.0 . 147It was ported to 148.Nx 149by Coyote Point Systems, Inc. and appeared in 150.Nx 5.0 . 151.Sh AUTHORS 152This manual page was written by 153.An -nosplit 154.An Alfred Perlstein , 155.An Sheldon Hearn , 156and 157.An Jeroen Ruigrok van der Werven . 158.Pp 159The accept filter concept was pioneered by 160.An David Filo 161at Yahoo!\& 162and refined to be a loadable module system by 163.An Alfred Perlstein . 164