share/man/man9/accept_filter.9

   1 .\" $NetBSD$
   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
  56 Accept filters allow an application to request
  57 that the kernel pre-process incoming connections.
  58 This manual page describes the kernel interface for accept filters.
  59 User applications request accept filters via the
  60 .Xr setsockopt 2
  61 system call, passing in an
  62 .Fa optname
  63 of
  64 .Dv SO_ACCEPTFILTER .
  65 .Sh IMPLEMENTATION NOTES
  66 A module that wants to be an accept filter
  67 must provide a
  68 .Vt "struct accept_filter"
  69 to the system:
  70 .Bd -literal
  71 struct 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
  80 The module should register it with the function
  81 .Fn accept_filt_add ,
  82 passing a pointer to a
  83 .Vt "struct accept_filter" ,
  84 allocated with
  85 .Xr malloc 9 .
  86 .Pp
  87 The accept filters currently provided with
  88 .Nx
  89 .Xr ( accf_data 9
  90 and
  91 .Xr accf_http 9 )
  92 are implemented as pseudo-devices, but an accept filter may use any
  93 supported means of initializing and registering itself at system startup
  94 or later, including the module framework if supported
  95 by the running kernel.
  96 .Pp
  97 The fields of
  98 .Vt "struct accept_filter"
  99 are as follows:
 100 .Bl -tag -width ".Va accf_callback"
 101 .It Va accf_name
 102 Name of the filter;
 103 this is how it will be accessed from userland.
 104 .It Va accf_callback
 105 The callback that the kernel will do
 106 once the connection is established.
 107 It is the same as a socket upcall
 108 and will be called when the connection is established
 109 and whenever new data arrives on the socket,
 110 unless the callback modifies the socket's flags.
 111 .It Va accf_create
 112 Called whenever a
 113 .Xr setsockopt 2
 114 installs the filter onto
 115 a listening socket.
 116 .It Va accf_destroy
 117 Called whenever the user removes the accept filter on the socket.
 118 .El
 119 .Pp
 120 The
 121 .Fn accept_filt_del
 122 function
 123 passed the same string used in
 124 .Va accept_filter.accf_name
 125 during registration with
 126 .Fn accept_filt_add ,
 127 the kernel will then disallow and further userland use of the filter.
 128 .Pp
 129 The
 130 .Fn accept_filt_get
 131 function is used internally to locate which accept filter to use via the
 132 .Xr setsockopt 2
 133 system call.
 134 .Pp
 135 The
 136 .Fn accept_filt_generic_mod_event
 137 function can be used by accept filters which are loadable kernel modules
 138 to 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
 145 The accept filter mechanism was introduced in
 146 .Fx 4.0 .
 147 It was ported to
 148 .Nx
 149 by Coyote Point Systems, Inc. and appeared in
 150 .Nx 5.0 .
 151 .Sh AUTHORS
 152 This manual page was written by
 153 .An -nosplit
 154 .An Alfred Perlstein ,
 155 .An Sheldon Hearn ,
 156 and
 157 .An Jeroen Ruigrok van der Werven .
 158 .Pp
 159 The accept filter concept was pioneered by
 160 .An David Filo
 161 at Yahoo!\&
 162 and refined to be a loadable module system by
 163 .An Alfred Perlstein .