1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2014 Ryan Zezeski
  13 .\"
  14 .Dd Nov 20, 2014
  15 .Dt HTTPFILT 7M
  16 .Os
  17 .Sh NAME
  18 .Nm httpfilt
  19 .Nd socket filter module for deferred HTTP connections
  20 .Sh DESCRIPTION
  21 The
  22 .Nm httpfilt
  23 socket filter provides deferment of
  24 .Xr accept 3SOCKET
  25 for HTTP connections. The accept call will not return until the CRLF
  26 line that designates the end of the headers has been seen, or until 8K
  27 has been buffered. Deferment assures the application that the first
  28 call to
  29 .Xr read 2 or
  30 .Xr recv 3SOCKET
  31 will not block. It reduces unnecessary switching between user and
  32 kernel.
  33 .Sh IMPLEMENTATION NOTES
  34 It's important to understand that this filter only defers HTTP
  35 requests, it doesn't parse them. It's not meant to be an in-kernel
  36 HTTP server, rejecting or accepting requests. That's still the job of
  37 the application. It simply does its best to buffer data until the HTTP
  38 request is complete, sans the body.
  39 .Pp
  40 As the filter does not implement a complete HTTP request parser it can
  41 be fooled. It is possible to create bogus requests which keep the
  42 socket deferred in the kernel indefinitely. These deferred sockets are
  43 allowed to stay open until the socketfilter system feels pressure and
  44 starts closing them.
  45 .Pp
  46 If you want to avoid indefinite deferral then
  47 .Xr datafilt 7M
  48 may be used instead. It defers the connection until at least one byte
  49 arrives.
  50 .Sh EXAMPLES
  51 .Ss Example 1
  52 Enable HTTP deferment on the listening socket.
  53 .Bd -literal
  54     char filt[] = "httpfilt";
  55     setsockopt(lsock, SOL_FILTER, FIL_ATTACH, filt, strlen(filt) + 1);
  56 .Ed
  57 .Ss Example 2
  58 Disable HTTP deferment on the listening socket.
  59 .Bd -literal
  60     char filt[] = "httpfilt";
  61     setsockopt(lsock, SOL_FILTER, FIL_DETACH, filt, strlen(filt) + 1);
  62 .Ed
  63 .Sh SEE ALSO
  64 .Xr setsockopt 3SOCKET ,
  65 .Xr datafilt 7M